Create and update expenses
Record and update expense transactions that represent your customers' spend
Overview
An expense is a transaction that represents the purchase made by your customer and the context behind that purchase. It usually includes the following details:
- Transaction type, e.g. whether it's a payment or a refund
- General ledger account the transaction should be reconciled to
- Associated tax rates
- Applicable tracking categories
With Sync for Expenses, you need to create the expense or transfer transactions first and write that dataset to Codat. We will describe options available to you on this page.
Then, you need to sync expenses to reflect these in your customer's accounting software. Finally, once these transactions have been synced, you can upload attachments to associate receipts with the transaction.
This process is summarized on the diagram below.
Create expenses
To create a new expense transaction in Codat, use the Create expense transaction endpoint.
In the request, make sure that the transaction's id is unique as it serves as an idempotence key. Codat validates the id to ensure that it's unique to a company, preventing the creation of duplicate transactions in your SMB's accounting software.
[
{
"id": "08ca1f02-0374-11ed-b939-0242ac120002",
"type": "Payment",
"issueDate": "2023-12-13T00:00:00+00:00",
"currency": "GBP",
"currencyRate": 1.26,
"contactRef":{
"id":"an-id-to-a-suppliers-record",
"type": "Supplier"
},
"bankAccountRef": {
"id": "an-id-to-a-bank-or-credit-card-account"
},
"postAsDraft": false,
"merchantName": "Amazon UK",
"lines": [
{
"netAmount": 110.42,
"taxAmount": 14.43,
"taxRateRef": {
"id": "an-id-to-a-taxRates-record"
},
"accountRef": {
"id": "id-of-the-expense-nominal-account"
},
"trackingRefs": [
{
"id": "an-id-to-a-trackingCategories-record",
"dataType": "trackingCategories"
}
],
"invoiceTo": {
"id": "an-id-to-a-customers-record",
"dataType": "customers"
}
}
],
"notes": "Amazon UK | Online Purchase | Order 123XX45"
}
]
Next, you need to follow up with an expense sync to reflect this item of spend in the customer's accounting software. We cover this in detail in Sync expenses.
Draft transactions
Some accounting software allow expense transactions to be created in a draft state instead of posting directly to the ledger. This means the user can review the expense in the accounting software before finalizing and posting it prior to reconciliation.
To create an expense as a draft, set the postAsDraft property on the transaction to true. For platforms without this feature, the postAsDraft property should be ignored or set to false.
This functionality is currently only available for Microsoft Dynamics.
Billable expenses
Your customer may want to mark an expense as billable so that they can easily identify and allocate costs to specific customers or projects. This simplifies the process of invoicing clients for reimbursable expenses.
To mark an expense as billable, set the invoiceTo property to customer. The expense will then reference the customer in the line item.
This functionality is currently only available for QuickBooks Online and QuickBooks Desktop.
Multicurrency expense transactions
Sync for Expenses validates each expense transaction involving foreign currency. We ensure that the combination of participating currencies will be accepted by the target accounting software as a valid expense. You can read more about expenses in foreign currency and platform support for different transaction types.
Default tax rates
If you need to remove an associated tax rate from an expense, use one of the following default values that have no impact on the expense:
| Platform | Default tax rate |
|---|---|
| QuickBooks Online | NON |
| Xero | NONE |
| Oracle NetSuite | US subsidiaries: -7Canadian subsidiaries: 114All other subsidiaries: check the UNDEF-{country code} tax rate |
| Dynamics 365 | Set up and apply a 0% tax rate |
| QuickBooks Desktop | Null |
| FreeAgent | taxRateRef is not supported |
Transaction types
Sync for Expenses maps and processes expense transactions based on the following transaction types:
| Transaction type | Description |
|---|---|
payment | Represents any spend that takes place on the account and interest on credit purchases. |
refund | Represents any refunds and returns on an original transaction. |
reward | Represents reward redemptions, such as cashback. |
chargeback | Similarly to a refund, represents a return of a transaction or a payment sum which may have been disputed. |
Adjustments
Your customer may want to reflect write-offs and transaction adjustments, such as foreign exchange adjustments, in their accounting software. Adjustments for FX alterations in expenses are essential to account for fluctuations in exchange rates. This ensures that expenses incurred in foreign currencies are accurately reflected in the company's reporting currency.
This process helps maintain the accuracy and reliability of financial statements, which is crucial for effective financial management and reporting.
You can use the Create adjustment transactions endpoint to help your customer achieve this. The adjustments will then appear in their accounting software as a journal entry.
This functionality is currently only available for QuickBooks Desktop.
Update expenses
Check our API reference for an up-to-date list of integrations that support this functionality.
In some cases, your customer may want to update an expense transaction that was previously synced to their accounting software. Use our Update expense transactions endpoint to edit the following parameters and reflect the change in the SMB's accounting software:
- Net expense amount
- Tax amount of the spend
- Tax rate reference associated with the spend
- Expense bank account reference (not possible to update for FreeAgent)
- Tracking category objects
- Description and notes
PUT https://api.codat.io/companies/{companyId}/sync/expenses/expense-transactions
Read next
- Sync the expenses to reflect the spend in the accounting software and monitor the progress of the synchronization.