(superceded) Implementing Codat's no-code merchant configuration

🚧

Sync for Commerce: beta testing

Note that Sync for Commerce is in beta testing.

Before you start

Before you start, retrieve the following details:

The `key` of the accounting integration selected by the merchant which you obtained at [Accounting platform selection](doc:sync-platform-selection) stage. * The ID that you use to identify the merchant in your internal system, hereafter referred to as ‘yourMerchantId’. * The `clientId` of the client (Codat instance) that you wish to use to implement the no-code merchant configuration. Contact your account manager to get the `clientId`.

These details are used to form the no-code merchant configuration 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.

Redirecting the merchant to the no-code solution

  1. After the merchant selects their accounting platform, they should be immediately redirected to a secure URL leading them to the Sync for Commerce flow. To retrieve the secure URL, make the following request:
GET config/sync/commerce/lqai/{key}/start?merchantIdentifier={yourMerchantId}

Example response:

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

Codat expects the merchantIdentifier to always be unique.

For example, if a merchant has successfully completed the configuration journey, and you create another syncFlowUrl using the same merchant identifier, the redirect will take the user back to the sync settings page where they would be able to alter their preferences.

🚧

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.

  1. Redirect the merchant to the constructed URL. Note that the 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, generate a new URL with a new one-time password and direct the merchant to it.
  2. After the merchant follows the provided link, they are redirected to the previously selected accounting platform for authorization.
  3. Upon successful authorization, the merchant is presented with Codat’s white-labeled configuration flow and is prompted to configure the data sync. For the best experience, we recommend that you set up your logo and primary color.

Every time a user goes through the no-code 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.
  1. To allow the merchants to review their connection, present them with the same URL as the one used for the original setup (see step 1 of this guide). It will direct the merchant to the Sync settings page where they will be able to review the details of the last sync or 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.
  2. Before you move on to the next stage, Data pushing, the configuration must be complete. You can check the configuration status following the steps below.

Checking the configuration status

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={yourMerchantId}

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.

Customizing your no-code solution

Sync for Commerce no-code 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 almost every text field of the flow, including the text displayed on buttons. 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. To find the data-textkey for a field, refer to the screenshots below. On the screenshots, the text values are replaced by the corresponding data-textkey values.

🚧

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.

Sales Accounts screen of the Sync for Commerce flow (click to expand).Sales Accounts screen of the Sync for Commerce flow (click to expand).

Sales Accounts screen of the Sync for Commerce flow (click to expand).

Sales Accounts screen with `data-textkey` values in place of the corresponding text (click to expand).Sales Accounts screen with `data-textkey` values in place of the corresponding text (click to expand).

Sales Accounts screen with data-textkey values in place of the corresponding text (click to expand).

Sales Tax rates screen of the Sync for Commerce flow (click to expand).Sales Tax rates screen of the Sync for Commerce flow (click to expand).

Sales Tax rates screen of the Sync for Commerce flow (click to expand).

Sales Tax rates screen with `data-textkey` values in place of the corresponding text (click to expand).Sales Tax rates screen with `data-textkey` values in place of the corresponding text (click to expand).

Sales Tax rates screen with data-textkey values in place of the corresponding text (click to expand).

Sales Other screen of the Sync for Commerce flow (click to expand).Sales Other screen of the Sync for Commerce flow (click to expand).

Sales Other screen of the Sync for Commerce flow (click to expand).

Sales Other screen with `data-textkey` values in place of the corresponding text (click to expand).Sales Other screen with `data-textkey` values in place of the corresponding text (click to expand).

Sales Other screen with data-textkey values in place of the corresponding text (click to expand).

Refer to the screenshots below to update the text fields in the Fees section of the Sync for Commerce UI flow:

Fees Accounts screen of the Sync for Commerce flow (click to expand).Fees Accounts screen of the Sync for Commerce flow (click to expand).

Fees Accounts screen of the Sync for Commerce flow (click to expand).

Fees Accounts screen with `data-textkey` values in place of the corresponding text (click to expand).Fees Accounts screen with `data-textkey` values in place of the corresponding text (click to expand).

Fees Accounts screen with data-textkey values in place of the corresponding text (click to expand).

Refer to the screenshots below to update the text fields in the Payments section of the Sync for Commerce UI flow:

Payments Accounts screen of the Sync for Commerce flow (click to expand).Payments Accounts screen of the Sync for Commerce flow (click to expand).

Payments Accounts screen of the Sync for Commerce flow (click to expand).

Payments Accounts screen with `data-textkey` values in place of the corresponding text (click to expand).Payments Accounts screen with `data-textkey` values in place of the corresponding text (click to expand).

Payments Accounts screen with data-textkey values in place of the corresponding text (click to expand).

Refer to the screenshots below to update the text fields in the Sync schedule section of the Sync for Commerce UI flow:

Sync Schedule screen of the Sync for Commerce flow (click to expand).Sync Schedule screen of the Sync for Commerce flow (click to expand).

Sync Schedule screen of the Sync for Commerce flow (click to expand).


Did this page help you?