Invoices
Explore Invoices endpoints in Swagger.
Overview
An invoice is an itemised record of goods sold or services provided to a customer.
In Codat, an invoice contains details of:
- The timeline of the invoice - when it was raised, marked as paid, last edited, and so on.
- How much the invoice is for, what portion is tax or discounts, and what currency the amounts are represented in.
- Who the invoice has been raised to - the customer.
- The breakdown of what the invoice is for - the line items.
- Any payments assigned to the invoice - the payment allocations.
Invoices or bills?
In Codat, invoices represent accounts receivable only. For accounts payable invoices, see Bills.
Invoice PDF downloads
You can download a PDF version of an invoice for supported integrations.
The filename will be invoice-{number}.pdf.
Data model
Referencing an invoice in Sage 50 and ClearBooks
In Sage 50 and ClearBooks, you may prefer to use the invoiceNumber to identify an invoice rather than the invoice id. Each time a draft invoice is submitted or printed, the draft id becomes void and a submitted invoice with a new id exists in its place. In both platforms, the invoiceNumber should remain the same.
Field | Type | Description |
|---|---|---|
id | string | Identifier for the invoice, unique to the company in the accounting platform. |
invoiceNumber | string | Friendly reference for the invoice. If available, this appears in the file name of invoice attachments. |
customerRef | Reference to the customer the invoice has been issued to. | |
issueDate | string | Date of the invoice as recorded in the accounting system. |
dueDate | string | Date the customer is due to be paid by. |
modifiedDate | string | Date the record was last updated in the Codat system. |
sourceModifiedDate | string | Date the record was last changed in the accounting system. |
paidOnDate | string | Date the invoice was marked as paid in the accounting system. If this field is not available from the accounting software, it is calculated by Codat using associated payments. |
currency | string | Currency of the invoice. |
currencyRate | number | Rate between the currency of the invoice and the base currency of the company. |
lineItems | An array of InvoiceLineItems. | |
paymentAllocations | An array of InvoicePaymentAllocation. | |
totalDiscount | decimal | Numerical value of discounts applied to the invoice. |
subTotal | decimal | Total amount of the invoice excluding any taxes. |
totalTaxAmount | decimal | Amount of tax on the invoice. |
totalAmount | decimal | Amount of the invoice, inclusive of tax. |
amountDue | decimal | Amount outstanding on the invoice. |
discountPercentage | decimal | Percentage rate (from 0 to 100) of discounts applied to the invoice. For example: A 5% discount will return a value of |
status | string | Current state of the invoice:
|
note | string | Any additional information about the invoice. Where possible, Codat links to a data field in the accounting platform that is publicly available. This means that the contents of the note field are included when an invoice is emailed from the accounting platform to the customer. |
Line items
Field | Type | Description |
|---|---|---|
description | string | Friendly name of the goods or services provided. |
unitAmount | decimal | Price of each unit of goods or services. |
quantity | decimal | Number of units of goods or services provided. |
discountAmount | decimal | Numerical value of any discounts applied. |
subTotal | decimal | Amount of the line, inclusive of discounts but exclusive of tax. |
taxAmount | decimal | Amount of tax for the line. |
totalAmount | decimal | Total amount of the line, including tax. When pushing invoices to Xero, the total amount is exclusive of tax to allow automatic calculations if a tax rate or tax amount is not specified. |
accountRef | Reference to the account to which the line item is linked. | |
discountPercentage | decimal | Percentage rate (from 0 to 100) of any discounts applied to the unit amount. |
taxRateRef | Reference to the tax rate to which the line item is linked. | |
itemRef | string | Reference to the item the line is linked to. |
trackingCategoryRefs | Reference to the tracking categories to which the line item is linked. |
Payment allocations
Field | Type | Description |
|---|---|---|
id | string | Identifier from the payments data type. |
totalAmount | decimal | Amount in the currency of the invoice. |
currency | string | Currency of the original payment. |
currencyRate | decimal | currencyRate * totalAmount = amount in original currency of payment. |
date | string | Date of the payment. |
note | string | Note field from the payment. |
Requirements for reference fields
The reference fields customerRef, accountRef, and taxRateRef are only populated if the corresponding data type has been synchronised. If you see null values for these fields, please complete a new sync for the corresponding data type. For example, sync the customers data type for customerRef.
Example data
{
"results": [
{
"id": "e55b7c0d-9084-4113-9379-515d0a4a07a3",
"invoiceNumber": "30018481",
"customerRef": {
"id": "06bf0258-4a11-4a44-b141-a991fcb1d7c7",
"companyName": "Speedy Gonzales"
},
"issueDate": "2018-10-04T22:40:50Z",
"dueDate": "2018-10-08T22:40:50Z",
"modifiedDate": "2019-02-19T12:06:58Z",
"sourceModifiedDate": "2018-10-04T22:40:50Z",
"paidOnDate": null,
"currency": "USD",
"currencyRate": null,
"lineItems": [
{
"description": "ACMEIndestructoSteelBall",
"unitAmount": 80,
"quantity": 8,
"discountAmount": 0,
"subTotal": 640,
"taxAmount": 64,
"totalAmount": 704,
"accountRef": {
"id": "77df77d7-777b-4455-af51-a6b563733842",
"name": "Sales"
},
"discountPercentage": null,
"taxRateRef": {
"id": "8c88aff8-7cb9-8888-a8d8-443e72e02498",
"name": "ACME Sales Tax (10%)"
},
"itemRef": {
"id": "3",
"name": "ACME Construction"
},
"trackingCategoryRefs": [
{
"id": "costcode9",
"name": "ACME Site One"
}
]
},
{
"description": "Anvil10000Lb",
"unitAmount": 50,
"quantity": 7,
"discountAmount": 0,
"subTotal": 350,
"taxAmount": 35,
"totalAmount": 385,
"accountRef": {
"id": "77df77d7-777b-4455-af51-a6b563733842",
"name": "Sales"
},
"discountPercentage": null,
"taxRateRef": {
"id": "8c88aff8-7cb9-8888-a8d8-443e72e02498",
"name": "ACME Sales Tax (10%)"
},
"itemRef": {
"id": "4",
"name": "ACME Tools"
}
},
{
"description": "ACMEStraitJacketEjectingBazooka",
"unitAmount": 52,
"quantity": 6,
"discountAmount": 0,
"subTotal": 312,
"taxAmount": 31.2,
"totalAmount": 343.2,
"accountRef": {
"id": "77df77d7-777b-4455-af51-a6b563733842",
"name": "Sales"
},
"discountPercentage": null,
"taxRateRef": {
"id": "8c88aff8-7cb9-8888-a8d8-443e72e02498",
"name": "ACME Sales Tax (10%)"
},
"itemRef": {
"id": "5",
"name": "ACME Defence"
}
},
{
"description": "ACMEIntegratingPistol",
"unitAmount": 44,
"quantity": 10,
"discountAmount": 0,
"subTotal": 440,
"taxAmount": 44,
"totalAmount": 484,
"accountRef": {
"id": "77df77d7-777b-4455-af51-a6b563733842",
"name": "Sales"
},
"discountPercentage": null,
"taxRateRef": {
"id": "8c88aff8-7cb9-8888-a8d8-443e72e02498",
"name": "ACME Sales Tax (10%)"
},
"itemRef": {
"id": "3",
"name": "ACME Defence"
}
}
],
"paymentAllocations": [],
"totalDiscount": 0,
"subTotal": 1742,
"totalTaxAmount": 174.2,
"totalAmount": 1916.2,
"amountDue": 1916.2,
"discountPercentage": null,
"status": "Draft",
"note": "Details of breakdown available on request."
}
],
"pageNumber": 1,
"pageSize": 1,
"totalResults": 1456,
"_links": {
"current": {
"href": "/companies/85c10664-b6cc-49dd-b369-0cd1cef69031/data/invoices?page=1&pageSize=1"
},
"self": {
"href": "/companies/85c10664-b6cc-49dd-b369-0cd1cef69031/data/invoices"
},
"next": {
"href": "/companies/85c10664-b6cc-49dd-b369-0cd1cef69031/data/invoices?page=1&pageSize=2"
}
}
}
Updated about 1 month ago