Explore Bills endpoints in Swagger.

Overview

A bill is an itemized record of goods purchased from or services provided by a supplier.

In Codat, a bill contains details of:

  • When the bill was recorded in the accounting system.
  • How much the bill is for and the currency of the amount.
  • Who the bill was received from — the supplier.
  • What the bill is for — the line items.

Some accounting platforms give a separate name to purchases where the payment is made immediately, such as something bought with a credit card or online payment. One example of this would be QuickBooks Online's expenses.

Codat doesn't have a separate data type for these, so you'll see the itemized breakdown of the purchase here and the corresponding payment in the Bill payments dataset. The payment information will also be populated on the bill's paymentAllocations if you've synchronized bill payments for the company.

📘

Invoices or bills?

In Codat, bills are for accounts payable only. For the accounts receivable equivalent of bills, see Invoices.

Data model

Field

Type

Description

id

string

Identifier for the bill, unique for the company in the accounting platform.

reference

string

User-friendly reference for the bill.

supplierRef

reference type

Reference to the supplier the bill was received from.

purchaseOrderRefs

array

List of references to the purchase orders for which the bill was issued.

issueDate

string
See date

Date of the bill as recorded in the accounting platform.

dueDate

string
See date

Date the supplier is due to be paid.

currency

string
See currency

Currency of the bill.

currencyRate

decimal
See currency rate

Rate for converting the total amount of the bill into the base currency for the company.

lineItems

array

Array of BillLineItems.

status

string

Current state of the bill, either:

  • Draft — Bill is yet to be authorized and sent by the supplier, and will not be used in any reports. It may contain incomplete line items.

  • Open — Bill is no longer a draft. It has been processed and/or sent to the supplier. In this state, it will impact the ledger. It also has no payments made against it (amountDue == totalAmount).

  • PartiallyPaid — The balance paid against the bill is positive, but less than the total bill amount (0 < amountDue < totalAmount).

  • Paid — Bill is paid in full. This includes if the bill has been credited or overpaid. (amountDue == 0).

  • Void — A Bill can become Void by being deleted, refunded, written off, or cancelled. A voided bill may still be partially paid and so all outstanding amounts on voided bills are removed from the accounts payable account.

  • Unknown

subTotal

decimal

Total amount of the bill, excluding any taxes.

taxAmount

decimal

Amount of tax on the bill.

totalAmount

decimal

Amount of the bill, including tax.

amountDue

decimal

Amount outstanding on the bill.

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.

note

string

Any private, company notes about the bill, such as payment information.

Line items

Field

Type

Description

description

string

Friendly name of the goods or services received.

unitAmount

decimal

Price of each unit of goods or services.

quantity

decimal

Number of units of goods or services received.

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.

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 product, service type, or inventory item to which the line item is linked.

trackingCategoryRefs

array

Collection of categories against which this item is tracked.

🚧

Requirements for reference fields

The reference fields supplierRef, accountRef, and taxRateRef are only populated if the corresponding data type has been synchronized. If you see null values for these fields, please complete a new sync for the corresponding data type. For example, sync the suppliers data type for supplierRef.

Example data

"results": [
    {
      "id": "f64ac382-14b6-4850-b5c3-0fe848342b1d",
      "reference": "57120",
      "supplierRef": {
        "id": "21C99A58-7565-4DC8-8FDF-BA7DF5280F25",
        "supplierName": "EDD"
      },
      "purchaseOrderRefs":  [
          {
        "id": "string",
        "purchaseOrderNumber": "string"
          }
        ]
      },
      "issueDate": "2020-04-18T00:00:00",
      "dueDate": "2021-08-07T00:00:00",
      "currency": "GBP",
      "currencyRate": 1,
      "lineItems": [
        {
          "description": "10,000 Lb anvil bought",
          "unitAmount": 45,
          "quantity": 2,
          "discountAmount": 0,
          "subTotal": 90,
          "taxAmount": 9,
          "totalAmount": 99,
          "accountRef": {
            "id": "13931cbf-ea06-4d6e-9538-a8457fa66011",
            "name": "Cost of Goods Sold"
          },
          "discountPercentage": 0,
          "taxRateRef": {
            "id": "6c88aff3-7cb9-4980-a3d3-443e72e02498",
            "name": "ACME Sales Tax (10%)",
            "effectiveTaxRate": 10
          },
          "itemRef": {
            "id": "1",
            "name": "Anvil (10,000lb)"
          },
          "trackingCategoryRefs": []
        },
        {
          "description": "10,000 Lb anvil bought",
          "unitAmount": 45,
          "quantity": 4,
          "discountAmount": 0,
          "subTotal": 180,
          "taxAmount": 18,
          "totalAmount": 198,
          "accountRef": {
            "id": "13931cbf-ea06-4d6e-9538-a8457fa66011",
            "name": "Cost of Goods Sold"
          },
          "discountPercentage": 0,
          "taxRateRef": {
            "id": "6c88aff3-7cb9-4980-a3d3-443e72e02498",
            "name": "ACME Sales Tax (10%)",
            "effectiveTaxRate": 10
          },
          "itemRef": {
            "id": "1",
            "name": "Anvil (10,000lb)"
          },
          "trackingCategoryRefs": []
        }
      ],
      "status": "Paid",
      "subTotal": 270,
      "taxAmount": 27,
      "totalAmount": 297,
      "amountDue": 0,
      "modifiedDate": "2021-04-08T09:15:56Z",
      "sourceModifiedDate": "2021-01-29T22:42:20",
      "note": "bill with 2 line items, totalling 297",
      "paymentAllocations": [
        {
          "payment": {
            "id": "ee9f6363-d6fd-4bb5-87e6-10d0d1bba6af",
            "note": "Bill Payment against bill",
            "accountRef": {
              "id": "dbcaf288-2b39-4b95-8ab3-42202ab15918",
              "name": "Business Current Account"
            },
            "currency": "GBP",
            "currencyRate": 1,
            "paidOnDate": "2020-10-18T00:00:00",
            "totalAmount": 297
          },
          "allocation": {
            "currency": "GBP",
            "currencyRate": 1,
            "allocatedOnDate": "2021-02-13T00:00:00",
            "totalAmount": -297
          }
        }
      ]
    }

Did this page help you?