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

string

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

id

string

Identifier from the payments data type.

totalAmount

decimal

Amount in the currency of the invoice.

currency

string
See currency

Currency of the original payment.

currencyRate

decimal
See currency rate

currencyRate * totalAmount = amount in original currency of payment.

date

string
See date

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"
        }
    }
}

Did this page help you?