This is a staging build of the docs
We've reorganized our products to make building with Codat easier than ever
Skip to main content

Merchant configuration

Enable merchants to connect their systems and specify how they want their sales data to be synchronized into their accounting package

Our Sync configuration UI allows merchants to authenticate to gain access to their commerce platform and accounting package and records the merchants' sales data synchronization preferences. It can be customized to integrate seamlessly into your software.

Merchant configuration​

Once a merchant authorized access to their systems, they can use the Sync configuration UI to perform the following configuration:

  • Decide whether to handle sales as invoices or journal entries within their accounting package.
  • Schedule the start date and time from which sales data should be synchronized.
  • Configure how their sales should be accounted for, including:
    • Aggregation of sales by product category,
    • Tracking of sales by location,
    • Handling of gift cards, gratuities, and refunds,
    • Tax totals.
  • Configure how to account for payments for each payment type you support and your customer uses.
  • Configure how to account for payment fees.

Mapping sales, payments, and fees​

The configuration of accounting for sales, payments, and fees happens in the form of mapping.

First, Codat retrieves relevant data from the connected commerce platform and accounting package.

The UI then requests the user to map different types of sales, payments, and fees to the relevant accounts in their accounting system. For example, they may map sales of food to the "Food income" account and map payment fees to the "Payment costs" account.

The Sync configuration UI also allows your customer to create a new account in their accounting package where necessary.

Implementing your own UI

You can implement your own UI to capture a merchant's desired sync configuration using our API. Consult your Solutions Engineer for support in doing this.

Customize the Sync configuration UI​

Customization options available for the configuration UI include:

  • Branding, including your company name, logo, icon and brand colours
  • Text content of the Sync configuration UI
Further UI customization

This section describes most commonly implemented Sync configuration UI customization. However, further customization is possible. Please consult your Solutions Engineer for details.

Branding customization​

You can configure your branding options in the Branding settings section of the Codat Portal. Learn more about the branding options available to you in our Company branding documentation.

Text content customization​

Updating the text fields helps ensure that your users clearly understand how to correctly configure their sales data synchronization and how exactly that data will be synced.

UI element customization​

The Sync configuration UI is organised in 6 stages, each with customizable text elements:

StageAction required from user
1. Connection to commerce systemAuthenticate with commerce platform
2. Connection to accounting systemAuthenticate with accounting package
3. Sales synchronization configurationConfigure how sales should be accounted for
4. Fees synchronization configurationConfigure how fees should be accounted for
5. Payments synchronization configurationConfigure how payments should be accounted for
6. Sync schedule configurationSet start date and time for sales data synchronization

Each customizable element is identified by its data-textkey. You can customize the following elements:

  • Main title
  • Checkbox options
  • Previous and Next buttons on each stage
  • Stage title, description, and the description of the required field indicator
  • Subsection titles and descriptions within each stage
  • Dropdown labels for sales, fees, and payments configuration (stages 3, 4, and 5)

You can also call the Get preferences for text fields endpoint to retrieve the full list of customizable elements:

GET sync/commerce/config/ui/text

This returns all customizable UI elements with the current text configured for each. You can also find the full list of elements and their default values in the Summary of data-textkeys and default values section below.

{
  "configure-setupSidebar-checkboxes-sales": "Set up sales",
  "configure-setupSidebar-checkboxes-fees": "Set up fees",
  "configure-setupSidebar-checkboxes-payments": "Set up payments",
  ... // etc.
}

To update the text values via our API, use the Update preferences for text fields endpoint and include the desired text strings in the request body for each data-textkey:

PATCH sync/commerce/config/ui/text

Example request body:

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

// Display an empty string
{
   "data-textkey": ""
}

// Use the default value
{
   "data-textkey": null
}
Summary of text elements and default values​
Default valuedata-textkey value
Set up Sync to {platform name}configure-setupSidebar-title

Customizing dropdowns​

When surfacing the Sales, Fees, and Payments synchronization configuration to your merchant (stages 3, 4, and 5), it is likely that not all dropdown options will be applicable to your product.

All dropdown list options are shown to your merchants by default, but you can choose to only display those relevant to you.

You can get a full list of dropdown items by calling the List visible accounts endpoint:

GET clients/{clientId}/config/ui/accounts/platform/{platformKey}

This will return all dropdown items, identified by their account-key.

{
    "visibleAccounts": [
         "sales-accounts-sales",
         "sales-accounts-refund",
         ... // etc.
    ]
}

You can update the list of dropdown items displaued to your merchant by calling the Update visible accounts endpoint:

POST sync/commerce/config/ui/accounts/platform/{commerceKey}
Example request body for managing dropdown item visibility
//To update the visible dropdown items to the ones provided in the request body:
{
    "visibleAccounts": [
         "account-key-1",
         "account-key-2"
    ]
}

//To revert to the default settings and show all dropdown items:
{}

//To show only the dropdown items that are required:
{
  "visibleAccounts": []
}
Summary of dropdown items available for customization​
Display name (unless customized)account-key
Sales*sales-accounts-sales
Refund*sales-accounts-refund
Gratuitysales-accounts-gratuity
Prepaidsales-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

account-keys marked with an '*' must be shown to users.

Was this page useful?
❤️
👍
🤔
👎
😭

Contents

Suggest edits