Accounting: Bill payment
> **Bill payments or payments?** > > We distinguish between transactions where the company received money vs. paid money. If the transaction represents a company spending money (accounts payable) we call this a Bill payment. > > See [payments](https://docs.codat.io/lending-api#/schemas/Payment) for the accounts receivable equivalent of Bill payments, which covers [invoices](https://docs.codat.io/lending-api#/schemas/Invoice) and [credit notes](https://docs.codat.io/lending-api#/schemas/CreditNote). ## Overview Bill payments include all accounts payable transaction data ([bills](https://docs.codat.io/lending-api#/schemas/Bill) and [credit notes against bills](https://docs.codat.io/lending-api#/schemas/BillCreditNote)). A bill payment in Codat usually represents an allocation of money within any customer accounts payable account. This includes, but is not strictly limited to: - A payment made against a bill — for example, a credit card payment, cheque payment, or cash payment. - An allocation of a supplier's credit note to a bill or perhaps a refund. - A bill payment made directly to an accounts payable account. This could be an overpayment or a prepayment, or a refund of a payment made directly to an accounts payable account. Depending on the bill payments which are allowed by the underlying accounting software, some of these types may be combined. Please see the example data section for samples of what these cases look like. In Codat, a bill payment contains details of: - When the bill payment was recorded in the accounting system. - How much it is for and in the currency. - Who the payment has been paid to, the _supplier_. - The types of bill payments, the _line items_. Some accounting software 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_. You can find these types of transactions in our [Direct costs](https://docs.codat.io/lending-api#/schemas/DirectCost) data model. Bill payments is a child data type of [account transactions](https://docs.codat.io/lending-api#/schemas/AccountTransaction). --- ## Bill payment types ### Payment of a bill A payment paying a single bill should have the following properties: - A `totalAmount` indicating the amount of the bill that was paid. This is always positive. - A `lines` array containing one element with the following properties: - An `amount` equal to the `totalAmount` above. - A `links` array containing one element with the following properties: - A `type` indicating the type of link, in this case a `Bill`. - An `id` containing the ID of the bill that was paid. - An amount of `-totalAmount` (negative `totalAmount`), indicating that the entirety of the paid amount is allocated to the bill. ### Payment of multiple bills It is possible for one payment to pay multiple bills. This can be represented using two possible formats, depending on how the supplier keeps their books: 1. The payment has multiple entries in its **lines** array, one for each bill that is paid. Each line will follow the above example for paying a bill, and the rules detailed in the data model. 2. The payment has a line with multiple links to each bill. This occurs when the proportion of the original payment allocated to each bill is not available. Each line is the same as those described above, with the **amount** indicating how much of the payment is allocated to the bill. The **amount** on the lines sum to the **totalAmount** on the payment. > Pushing batch payments to Xero > > When pushing a single bill payment to Xero to pay multiple bills, only the first format is supported—multiple entries in the payment **lines** array. ### Payments and refunds on account A payment on account, that is a payment that doesn’t pay a specific bill, has one entry in its lines array. The line has the following properties: - A **totalAmount** indicating the amount paid by a supplier or refunded to them by a company. A payment to the supplier is always negative. A refund is always positive. - A **links** array containing one element with the following properties: - A **type** indicating the type of link. For a payment this is `PaymentOnAccount`. For a refund this is `Refund`. - The **id** containing the ID of the supplier. - An amount for the link is `0` **totalAmount** or the amount of the payment or refund. It is possible to have a payment that is part on account and part allocated to a bill. Each line should follow the examples above. ### Using a credit note to pay a bill The payment of a bill using a credit note has one entry in its `lines` array. This **line** has the following properties: - An **amount** indicating the amount of money moved, which in this case is `0`, as the credit note and bill allocation must balance each other. - A **links** array containing two elements: - The first link has: - A **type** indicating the type of link, in this case a `Bill`. - An **id** containing the ID of the bill that was paid. - The second link has: - A **type** indicating the type of link, in this case a `CreditNote`. - An **id** containing the ID of the credit note used by this payment. The **amount** field on the **line** equals the **totalAmount** on the payment. ### Refunding a credit note A bill payment refunding a credit note has one entry in its **lines** array. This line has the following properties: - An **amount** indicating the amount of the credit note that was refunded. This is always negative, indicating that it is a refund. - A **links** array containing one element with the following properties: - A **type** indicating the type of `link`, in this case a `CreditNote`. - An **id** containing the ID of the credit note that was refunded. The **totalAmount** field on the payment equals the line's **amount** field. These are both negative, as this is money leaving accounts payable. ### Refunding a payment If a payment is refunded, for example, when a company overpaid a bill and the overpayment is returned, there are two payment records: - One for the incoming overpayment. - Another for the outgoing refund. The payment issuing the refund is identified by the fact that the **totalAmount** is negative. This payment has one entry in its lines array that have the following properties: - An **amount** indicating the amount that was refunded. This is always negative. - A **links** array containing one element with the following properties: - A **type** indicating the type of a the link, in this case a `BillPayment`. - An **id** containing the ID of the payment that was refunded. The **amount** field on the line equals the **totalAmount** on the payment and is negative as this is money leaving accounts payable. The payment that was refunded can be identified as it has a line where the `amount` on its `line` is positive and the type of the link is `Refund`. This payment may have several entries in its **lines** array if it was partly used to pay an bill. For example, a £1,050 payment paying a £1,000 bill with a refund of £50 has two lines: - One for £1,000 linked to the bill that was paid - Another for £50 linked to the payment that refunded the over payment. This link is of type `Refund` but the ID corresponds to a bill payment. The line linked to the bill payment has the following properties: - An **amount** indicating the amount that was refunded. This is positive as its money that was added to accounts payable, but is balanced out by the negative amount of the refund. - A **links** array containing one element with the following properties: - A **type** indicating the type of the link, in this case a `Refund`. - An **id** containing the ID of the payment that refunded this line. > Linked payments > > Not all accounting software support linked payments in this way. In these platforms you may see a payment on account and a refund on account. ## Foreign currencies There are two types of currency rate that are detailed in the bill payments data type: Payment currency rate: - Base currency of the accounts payable account. - Foreign currency of the bill payment. Payment line link currency rate: - Base currency of the item that the link represents. - Foreign currency of the payment. These two rates allow the calculation of currency loss or gain for any of the transactions affected by the payment lines. The second rate is used when a bill payment is applied to an item in a currency that does not match either: - The base currency for the accounts payable account. - The currency of the item.
Unified_API
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "#/components/schemas/AccountingBillPayment",
"title": "Accounting: Bill payment",
"description": "> **Bill payments or payments?** \n> \n> We distinguish between transactions where the company received money vs. paid money. If the transaction represents a company spending money (accounts payable) we call this a Bill payment.\n>\n> See [payments](https://docs.codat.io/lending-api#/schemas/Payment) for the accounts receivable equivalent of Bill payments, which covers [invoices](https://docs.codat.io/lending-api#/schemas/Invoice) and [credit notes](https://docs.codat.io/lending-api#/schemas/CreditNote).\n\n## Overview\n\nBill payments include all accounts payable transaction data ([bills](https://docs.codat.io/lending-api#/schemas/Bill) and [credit notes against bills](https://docs.codat.io/lending-api#/schemas/BillCreditNote)).\n\nA bill payment in Codat usually represents an allocation of money within any customer accounts payable account. This includes, but is not strictly limited to:\n\n- A payment made against a bill \u2014 for example, a credit card payment, cheque payment, or cash payment.\n- An allocation of a supplier's credit note to a bill or perhaps a refund.\n- A bill payment made directly to an accounts payable account. This could be an overpayment or a prepayment, or a refund of a payment made directly to an accounts payable account.\n\nDepending on the bill payments which are allowed by the underlying accounting software, some of these types may be combined. Please see the example data section for samples of what these cases look like.\n\nIn Codat, a bill payment contains details of:\n\n- When the bill payment was recorded in the accounting system.\n- How much it is for and in the currency.\n- Who the payment has been paid to, the _supplier_.\n- The types of bill payments, the _line items_. \n\nSome accounting software 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_. You can find these types of transactions in our [Direct costs](https://docs.codat.io/lending-api#/schemas/DirectCost) data model.\n\nBill payments is a child data type of [account transactions](https://docs.codat.io/lending-api#/schemas/AccountTransaction).\n\n---\n\n## Bill payment types\n\n### Payment of a bill\n\nA payment paying a single bill should have the following properties:\n\n- A `totalAmount` indicating the amount of the bill that was paid. This is always positive.\n- A `lines` array containing one element with the following properties:\n - An `amount` equal to the `totalAmount` above.\n - A `links` array containing one element with the following properties:\n - A `type` indicating the type of link, in this case a `Bill`.\n - An `id` containing the ID of the bill that was paid.\n - An amount of `-totalAmount` (negative `totalAmount`), indicating that the entirety of the paid amount is allocated to the bill.\n\n### Payment of multiple bills\n\nIt is possible for one payment to pay multiple bills. This can be represented using two possible formats, depending on how the supplier keeps their books:\n\n1. The payment has multiple entries in its **lines** array, one for each bill that is paid. Each line will follow the above example for paying a bill, and the rules detailed in the data model.\n2. The payment has a line with multiple links to each bill. This occurs when the proportion of the original payment allocated to each bill is not available.\n\nEach line is the same as those described above, with the **amount** indicating how much of the payment is allocated to the bill. The **amount** on the lines sum to the **totalAmount** on the payment.\n\n> Pushing batch payments to Xero\n> \n> When pushing a single bill payment to Xero to pay multiple bills, only the first format is supported\u2014multiple entries in the payment **lines** array.\n\n### Payments and refunds on account\n\nA payment on account, that is a payment that doesn\u2019t pay a specific bill, has one entry in its lines array.\n\nThe line has the following properties:\n\n- A **totalAmount** indicating the amount paid by a supplier or refunded to them by a company. A payment to the supplier is always negative. A refund is always positive.\n- A **links** array containing one element with the following properties:\n - A **type** indicating the type of link. For a payment this is `PaymentOnAccount`. For a refund this is `Refund`.\n - The **id** containing the ID of the supplier.\n - An amount for the link is `0` **totalAmount** or the amount of the payment or refund.\n\nIt is possible to have a payment that is part on account and part allocated to a bill. Each line should follow the examples above.\n\n### Using a credit note to pay a bill\n\nThe payment of a bill using a credit note has one entry in its `lines` array. This **line** has the following properties:\n\n- An **amount** indicating the amount of money moved, which in this case is `0`, as the credit note and bill allocation must balance each other.\n- A **links** array containing two elements:\n - The first link has:\n - A **type** indicating the type of link, in this case a `Bill`.\n - An **id** containing the ID of the bill that was paid.\n - The second link has:\n - A **type** indicating the type of link, in this case a `CreditNote`.\n - An **id** containing the ID of the credit note used by this payment.\n\nThe **amount** field on the **line** equals the **totalAmount** on the payment.\n\n### Refunding a credit note\n\nA bill payment refunding a credit note has one entry in its **lines** array. This line has the following properties:\n\n- An **amount** indicating the amount of the credit note that was refunded. This is always negative, indicating that it is a refund.\n- A **links** array containing one element with the following properties:\n - A **type** indicating the type of `link`, in this case a `CreditNote`.\n - An **id** containing the ID of the credit note that was refunded.\n\nThe **totalAmount** field on the payment equals the line's **amount** field. These are both negative, as this is money leaving accounts payable.\n\n### Refunding a payment\n\nIf a payment is refunded, for example, when a company overpaid a bill and the overpayment is returned, there are two payment records: \n\n- One for the incoming overpayment.\n- Another for the outgoing refund.\n\nThe payment issuing the refund is identified by the fact that the **totalAmount** is negative. This payment has one entry in its lines array that have the following properties:\n\n- An **amount** indicating the amount that was refunded. This is always negative.\n- A **links** array containing one element with the following properties:\n - A **type** indicating the type of a the link, in this case a `BillPayment`.\n - An **id** containing the ID of the payment that was refunded.\n\nThe **amount** field on the line equals the **totalAmount** on the payment and is negative as this is money leaving accounts payable.\n\nThe payment that was refunded can be identified as it has a line where the `amount` on its `line` is positive and the type of the link is `Refund`. This payment may have several entries in its **lines** array if it was partly used to pay an bill. For example, a \u00a31,050 payment paying a \u00a31,000 bill with a refund of \u00a350 has two lines: \n\n- One for \u00a31,000 linked to the bill that was paid\n- Another for \u00a350 linked to the payment that refunded the over payment. This link is of type `Refund` but the ID corresponds to a bill payment.\n\nThe line linked to the bill payment has the following properties:\n\n- An **amount** indicating the amount that was refunded. This is positive as its money that was added to accounts payable, but is balanced out by the negative amount of the refund.\n- A **links** array containing one element with the following properties:\n - A **type** indicating the type of the link, in this case a `Refund`.\n - An **id** containing the ID of the payment that refunded this line.\n\n> Linked payments\n> \n> Not all accounting software support linked payments in this way. In these platforms you may see a payment on account and a refund on account.\n\n## Foreign currencies\n\nThere are two types of currency rate that are detailed in the bill payments data type: \n\nPayment currency rate: \n\n- Base currency of the accounts payable account.\n- Foreign currency of the bill payment.\n\nPayment line link currency rate: \n\n- Base currency of the item that the link represents.\n- Foreign currency of the payment.\n\nThese two rates allow the calculation of currency loss or gain for any of the transactions affected by the payment lines. The second rate is used when a bill payment is applied to an item in a currency that does not match either:\n\n- The base currency for the accounts payable account. \n- The currency of the item.\n",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier for the bill payment, unique for the company in the accounting software.",
"example": "3d5a8e00-d108-4045-8823-7f342676cffa"
},
"supplierRef": {
"allOf": [
{
"$ref": "#/components/schemas/AccountingSupplier/definitions/supplierRef"
},
{
"description": "Supplier against which the payment is recorded in the accounting software."
}
]
},
"accountRef": {
"$ref": "#/components/schemas/AccountingAccount/definitions/accountRef",
"description": "Account the payment is linked to in the accounting software."
},
"totalAmount": {
"type": "number",
"format": "decimal",
"description": "Amount of the payment in the payment currency. This value never changes and represents the amount of money that is paid into the supplier's account.",
"example": 1329.54
},
"currency": {
"allOf": [
{
"$ref": "#/components/schemas/SourceAccount/properties/currency"
},
{
"description": "ISO currency code in which the bill payment is recorded in the accounting software."
}
]
},
"currencyRate": {
"$ref": "#/components/schemas/AccountingPaymentAllocation/definitions/paymentAllocationPayment/properties/currencyRate"
},
"date": {
"allOf": [
{
"$ref": "#/components/schemas/DateTime"
},
{
"description": "Date the bill payment was recorded in the accounting software."
}
]
},
"note": {
"type": "string",
"nullable": true,
"description": "Additional information associated with the payment.",
"example": "Bill Payment against bill c13e37b6-dfaa-4894-b3be-9fe97bda9f44"
},
"paymentMethodRef": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentMethodRef"
},
{
"description": "The Payment Method to which the payment is linked in the accounting software."
}
]
},
"lines": {
"type": "array",
"nullable": true,
"description": "An array of bill payment lines.",
"items": {
"$ref": "#/components/schemas/AccountingBillPayment/definitions/billPaymentLine"
}
},
"reference": {
"type": "string",
"nullable": true,
"description": "Additional information associated with the payment."
},
"metadata": {
"$ref": "#/components/schemas/Metadata"
},
"supplementalData": {
"$ref": "#/components/schemas/SupplementalData"
}
}
},
{
"$ref": "#/components/schemas/CommerceOrder/allOf/3"
}
],
"required": [
"date"
],
"definitions": {
"billPaymentLine": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"format": "decimal",
"description": "Amount in the bill payment currency."
},
"links": {
"type": "array",
"nullable": true,
"items": {
"$ref": "#/components/schemas/AccountingBillPayment/definitions/billPaymentLineLink"
}
},
"allocatedOnDate": {
"$ref": "#/components/schemas/DateTime",
"description": "AllocatedOnDate must be specified and be later than the issue date of the bill."
}
},
"required": [
"amount"
]
},
"billPaymentLineLink": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/AccountingBillPayment/definitions/billPaymentLineLinkType"
},
"id": {
"type": "string",
"nullable": true,
"description": "Unique identifier of the transaction represented by the link."
},
"amount": {
"type": "number",
"format": "decimal",
"nullable": true,
"description": "Amount by which the balance of the linked entity is altered, in the currency of the linked entity.\n\n- A negative link amount reduces the outstanding amount on the accounts payable account.\n- A positive link amount increases the outstanding amount on the accounts payable account."
},
"currencyRate": {
"$ref": "#/components/schemas/AccountingPaymentAllocation/definitions/paymentAllocationPayment/properties/currencyRate"
}
},
"required": [
"type"
]
},
"billPaymentLineLinkType": {
"description": "Types of links to bill payment lines.",
"type": "string",
"enum": [
"Unknown",
"Unlinked",
"Bill",
"Other",
"CreditNote",
"BillPayment",
"PaymentOnAccount",
"Refund",
"ManualJournal",
"Discount"
]
}
},
"examples": [
{
"totalAmount": 1000,
"lines": [
{
"amount": 1000,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -1000
}
]
}
]
},
{
"totalAmount": 0,
"lines": [
{
"amount": 0,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -1000
},
{
"type": "CreditNote",
"id": "y",
"amount": 1000
}
]
}
]
},
{
"totalAmount": 2000,
"lines": [
{
"amount": 1000,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -1000
}
]
},
{
"amount": 1000,
"links": [
{
"type": "PaymentOnAccount",
"id": "y",
"amount": -1000
}
]
}
]
},
{
"totalAmount": -1000,
"lines": [
{
"amount": -1000,
"links": [
{
"type": "CreditNote",
"id": "y",
"amount": 1000
}
]
}
]
},
{
"totalAmount": -1000,
"lines": [
{
"amount": -1000,
"links": [
{
"type": "PaymentOnAccount",
"id": "y",
"amount": 1000
}
]
}
]
},
{
"totalAmount": 250,
"lines": [
{
"amount": 0,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -750
},
{
"type": "CreditNote",
"id": "y",
"amount": 750
}
]
},
{
"amount": 250,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -250
}
]
}
]
},
{
"totalAmount": 1000,
"lines": [
{
"amount": 1000,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -1000
}
]
}
],
"modifiedDate": "2022-10-23T00:00:00Z",
"sourceModifiedDate": "2022-10-23T00:00:00Z"
},
{
"totalAmount": 2000,
"lines": [
{
"amount": 0,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -1000
},
{
"type": "CreditNote",
"id": "y",
"amount": 1000
}
]
},
{
"amount": 0,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -1000
},
{
"type": "CreditNote",
"id": "z",
"amount": 1000
}
]
},
{
"amount": 1000,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -1000
}
]
},
{
"amount": 1000,
"links": [
{
"type": "PaymentOnAccount",
"id": "customer-001",
"amount": -1000
}
]
}
]
},
{
"totalAmount": 0,
"lines": [
{
"amount": 0,
"links": [
{
"type": "Bill",
"id": "w",
"amount": -1000
},
{
"type": "Bill",
"id": "x",
"amount": -1000
},
{
"type": "CreditNote",
"id": "y",
"amount": 1000
},
{
"type": "CreditNote",
"id": "z",
"amount": 1000
}
]
}
]
},
{
"totalAmount": 1000,
"lines": [
{
"amount": 1000,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -1000
}
]
}
],
"modifiedDate": "2022-10-23T00:00:00Z",
"sourceModifiedDate": "2022-10-23T00:00:00Z"
},
{
"id": "001",
"totalAmount": 5000,
"date": "1901-01-01",
"lines": [
{
"amount": 1000,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -1000
}
]
},
{
"amount": 4000,
"links": [
{
"type": "PaymentOnAccount",
"id": "y",
"amount": -4000
}
]
}
]
},
{
"id": "001",
"totalAmount": 5000,
"date": "1901-01-01",
"lines": [
{
"amount": 1000,
"links": [
{
"type": "Bill",
"id": "x",
"amount": -1000
}
]
},
{
"amount": 1000,
"links": [
{
"type": "Bill",
"id": "y",
"amount": -1000
}
]
},
{
"amount": 3000,
"links": [
{
"type": "PaymentOnAccount",
"id": "y",
"amount": -3000
}
]
}
]
},
{
"totalAmount": 500,
"lines": [
{
"amount": 500,
"links": [
{
"type": "Bill",
"id": "a",
"amount": -1000
},
{
"type": "Bill",
"id": "b",
"amount": -1000
},
{
"type": "CreditNote",
"id": "y",
"amount": 750
},
{
"type": "CreditNote",
"id": "z",
"amount": 750
}
]
}
]
}
]
}