Invoices
An itemized record of goods sold or services provided
Explore the Invoices endpoints in Swagger.
View the coverage for invoices in the Data Coverage Explorer.
Overview
An invoice is an itemized 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 of the invoice 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. | |
salesOrderRefs | array | List of references to related Sales orders. |
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 modified in Codat in any way. For example, the The |
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. |
additionalTaxAmount | ||
additionalTaxPercentage |
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 type | 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 type | Reference to the tax rate to which the line item is linked. |
| itemRef | reference type | Reference to the item the line is linked to. |
| trackingCategoryRefs | reference type | Reference to the tracking categories to which the line item is linked. |
Payment allocations
Field | Type | Description |
|---|---|---|
payment | ||
id | string | Identifier of the allocated payment. |
note | string | Notes attached to the allocated payment. |
reference | string | Reference to the allocated payment. |
accountRef | The account that the allocated payment is made from or to. | |
currency | string | Currency the payment has been made in. |
currencyRate | decimal | Conversion rate between the currency of the allocated payment and the currency of the company. |
paidOnDate | string | The date the payment was paid. |
totalAmount | decimal | Total amount that was paid. |
allocation | ||
currency | string | The currency of the transaction. |
currencyRate | decimal | The conversion rate between the currency of the allocated payment and the currency of the transaction. |
allocatedOnDate | string | The date the payment was allocated. |
totalAmount | decimal | The total amount that has been allocated. |
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"
},
"salesOrderRefs": [
{
"id": "29d85e65-e54d-4a36-b141-0078175b620d",
"dataType": "salesOrders"
}
],
"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 2 months ago