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.
Push configuration
The configuration endpoint enables you to set up how your customers' expenses will be pushed. You can check the config anytime to confirm your company's configuration.
GET https://api.codat.io/companies/{companyId}/sync/expenses/config
{
"bankAccount": {
"id": "{selectedBankAccountId}"
},
"supplier": {
"id": "{selectedSupplierId}"
},
"customer": {
"id": "{selectedCustomerId}"
}
}
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.
- 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.
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 supports both of these options.
Supplier
- A supplier (
supplier.id) is required to associate all spending against that supplier. - Suppliers can be set at the configuration level and also at the transaction level.
- By setting the supplier at the transaction level you will be able to override the configuration supplier, in order to sync a more accurate representation of who the spend should be associated with in the accounting platform.
- If no supplier is set at the transaction level, the spend will have the config supplier set as a default against it.
- The currency associated with the supplier must match the currency associated with the spend.
- The currency associated with the supplier must match the currency associated with the spend. Codat validates the match for suppliers with a single set currency, but not for suppliers that work with multiple currencies.
In some cases, different accounting platforms have certain ways of handling suppliers and customers, based on transaction types:
| Supported Platforms | |||||
| Xero | QBO | Netsuite (credit card only) | Microsoft Dynamics | ||
| Transaction Types | Payments | Supplier used | Supplier used | Supplier used | Supplier is not associated with expense transactions due to a Dynamics platform limitation. |
| Refund | Customer used | Supplier used | Supplier used | ||
| Rewards | Customer used | Supplier used | NA | ||
| Chargeback | Customer used | Supplier used | NA | ||
| Transfer In | Customer used | Supplier used | NA | ||
| Transfer Out | Supplier used | Supplier used | NA | ||
| Adjustment In | If the chart of accounts’ is a bank account, then supplier used, if not then customer used. | Customer used | NA | ||
| Adjustment Out | Supplier used | Customer used | NA | ||
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.
Overriding the configuration settings
- Suppliers and Bank Accounts can be set at the configuration level and at the transaction level.
- By setting these at the transaction level, you can override the configuration and sync a more accurate representation of who or where the spend should be associated with in the accounting platform.
- If no override is set at the transaction level, the spend will have the configured supplier or bank account set as a default against it.
- This functionality is not currently supported for Customers.
"bankAccountRef":{
"id":"08ca1f02-0374-11ed-b939-0242ac120002",
"contactRef":{
"id":"08ca1f02-0374-11ed-b939-0242ac120002",
"type": "Supplier"
Mapping options
Every company has its 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 business's accounting software. The name is what they have labeled 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 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, 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 SMBs 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