Map customer transactions

Map accounts, suppliers, and customers to create transactions using the Sync for Expenses product

Once your SMB user has authorized a connection to their accounting software and you have created a data connection, they are ready to start creating their expense transactions. Each transaction needs to be associated with a bank account, customer, and supplier. To add these values to the transaction, you can:

• Enable your customer to indicate the required bank account, customer, and supplier values on each expense transaction.
• Use default fallback bank account, customer, and supplier values pre-configured for the customer's company.

You also need to provide your customer with an opportunity (via your application's user interface) to choose the default accounts, tracking categories, and tax rates that their expenses will be mapped to.

Enable customer to set values

Your customers should be able set a bank account, customer, and supplier for each expense transaction to allow for a more accurate representation of who or where the spend should be associated with in the accounting software.

Bank account override on the expense transaction

"bankAccountRef":{
  "id":"08ca1f02-0374-11ed-b939-0242ac120002",
}

Supplier / customer override on the expense transaction

"contactRef":{
  "id":"08ca1f02-0374-11ed-b939-0242ac120002",
  "type": "Supplier"
}

If your customer doesn't provide these values on the transaction itself, Sync for Expenses will use default values you configure for the company as a fallback.

Default and mandatory values

If you choose not to set default configuration and no values are entered on the transaction, the expense will fail to create in the accounting software. To avoid this, make the bank account, customer, and supplier fields mandatory in your app's UI for your user to provide.

Configure default values

When no values are set at the transaction level, the spend item will be associated with the bank account, supplier, and customer default values configured for the company.

To set these values and determine how your customers' transactions will be recorded, use our Set company configuration endpoint. You can use the Get company configuration endpoint anytime to check the existing configuration or display it to the user.

Company Config

POST https://api.codat.io/companies/{companyId}/sync/expenses/config
{
    "bankAccount": {
        "id": "{selectedBankAccountId}"
    },
    "supplier": {
        "id": "{selectedSupplierId}"
    },
    "customer": {
        "id": "{selectedCustomerId}"
    }
}

If a configuration is set for a company, but the customer sets a bank account, supplier, and customer value on the expense transaction level, Sync for Expenses will use the values from the trasaction when creating the expense in the accounting software.

Suppliers in Microsoft Dynamics

Due to a limitation in the accounting software, Microsoft Dynamics requires a default supplier when creating expenses. We currently don't support assigning a supplier at the transaction level.

Bank account

A bank account (bankAccount.id) is required to show where purchases have been made from. This can either a credit or debit account. You can choose to create a new account or retrieve a list of existing accounts from your customer's accounting software.

• To create a new bank account, use the Create bank account endpoint. You should trigger a data refresh if a new bank account has been created prior to syncing transactions.

• Use the List accounts endpoint to fetch a list of your customer's existing accounts from their accounting software and display these to them. You can also use query parameters to narrow down the list of results, for example:

  • query=metadata.isDeleted=false&&isBankAccount=true returns existing bank accounts.
  • query=metadata.isDeleted=false&&isBankAccount=true&&type=liability returns existing liability bank accounts, which are used for credit cards.

Supplier

A supplier (supplier.id) is required so that the relevant spending can be associated with that that supplier record. You can choose to create a new supplier or retrieve a list of existing suppliers from your customer's accounting software.

• To create a new supplier, use the Create supplier endpoint.

• Use the List suppliers endpoint to fetch a list of your customer's existing suppliers from their accounting software and display these to them. You can also use query parameters to narrow down the list of results. For example, query=metadata.isDeleted=false&&supplierName=supplierName returns existing suppliers that match the specified name.

Supplier currency considerations

The currency associated with the supplier must match the currency associated with the relevant spend. Codat validates the match for suppliers with a single set currency, but not for suppliers that work with multiple currencies.

Customer

Choose the customer (customer.id) that any income-related activities, such as cashback, should be associated with. You can create a new supplier or retrieve a list of existing suppliers from your customer's accounting software.

• To create a new customer, use the Create customer endpoint.

• Use the List customers endpoint to fetch a list of your SMB's existing customers from their accounting software and display these to them. You can also use query parameters to narrow down the list of results. For example, query=metadata.isDeleted=false&&customerName=name returns existing customers that match the specified name.

Supplier and customer handling

In some scenarios, different accounting software assign customers and suppliers to a transaction based on the expense's transaction types:

Supported platforms
		Xero	QBO	Netsuite	Microsoft Dynamics	QuickBooks Desktop	FreeAgent
Transaction types	Payments	Supplier	Supplier	Supplier	Supplier is not associated with expense-transactions due to a Dynamics platform limitation.	Supplier	Supplier is not associated with expense-transactions due to a FreeAgent platform limitation.
	Refund	Customer	Supplier	Supplier		Supplier
	Rewards	Customer	Supplier	NA		NA
	Chargeback	Customer	Supplier	NA		NA

Mapping options

Every SMB customer has its own preference on how an individual expense should be represented in their accounting software. You can retrieve these options using the Mapping options endpoint.

The response can then be cached and displayed to the customer when they are finalizing their expenses. You will normally see the name of the connected expense provider in the expenseProvider property.

Sample mappingOptions response

{
    "expenseProvider": "Partner Expense",
    "accounts": [
        {
            "id": "127f3b99-8dc2-4b7e-854c-91ef9bd2757b",
            "nominalCode": "300",
            "name": "Purchases",
            "currency": "GBP",
            "accountType": "Expense",
            "fullyQualifiedCategory": "Expense.DirectCosts",
            "isBankAccount": false,
            "validTransactionTypes": [
                "Payment",
                "Refund",
                "Reward",
                "Chargeback"
            ]
        }
        ...
    ],
    "trackingCategories": [
        {
            "id": "dba3d4da-f9ed-4eee-8e0b-452d11fdb1fa",
            "modifiedDate": "2022-08-03T12:04:40.067Z",
            "name": "Sales and Marketing",
            "hasChildren": false,
            "parentId": "DEPARTMENT"
        }
        ...
    ],
    "taxRates": [
        {
            "id": "INPUT2",
            "name": "20% (VAT on Expenses)",
            "code": "INPUT2",
            "effectiveTaxRate": 20,
            "totalTaxRate": 20
        }
        ...
    ]
}

Accounts

The accounts array includes the general ledger accounts which have been read from the SMB customer's accounting software.

• The name is what they labelled the account in the software, so you can display this to your end user.
• validTransactionTypes tells you which transaction types are accepted by the account. This prevents validation issues, such as a customer accidentally trying to reconcile an expense to an income account.

You can also create additional accounts with our Create account endpoint, for example if a company has a new category for representing expenses.

Tracking categories

Tracking categories are used to monitor specific cost centers and control budgets that sit outside of the standard chart of accounts. Your customers may use tracking categories to group and track the income and costs of specific departments (e.g. Sales and marketing), projects, locations, or customers.

When writing an expense reconciliation, you can include a tracking category to further categorize this expense.

Tax rates

Tax rates enable your SMB customers to accurately track taxes against purchases and, depending on the locale, allow them to recoup the tax.

Accounting systems typically store a set of taxes and associated rates within the accounting software. This means users don't have to look up or remember the rate for each type of tax. For example, applying the tax "UK sales VAT" to the line items of an invoice in an accounting software will add the correct tax rate of 20%.

In some cases, your customers might not need to track tax on expenses. We recommend assigning a default tax code for 0% from the accounting software for those transactions.

Refresh mapping options

The default sync settings set for Sync for Expenses' data types will refresh the mapping options on an daily basis, however, you can also refresh the options manually by making a request to the Mapping options endpoint.

POST https://api.codat.io/companies/{companyId}/data/all

---

Read next

• Learn how to create datasets that contain expense transactions