Xero mapping specification

Overview

This document provides guidelines for data mapping configuration from a commerce platform to Xero.

In Codat's Sync Flow UI, the data types are grouped under the three main features:

The document contains information about the account types supported by each feature and demonstrates the way that the data displays in the accounting platform after a successful synchronization via Sync for Commerce.

📘

Xero Account Types

In this document, we will be referencing the following account types in Xero:

  • Asset,
  • Liability,
  • Revenue, and
  • Expense.

Sales

The Sales feature represents sales made in course of a company’s normal business activities during a set period of time.

To set up Sales using the Codat Sync for Commerce UI flow, a merchant needs to complete the following steps:

  1. Select the accounts for Sales, Refunds, Gratuity, and Prepaid features from the respective dropdown lists. The lists display all the applicable accounts available on the merchant’s Xero accounting platform:
Sync UI Sales Accounts screen where you can select the accounts to use to map the commerce data.Sync UI Sales Accounts screen where you can select the accounts to use to map the commerce data.

Sync UI Sales Accounts screen where you can select the accounts to use to map the commerce data.

📘

Features display

Codat Sync for Commerce UI displays all the available features by default. However, the Sync for Commerce API allows you to disable any unsupported features in your own UI. For example, you can disable a particular payment type.

  1. Select the tax rates that they wish to apply to the data they are sending:
Sync UI Sales Tax rates screen where you can select the applicable tax rates.Sync UI Sales Tax rates screen where you can select the applicable tax rates.

Sync UI Sales Tax rates screen where you can select the applicable tax rates.

  1. Select the preferred status for invoices representing the Sales data within their accounting platform (Submitted or Draft).
  2. The grouping period is set to daily by default.
Sync UI Sales Other screen where you can set up the invoice status and the grouping period for **Sales**.Sync UI Sales Other screen where you can set up the invoice status and the grouping period for **Sales**.

Sync UI Sales Other screen where you can set up the invoice status and the grouping period for Sales.

Sales account mapping

Sales

Sales are booked on a nominal account of the Xero type Revenue. This is the account that the merchant would typically use to book their sales. The merchant can select an existing account from Xero. If an account is not available, it needs to be created in Xero for this purpose.

A dropdown list displaying nominal accounts that can be used to map **Sales**.A dropdown list displaying nominal accounts that can be used to map **Sales**.

A dropdown list displaying nominal accounts that can be used to map Sales.

Codat pushes a single sales invoice to Xero daily. The invoice is issued to the commerce services provider.

The invoice represents an aggregation of all the sales made over the course of that day.

It contains a line item for each tax rate. Each line item represents the total of all sales at the given tax rate.

If no sales have been made at a given tax rate on that day, the corresponding line item will be omitted.

An invoice in Xero that represents sales made at the 20.0 and 0.0 tax rates (click to expand).An invoice in Xero that represents sales made at the 20.0 and 0.0 tax rates (click to expand).

An invoice in Xero that represents sales made at the 20.0 and 0.0 tax rates (click to expand).

🚧

Rounding

Discounts are applied to the total of the purchase once all the items have been summed up rather than at an item level. As we are splitting out items into VAT percentages across all sales for the day, discounts need to be applied at the item level which may lead to slight rounding discrepancies compared to applying the discount at the summed level. As per the advice of most accounting packages, we add an invoice line of ± 0.01 to bring the total in line with the correct total.

When the merchant receives payment for the reported sales, the invoice is marked as paid and is balanced by the merchant’s holding account (also known as a clearing or a liquid account) for the respective payment type.

To learn more about the configuration of Payments, navigate to the Payments section.

Refunds

Refunds represent a catch-all for all refunds, cash or non-cash.

Similar to Sales, Refunds are usually booked on a nominal account that the merchant uses to book their revenue, of the Xero type Revenue.

Typically, merchants would push Sales and Refunds into the same account. However, they can use a different account if they wish to report them separately.

A dropdown list displaying nominal accounts that can be used to map **Refunds** (click to expand).A dropdown list displaying nominal accounts that can be used to map **Refunds** (click to expand).

A dropdown list displaying nominal accounts that can be used to map Refunds (click to expand).

When purchase refunds are recorded in Xero, the negative revenue will be booked to the selected account.

Codat pushes a single sales credit note to Xero daily.

The credit note represents all refunds made over the course of that day. It contains one line item for each tax rate, with this line item representing the total of all refunds at that tax rate.

If no refunds have been made for a given tax rate on that day, the corresponding line item will be omitted.

