Implement the Sync Flow

Learn how to implement our Sync for Commerce UI that allows your merchant to configure their desired data mapping.

Before Codat can accept the data from your merchant, the merchant has to establish the way they want the data to be mapped to their accounting platform, as well as the synchronization schedule.

Sync Flow handles this for you. To use it for merchant configuration, you need to complete the following steps:

  1. Retrieve the Sync Flow URL
  2. Redirect the merchant to the Sync Flow URL
  3. Allow the merchant to review and modify their connection via Sync Settings
  4. (Optional) Check the configuration status

You can also customize your Sync Flow.

Before you start

We recommend that you keep the following details at hand:

  • The key of the accounting platform selected by the merchant. You can get the key by following the instructions in Accounting platform selection.
  • The name that you use for the merchant in your internal system, hereafter referred to as merchantIdentifier.

These details are used to form the Sync Flow URL.

📘

Use our Swagger to follow this guide

All the endpoints mentioned in this guide are available in our Sync for Commerce Swagger. You can use it to try the API requests from this guide directly in your browser. Before you use Swagger, make sure to authenticate.

Step 1: Retrieve the Sync Flow URL

After the merchant selects their accounting platform, they should be immediately redirected to a secure URL leading them to the Sync Flow. To retrieve the secure URL, make the following request:

GET config/sync/commerce/lqai/{key}/start?merchantIdentifier={merchantIdentifier}

Example response:

{ 
    "url":”https://sync-flow.codat.io/{clientId}/lqai/gbol/start?otp={6digitOneTimePassword}”
}

Codat expects the merchantIdentifier to always be unique.

🚧

One-time password

The URL that you will receive in response includes a one-time password which will expire after 30 seconds. Using a one-time password eliminates the possibility of malicious third parties accessing the Sync Flow and ensures a high level of security for your merchants.

Retrieve the Sync Flow URL with a custom redirect

By default, upon completion of the Sync Flow a merchant is presented with a success message over the Sync Settings page.

Alternatively, you can redirect the merchant to a custom URL.

To do that, add a query parameter with redirectUrl as a property name and the absolute URL as a value to the GET request described in Step 1.

The resulting Sync Flow URL will include the redirect URL as shown in this example:

{
    "url": "https://sync-flow.codat.io/06de067c-1d6c-416a-8e61-676e6c135e68/lqai/gbol/start?merchantIdentifier=CoPay&otp=615853&redirectUrl=app.codat.io"
}

Step 2: Redirect the merchant to the Sync Flow URL

  1. Redirect the merchant to the constructed URL.

🚧

The Sync Flow URL has a 30-second limit of validity, so make sure the merchant accesses the URL within that limit. Otherwise, their access will be restricted with a 401 error. In this scenario, you can generate a new URL with a new one-time password and direct the merchant to it.

  1. After the merchant follows the provided link, they are redirected to the previously selected accounting platform for authorization.
  2. Upon successful authorization, the merchant is presented with Codat’s white-labeled configuration flow and is prompted to configure the data synchronization:
    • Choose which accounts within their accounting platform to push the data into
    • Link tax rates from their accounting platform to those used for their eCommerce or POS data
    • Schedule the start date, start time, and frequency of the regular data synchronization
    • Set up the default invoice status
    • Set up the data grouping period

To provide your merchants with a branded experience, we recommend that you set up your logo and primary color.

📘

Every time a user goes through the Sync Flow, the following happens:

  • A Codat company is created. Its name value is populated with the merchant ID value provided via the Sync Flow URL query parameters.
  • Commerce and accounting data connections are established.

Step 3: Allow the merchant to review and modify their connection

To allow the merchants to review and modify their connection, present them with the same URL as the one used for the original setup. It will direct the merchant to the Sync settings page where they will be able to:

  • Enable and disable data synchronization
  • Schedule the start date, start time, and frequency of the regular data synchronization
  • See the date and time of the last sync and the next one
  • Review and change which accounts within their accounting platform to push the data into (see Mapping specifications for more information)
  • Review and change the tax rates mapping
  • Set up the default invoice status
  • Set up the data grouping period
  • Sever the connection to their accounting platform

🚧

In case the merchant severs the connection, the next scheduled data sync will fail, and no further data syncs will be attempted.

