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 type	Reference to the customer the invoice has been issued to.
issueDate	string See date	Date of the invoice as recorded in the accounting system.
dueDate	string See date	Date the customer is due to be paid by.
modifiedDate	string See date	Date the record was last updated in the Codat system.
sourceModifiedDate	string See date	Date the record was last changed in the accounting system.
paidOnDate	string See date	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 See currency	Currency of the invoice.
currencyRate	number See currency rate	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 `5`, not `0.05`.
status	string	Current state of the invoice: `Draft` - Invoice hasn't been submitted to the supplier. It may be in a pending state or is scheduled for future submission, for example by email. `Submitted` - Invoice is no longer a draft. It has been processed and, or, sent to the customer. In this state, it will impact the ledger. It also has no payments made against it (amountDue == totalAmount). `PartiallyPaid` - The balance paid against the invoice is positive, but less than the total invoice amount (0 < amountDue < totalAmount). `Paid` - Invoice is paid in full. This includes if the invoice has been credited or overpaid (amountDue == 0). `Void` - An invoice can become `Void` when it's deleted, refunded, written off, or cancelled. A voided invoice may still be `PartiallyPaid`, and so all outstanding amounts on voided invoices are removed from the accounts receivable account.
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 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	Reference type	The account that the allocated payment is made from or to.
currency	string See currency	Currency the payment has been made in.
currencyRate	decimal See currency rate	Conversion rate between the currency of the allocated payment and the currency of the company.
paidOnDate	string See date	The date the payment was paid.
totalAmount	decimal	Total amount that was paid.
allocation
currency	string See currency	The currency of the transaction.
currencyRate	decimal See currency rate	The conversion rate between the currency of the allocated payment and the currency of the transaction.
allocatedOnDate	string See date	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"
            },
            "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"
        }
    }
}

Invoices

Overview

📘
Invoices or bills?

👍
Invoice PDF downloads

Data model

📘
Referencing an invoice in Sage 50 and ClearBooks

Line items

Payment allocations

🚧
Requirements for reference fields

Example data

Overview

📘Invoices or bills?

👍Invoice PDF downloads

Data model

📘Referencing an invoice in Sage 50 and ClearBooks

Line items

Payment allocations

🚧Requirements for reference fields

Example data

📘
Invoices or bills?

👍
Invoice PDF downloads

📘
Referencing an invoice in Sage 50 and ClearBooks

🚧
Requirements for reference fields