Building your own merchant configuration

🚧

Sync for Commerce: beta testing

Note that Sync for Commerce is in beta testing.

Building your own merchant configuration requires you to complete the following steps:

  1. Create a Codat company to push the merchant’s commerce data into and establish an accounting data connection.
  2. Enable the merchant to configure the mapping of their commerce data into their accounting platform.
  3. Enable the merchant to perform ongoing integration configuration and disable their connection.

Before you start

Before you start, prepare the following details:

  • The key of the accounting integration selected by the merchant which you obtained at the Accounting platform selection stage.
  • The ID that you use for the merchant in your internal system.

📘

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.

Creating a company and establishing a data connection

After the merchant selects the accounting platform to pull the data from, perform the following steps:

  1. Create a Codat company for the merchant:
POST /meta/companies/sync

Request body:

{
    "name": "value"
}

📘

Use your merchant ID for the company name

We recommend that you populate the name value with the ID that you use for the merchant in your internal system so that it’s easier to identify the Codat company that corresponds to your record of the merchant.

🚧

Forbidden characters

Company names may only contain letters, numbers, spaces, and the following symbols: -, ', &, @, ., ,, ?, !.

Any forbidden characters will be removed from your company name. For example, Example Company (Codat[1]) will be created as Example Company Codat1.

This API request creates a company in Codat and a respective connection representing your platform.

The response to this request includes the parameters of a newly created company, including the Codat company ID (hereafter referred to as companyId) that you will need at later stages of building your merchant configuration.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "created": "2022-03-29T18:07:13.181Z",
  "dataConnections": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "sourceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "platformName": "string",
      "linkUrl": "string",
      "status": "string",
      "lastSync": "2022-03-29T18:07:13.181Z",
      "created": "2022-03-29T18:07:13.181Z",
      "sourceType": "string",
      "dataConnectionErrors": [
        {
          "statusCode": "string",
          "statusText": "string",
          "errorMessage": "string",
          "erroredOnUtc": "2022-03-29T18:07:13.181Z"
        }
      ]
    }
  ]
}

🚧

Keep track of the companyId

It's important that you keep track of the Codat companyId that is returned at step 1:

  • It is required for the next stage of the setup, data pushing, and any time you need to synchronize data for this merchant or interact with their configuration.
  • It is required to enable disconnected merchants to reauthorize the connection to their original Codat company without losing the history of data.

Here is an example of a Codat companyId:

"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  1. Establish an accounting data connection with the company created at the previous step of this guide:
POST /meta/companies/{companyId}/connections

Request body: “key”, for example “gbol” for Xero

  1. From the response, identify the linkUrl value for the accounting platform. Direct the merchants to this linkUrl to enable them to grant access to their accounting platform. As soon as the access is provided, Codat automatically pulls all the accounting data required to enable the merchant configuration.
{
  "id": "b7898332-7886-4e27-8c34-9615a3721bbe",
  "integrationId": "0f20c943-12d0-4800-9f6c-d218f62d494c",
  "sourceId": "8a156a5a-39cb-4f9d-856e-76ef9b9a9607",
  "platformName": "Xero",
  "linkUrl": "https://link-api-uat.codat.io/companies/63e34e58-6843-4f2d-b9c5-aee32ca31f40/connections/b7898332-7886-4e27-8c34-9615a3721bbe/start",
  "status": "PendingAuth",
  "created": "2022-03-29T18:14:41Z",
  "sourceType": "Accounting"
}
  1. After the merchant completes the authorization and grants access to their accounting platform, ensure they are redirected to your data mapping configuration UI by configuring relevant redirect URLs.

Data mapping configuration

Before the merchant can move on to the data mapping configuration stage, the initial pull of their accounting data must be completed. It usually takes less than a minute to complete.

To check whether the data has been processed successfully, (GET) /meta/companies/{companyId}/pull/history/.

Use the dataType query parameter to filter the result by the data type, for example: query=dataType=bankAccounts

Here are the data types that need to be synced before the mapping configuration stage:

  • chartOfAccounts
  • taxRates
  • bankAccounts
  • suppliers
  • customers
  • company

To enable the merchant to configure their data mapping, perform the following steps:

  1. Perform this call to get the available configuration options:
GET /config/companies/{companyId}/sync/
  1. Based on these configuration options, build a UI that allows the merchant to:
  • Enable or disable each section of the synchronization
  • Choose which accounts within their accounting platform to push the data into
  • Group data based on a time period, tax rates, and any custom grouping types
  • Link tax rates from their accounting platform to those used for their eCommerce or POS data
  • Update mapping at any point in time, should the underlying data in their accounting platform change (e.g. due to account deletion)
  • Schedule the start date, start time, and frequency of the regular data synchronization

❗️

Scheduling

As sales data is typically represented on a calendar day basis, we strongly recommend scheduling the synchronization to start at 12:00 AM of your merchant’s calendar zone provided in the UTC format, rather than allowing a merchant to configure a time of their choice. For example, for UTC-2 time zone, schedule the time to 2 AM UTC.

Such an approach ensures that a full calendar day’s worth of data is synchronized, which facilitates the reconciliation of data between the merchant’s commercial and accounting platforms.

📘

You can see Codat’s merchant configuration flow for an example of a UI implementing this functionality.

  1. Update the configuration via the Create Config endpoint:
POST /config/companies/{companyId}/sync/commerce

See the Data model section for details on account mapping and validation requirements.

Ongoing configuration

Enable merchants to view or update their integration settings via the Config API.

To retrieve the current configuration and available configuration options:

GET /config/companies/{companyId}/sync/commerce

To save a new configuration based on the user’s selections:

POST /config/companies/{companyId}/sync/commerce

Disabling a data connection

Data syncs can be paused by updating the merchant’s company configuration and setting the enabled property to false:

POST /config/companies/{companyId}/sync/commerce

It is also possible to deauthorize the access to your merchant’s accounting platform using the following request:

PATCH /meta/companies/{companyId}/connections/{connectionId}

{
  "status": "Unlinked"
}

In the request above, the connectionId is the ID of the accounting data connection that you want to deauthorize that can be retrieved from:

GET meta/companies/{companyId}/connections

When you disable a data connection, the next scheduled data sync will fail, and no further data syncs will be attempted.

To restore the connection, access to the merchant’s accounting data must be restored and the data syncs should be re-enabled.


Read next
Did this page help you?