An invoice in Xero that represents the refunds that have been made during the day (click to expand).An invoice in Xero that represents the refunds that have been made during the day (click to expand).

An invoice in Xero that represents the refunds that have been made during the day (click to expand).

Codat pushes refund payment data as cash refunds.

For each payment type refunded, a transaction is recorded against the credit note. This refund is taken from the selected account to receive Payments for each payment type (card, cash, etc):

🚧

Payments

The screenshots that follow are related to the Payments feature. To learn more about the configuration of Payments, navigate to the Payments section.

A cash refund in Xero that represents a card refund to the **Payment** account configured for card payments (click to expand).A cash refund in Xero that represents a card refund to the **Payment** account configured for card payments (click to expand).

A cash refund in Xero that represents a card refund to the Payment account configured for card payments (click to expand).

A cash refund in Xero that represents a cash refund to the **Payment** account configured for cash payments (click to expand).A cash refund in Xero that represents a cash refund to the **Payment** account configured for cash payments (click to expand).

A cash refund in Xero that represents a cash refund to the Payment account configured for cash payments (click to expand).

Gratuity

Gratuity represents tips collected by the merchant from their customers on payment.

Depending on the merchant’s preference, Gratuity can be booked in a Revenue or a Liability account.

A dropdown list displaying nominal accounts that can be used to map **Gratuity** (click to expand).A dropdown list displaying nominal accounts that can be used to map **Gratuity** (click to expand).

A dropdown list displaying nominal accounts that can be used to map Gratuity (click to expand).

Gratuity is pushed to Xero as part of the daily sales invoice as a separate line item.

A sales invoice in Xero featuring a line item representing **Gratuity** payments that have been received during the day (click to expand).A sales invoice in Xero featuring a line item representing **Gratuity** payments that have been received during the day (click to expand).

A sales invoice in Xero featuring a line item representing Gratuity payments that have been received during the day (click to expand).

Prepaid

The Prepaid feature covers the transactions pertaining to selling and redeeming prepaid items, such as gift cards.

Transactions of the type Prepaid should be booked into a Liability account.

A dropdown list displaying nominal accounts that can be used to map **Prepaid** (click to expand).A dropdown list displaying nominal accounts that can be used to map **Prepaid** (click to expand).

A dropdown list displaying nominal accounts that can be used to map Prepaid (click to expand).

The purchase of prepaid items will appear as a line item on the daily Sales invoice in Xero.

A daily sales invoice in Xero that features a gift card that was sold during the day (click to expand).A daily sales invoice in Xero that features a gift card that was sold during the day (click to expand).

A daily sales invoice in Xero that features a gift card that was sold during the day (click to expand).

Note that when a customer uses the prepaid item (for example, purchases an item with a gift card), this is processed as a normal sale (see Sales):

Payment on the daily **Sales** invoice representing a purchase of an item using a gift card (click to expand).Payment on the daily **Sales** invoice representing a purchase of an item using a gift card (click to expand).

Payment on the daily Sales invoice representing a purchase of an item using a gift card (click to expand).

Fees

The Fees feature encompasses the transactions that involve the commerce service provider, including Payment fees that a commerce platform charges the merchant for processing their card transactions and Payment fee refunds.

To set up Fees, the merchant needs to configure account mappings for all the Fees subtypes by selecting the account they wish to send the data into from the respective dropdown lists.

The lists display all the applicable accounts available on the merchant’s Xero accounting platform:

Sync UI **Fees** accounts screen where you can select the accounts to use to map the commerce data (scrolled up).Sync UI **Fees** accounts screen where you can select the accounts to use to map the commerce data (scrolled up).

Sync UI Fees accounts screen where you can select the accounts to use to map the commerce data (scrolled up).

Sync UI **Fees** accounts screen where you can select the accounts to use to map the commerce data (scrolled down).Sync UI **Fees** accounts screen where you can select the accounts to use to map the commerce data (scrolled down).

Sync UI Fees accounts screen where you can select the accounts to use to map the commerce data (scrolled down).

Fees account mapping

Payment fees

Payment fees are the commissions that a commerce platform charges the merchant for processing their card transactions.

Payment fees should be booked into a nominal account that the merchant uses to record their expenses, typically of the Xero Expense type.

A dropdown list displaying nominal accounts that can be used to map **Payment fee** (click to expand).A dropdown list displaying nominal accounts that can be used to map **Payment fee** (click to expand).

A dropdown list displaying nominal accounts that can be used to map Payment fee (click to expand).

