Building for a typical user journey

The user experience for end users related to the synchronisation of their commerce data to their accounting software.

Creating a Codat company

A Codat company should be created for each merchant you would like to synchronise data for. This is achieved using the Create company endpoint.

Connecting accounting software

A merchant must authorise the connection to their accounting software in order for the synchronisation to be able to function.

Create a data connection

A data connection should be created for the company in order to allow the merchant to link their accounting software.

  1. Identify the platformKey for the required accounting integration.
    • The integrations endpoint can be used to provide a list of available integrations, filtered by enabled = true and sourceType = Accounting.
    • Typically clients will wish to display this list of accounting packages to the merchant in their application.
  2. Create a data connection
    • The connections endpoint should be used, providing the platformKey (note that this will need to be in string quotes) of the required accounting integration from step 1 above and the companyId of the merchant.
  1. Redirect the user to authorise their accounting software
    • The user should be navigated to the linkUrl on the response from the API call.
  2. Once the user has authorised the connection they will be returned to your application configured in the Codat Portal.

Connecting commerce software

The synchronisation requires a source of "commerce" data which should be synchronised with the accounting software linked (above).

There are two options for the data source:

  1. Create a data connection to one of the integrations of type commerce already supported by Codat.
  2. Create a data connection to one of the integrations of type 'upload` to which you can push your own commerce data in the Codat standard format.

Merchant configuration

Once connections with sources of accounting data and commerce data have been established, the user will need to setup their Configuration for the synchronisation.

Codat clients should create a page on which the user is able to manage their configuration. The page should be powered by the merchant configuration endpoint.

The user should then configure the integration, by matching the required types of the commerce integration with accounts in their accounting software.

Recommended settings

We recommend our clients to build an option to populate the configuration with recommended settings. This will appeal to those merchants who are less accounting-savvy.

If an account doesn't exist it can be created using the New Account Endpoints. We have found the best user experience for this functionality is to create a modal dialogue box.

Saving configuration

A call should be made to the save the config endpoint. .

Updating configuration

We recommend clients allow merchants to access their configuration page at any time to view
or make changes to the configuration.

Changes to configuration are made using the save the config endpoint.

Viewing synchronisation status

In addition to viewing their configuration, merchants will likely want to be shown the status of their synchronisation and details on when the last synchronisation occurred. This information can be obtained from the sync status endpoint.

Updated 3 months ago

Building for a typical user journey


The user experience for end users related to the synchronisation of their commerce data to their accounting software.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.