Step 4: (Optional) Check the configuration status

❗️

Before you can push the merchant's data to Codat, the configuration must be complete.

To establish whether a merchant has successfully completed their commerce data configuration, perform the following steps:

  1. Retrieve the ID of the company created for your merchant:
GET companies?page=1&pageSize=100?query=name={merchantIdentifier}

This request returns information about the company. It should have both accounting and commerce data connections present and with the linked status. Retain the value of the company id which we will refer to as the companyId.

  1. Using the companyId, view the status of the merchant's configuration:
GET config/companies/{companyId}/sync/commerce

If the merchant has successfully configured their preferences and has enabled sync, then both the enabled and configured parameters will be set to true. This means you can start pushing the commerce data to this company.

Customize the Sync Flow

🚧

This section includes instructions on how to update the text values in the Sync Flow and change visibility of feature categories (accounts).

If you're looking to disable a feature (e.g., Fees), contact your Account Manager.

Sync Flow is a white-labeled solution that can be tailored to fit the needs of your clients.

To create a branded experience, you can:

  • Set up your company name, logo, and icon via the Link settings.
  • Update the text fields of the flow. Updating the text fields helps ensure that your users clearly understand what they are sharing via the Sync for Commerce flow and which accounts they should choose to ensure it works correctly.

How to update the text values

You can update every text field of the Sync Flow, including:

619619 534534 575575
  • Feature title, feature description, and required field indicator description (Sales, Fees, Payments)
623623
  • Feature categories title, feature categories title description, and feature categories (Sales, Fees, Payments)
11691169

Keep in mind that this update will only affect the UI.

To get a complete list of all the customizable text fields and their values perform the following request:

GET sync/commerce/config/ui/text

To update, remove or reset a text value, use the following request:

PATCH sync/commerce/config/ui/text

Request body:

// Updates the text value to the specified string
{
   "data-textkey": "A new value"
}

// Removes the value from the UI
{
   "data-textkey": ""
}

// Resets the value to default
{
   "data-textkey": null
}

In the request above, the data-textkey is the key of the field that you want to configure.

You can find the data-textkey values in the tables below.

🚧

Update the text fields consistently

We recommend grouping your updates to ensure that related values are updated consistently. A feature name (e.g., Sales) appears as a check box item in the left pane (Set up sales) and as the main title on the right side of the window (Sales), so it is important to update both configure-setupSidebar-checkboxes-sales and configure-content-sales-title.

Main title

Default value

data-textkey value

Set up Sync to {platform name}

configure-setupSidebar-title

Checkbox captions

Default value

data-textkey value

Connect to {Commerce platform name}

configure-setupSidebar-checkboxes-connectToCommerce

Connect to {Accounting platform name}

configure-setupSidebar-checkboxes-connectToAccounting

Set up sales

configure-setupSidebar-checkboxes-sales

Set up fees

configure-setupSidebar-checkboxes-fees

Set up payments

configure-setupSidebar-checkboxes-payments

Set up sync schedule

configure-setupSidebar=checkboxes-syncSchedule

Buttons

Default value

data-textkey value

Previous

configure-misc-previousButton

Next

configure-misc-nextButton

Required field indicator description

Default value

data-textkey value

Indicates a required field

configure-required-indicator

Sales title and description

Default value

data-textkey value

Sales

configure-content-sales-title

Sales title description:
no value by default.

configure-content-sales-description

Sales feature categories title and description

Default value

data-textkey value

Accounts

configure-content-sales-accounts-title

Configure accounts mapping from
{commerce platform name} to
{accounting platform name}.

configure-content-sales-accounts-description

Tax rates

configure-content-sales-taxRates-title

Configure tax rates mapping from
{commerce platform name} to
{accounting platform name}.

configure-content-sales-taxRates-description

Other

configure-content-sales-other-title

Other title description: no value by default.

configure-content-sales-other-description

Sales feature categories

Default value

data-textkey value

Sales

configure-content-sales-accounts-entries-sales

Refunds

configure-content-sales-accounts-entries-refund

Gratuity

configure-content-sales-accounts-entries-gratuity

Prepaid

configure-content-sales-accounts-entries-prepaid

0% tax rate

configure-content-sales-accounts-taxRates-entries-0

5% tax rate

configure-content-sales-accounts-taxRates-entries-10