Codat pushes a single purchase invoice (bill) to Xero each day. This bill represents all fees taken by the commerce platform over the course of that day. The bill contains a single line.

The bill is recorded against the commerce services supplier, and the expense account for the line item is set to the selected commerce fees account.

🚧

Payment fee account

If the selected target account is a bank account, bills are represented as a bank transaction (spend money) and will not be represented as a bill/bill payment.

A bill in Xero that represents all **Payment fees** taken by the commerce platform over the course of that day.A bill in Xero that represents all **Payment fees** taken by the commerce platform over the course of that day.

A bill in Xero that represents all Payment fees taken by the commerce platform over the course of that day.

To represent the payment of fees, a single payment is pushed for the full payment of the bill, representing the transfer of money out of the merchant’s holding account (also known as a clearing or a liquid account).

A payment that represents the transfer of money out of the liquid account to pay the fees.A payment that represents the transfer of money out of the liquid account to pay the fees.

A payment that represents the transfer of money out of the liquid account to pay the fees.

Payment fee refund

When a merchant refunds a payment accepted using a commerce platform, the commission taken when the payment was taken is simultaneously refunded to their commercial account. In the Codat Sync flow UI, such refunds are referred to as Payment fee refunds.

Payment fee refunds are typically booked to the same accounts configured for Payment fees. Using the same account simplifies the processing of fee refunds, but the merchant should be able to select a different account if they wish to do so.

A dropdown list displaying nominal accounts that can be used to map **Payment fee refunds** (click to expand).A dropdown list displaying nominal accounts that can be used to map **Payment fee refunds** (click to expand).

A dropdown list displaying nominal accounts that can be used to map Payment fee refunds (click to expand).

A single bill credit note is pushed each day representing all fee refunds processed that day:

A bill credit note in Xero that represents all fee refunds processed during the day.A bill credit note in Xero that represents all fee refunds processed during the day.

A bill credit note in Xero that represents all fee refunds processed during the day.

🚧

Payment fee refunds account

If the selected target account is a bank account, bills are represented as a bank transaction (receive money) and will not be represented as a credit note.

A cash refund payment for the whole value of the credit note is simultaneously pushed, so the bill credit note is fully paid (as no further cash is owed to the merchant by the commerce platform):

A cash refund payment that represents a refund from the commerce platform to the merchant.A cash refund payment that represents a refund from the commerce platform to the merchant.

A cash refund payment that represents a refund from the commerce platform to the merchant.

Payments

Payment accounts contain cash. This is in contrast to all the accounts discussed in the Sales and Fees sections, which are nominal accounts and represent accounting concepts rather than hard cash.

Codat supports either bank accounts or current accounts for Payments. They should be of a nominal type Asset or Liability and have an Enable payments to this account setting turned on:

An account setting that you need to turn on to enable an account to receive Payments.An account setting that you need to turn on to enable an account to receive Payments.

An account setting that you need to turn on to enable an account to receive Payments.

❗️

Deposit accounts

A deposit account cannot be used for payments.

We recommend having the following core payment types enabled:

  • Card
  • Cash
  • Payout

Sync for Commerce supports additional payment types that can be switched on as applicable including invoices, specific payment types, or custom types.

Payments account mapping

Codat has provided functionality to allow users to select different accounts for each different payment type.

🚧

Accounts for card payments

For card payments, it’s recommended that the merchant creates a clearing account to represent their account with the commerce services provider. The clearing account can be a bank account or a nominal account in Xero that has an Enable payments to this account setting turned on.

❗️

New payment types after setup

If the user starts using other payments types after initial setup, the synchronization will stop until the accounts have been re-mapped via returning to the configuration page.

Codat pushes a single payment to Xero per day per payment type which has been used that day.

For example, if the merchant processes ten card payments and twenty cash payments in one day, two payments are pushed. These payments are recorded against the daily sales invoice (see Sales).

If you are pushing Sales and Payments simultaneously, the sales invoices will be pushed to Xero fully paid (as no further cash is expected from customers).

A daily **Sales** invoice with two line items representing the sales made on the previous day.A daily **Sales** invoice with two line items representing the sales made on the previous day.

A daily Sales invoice with two line items representing the sales made on the previous day.

A Xero transaction that represents a cash payment.A Xero transaction that represents a cash payment.

A Xero transaction that represents a cash payment.

A Xero transaction that represents a card payment.A Xero transaction that represents a card payment.

A Xero transaction that represents a card payment.


Did this page help you?