Configuration and categorizing expenses
Set up, map, and enable the Sync for Expenses solution
Once your SMB user has authorized a connection to their accounting platform and you have created a data connection, you can then configure and enable Sync for Expenses.
Configuration
The configuration endpoint enables you to set up how your customers expenses will be pushed. You can check the config at any time to confirm your companies' configuration.
GET https://api.codat.io/companies/{companyId}/sync/expenses/config
{
"bankAccount": {
"id": "{selectedBankAccountId}"
},
"supplier": {
"id": "{selectedSupplierId}"
},
"customer": {
"id": "{selectedCustomerId}"
}
}
Using this endpoint you will be able to:
Bank Account
- Choose which bank account (
bankAccount.id
) purchases will be made from. This can also be a credit card account. - GET a list of available accounts. Use this request to retrieve a list of relevant accounts from your customers' accounting software. You should also add additional query parameters, e.g.
query=metadata.isDeleted=false&&isBankAccount=true
. - For credit cards you can use an additional query parameter e.g.
query=metadata.isDeleted=false&&isBankAccount=true&&type=liability
- You can POST to the Accounting API to create a new account.
There are two ways to handle transactions in a foreign currency:
Each Foreign Exchange currency has its own bank account
Each transaction is converted back to the currency of the bank account.
Sync for Expenses currently supports option 2 only.
Supplier
- A supplier (
supplier.id
) is required to associate all spending against that supplier.
Customer
- Choose which customer (
customer.id
) any income-related activities, such as cashback, should be associated with.
You can then post the updated configuration to Codat to store their saved preferences.
Mapping Options
Every company will have their own preference on how an individual expense can be represented in their accounting software, you can retrieve these options from the mappingOptions
endpoint.
The mappingOptions
response can then be cached and displayed to the end user when they are finalizing their expenses before exporting.
{
"expenseProvider": "Partner Expense",
"accounts": [
{
"id": "c5194f9d-b443-4630-b2d4-339bd57d313c",
"name": "Interest Earned",
"currency": "GBP",
"accountType": "Asset",
"validTransactionTypes": [
"Reward",
"Adjustment",
"Transfer"
]
}
...
],
"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
}
...
]
}
You will normally see the name of the connected provider in the expenseProvider
property.
Accounts
The accounts
array will include the general ledger accounts which have been pulled from the businesses accounting software. The name
is what they have labelled the account in their accounting software, so you can display this to your end user.
validTransactionTypes
will tell you which types are accepted by the account. This prevents validation issues such as an SMB accidentally trying to reconcile an expense to an income account.
Additional accounts can also be created using the public API, this could be useful if a company has a new category for representing expenses.
POST https://api.codat.io/companies/{companyId}/connections/{connectionId}/push/accounts",
{
"nominalCode": "310",
"name": "Stationary Costs",
"fullyQualifiedCategory": "Expenses"
}
Tracking categories
Tracking categories are used to monitor cost centres 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, such as "sales and marketing", projects, locations or customers.
When pushing an expense reconciliation, you can include a tracking category to associate this to further categorize an expense.
Tax Rates
The tax rates enable your SMB's 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 package. 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 adds the correct tax rate of 20%.
Assigning a tax rate to a transaction is mandatory unless the transaction is a transferIn or transferOut (see Transaction types. 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 package for those transactions.
Refreshing the mappingOptions
The default sync settings will refresh the mapping options on an daily basis, however, you can also refresh the options by making the following request.
POST https://api.codat.io/companies/{companyId}/data/all