10% tax rate

configure-content-sales-accounts-taxRates-entries-15

20% tax rate

configure-content-sales-accounts-taxRates-entries-20

Invoice status

configure-content-sales-other-entries-invoiceStatus

Grouping period

configure-content-sales-other-entries-groupingPeriod

Fees title and description

Default value

data-textkey value

Fees

configure-content-fees-title

Fees title description:
no value by default.

configure-content-fees-description

Fees feature categories title and description

Default value

data-textkey value

Accounts

configure-content-fees-accounts-title

Configure accounts mapping from
{commerce platform name} to
{accounting platform name}.

configure-content-fees-accounts-description

Fees feature categories

Default value

data-textkey value

Payment fee

configure-content-fees-accounts-entries-paymentFee

Payment fee refund

configure-content-fees-accounts-entries-paymentFeeRefund

Loan

configure-content-fees-accounts-entries-loan

Loan payment

configure-content-fees-accounts-entries-loanPayment

Loan fee

configure-content-fees-accounts-entries-loanFee

Cashback

configure-content-fees-accounts-entries-cashback

Payments title and description

Default value

data-textkey value

Payments

configure-content-payments-title

Payments title description:
no value by default.

configure-content-payments-description

Payments feature categories

Default value

data-textkey value

Card

configure-content-payments-accounts-entries-card

Cash

configure-content-payments-accounts-entries-cash

Invoice

configure-content-payments-accounts-entries-invoice

Online card

configure-content-payments-accounts-entries-onlineCard

Payout

configure-content-payments-accounts-entries-payout

Custom

configure-content-payments-accounts-entries-custom

Store credit

configure-content-payments-accounts-entries-storeCredit

Paypal

configure-content-payments-accounts-entries-paypal

Paypal qr

configure-content-payments-accounts-entries-paypalQr

Mobile

configure-content-payments-accounts-entries-mobile

Vipps

configure-content-payments-accounts-entries-vipps

Swish

configure-content-payments-accounts-entries-swish

Prepaid pyment

configure-content-payments-accounts-entries-prepaidPayment

Manual

configure-content-payments-accounts-entries-manual

How to change the visibility of feature categories (accounts)

To update the visibility of feature categories for a commerce platform, perform the following request:

POST sync/commerce/config/ui/accounts/platform/{commerceKey}

//Request body:
//To update the visible feature categories to the ones provided in the request body:
{
    "visibleAccounts": [
         "account-key-1",
         "account-key-2"
    ]
}

//To revert to the default settings and show all feature categories:
{}

//To show only the fields that are required:
{
  "visibleAccounts": []
}

In the request above, the commerceKey is the Codat platform key of the selected commerce platform. You can find a list of keys for the supported platforms in the Accounting platform selection section.
To find the account-key, consult the tables below. Note that fields marked with an '*' cannot be removed.

Sales feature categories

Default value

account-key

Sales*

sales-accounts-sales

Refund*

sales-accounts-refunds

Gratuity

sales-accounts-gratuity

Prepaid

sales-accounts-prepaid

0% tax rate*

sales-taxRates-0

5% tax rate*

sales-taxRates-5

10% tax rate*

sales-taxRates-10

20% tax rate*

sales-taxRates-20

Invoice status*

sales-other-invoiceStatus

Grouping period*

sales-other-groupingPeriod

Fees feature categories

Default value

account-key

Payment fee

fees-accounts-paymentFee

Payment fee refund

fees-accounts-paymentFeeRefund

Loan

fees-accounts-loan

Loan payment

fees-accounts-loanPayment

Loan fee

fees-accounts-loanFee

Cashback

fees-accounts-cashback

Payments feature categories

Default value

account-key

Card*

payments-accounts-card

Cash

payments-accounts-cash

Invoice

payments-accounts-invoice

Online card

payments-accounts-onlineCard

Payout

payments-accounts-payout

Custom

payments-accounts-custom

Store credit

payments-accounts-storeCredit

Paypal

payments-accounts-paypal

Paypal qr

payments-accounts-paypalQr

Mobile

payments-accounts-mobile

Vipps

payments-accounts-vipps

Swish

payments-accounts-swish

Prepaid payment

payments-accounts-prepaidPayment

Manual

payments-accounts-manual


Did this page help you?