Bill payments

Explore BillPayments endpoints in Swagger.

Overview

Bill payments include all accounts payable transaction data. This includes bills and credit notes against bills.

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, like a credit card, cheque, or cash payment.
  • An allocation of a supplier's credit note, either to a bill or maybe a refund.
  • A bill payment made directly to that accounts payable account. This could be an overpayment or a prepayment. It might also be a refund of a payment made directly to an accounts payable account.

Depending on the bill payments allowed by the underlying accounting package, some of these types may be combined. Please see the Example data section for samples of what these cases would 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 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 itemised breakdown of the purchase in the Bills dataset and the corresponding payment here.

📘

Bill payments or payments?

In Codat, bill payments represent accounts payable only. For accounts receivable, see payments, which includes invoices and credit notes.

Data model

FieldTypeDescription
id string Identifier for the bill payment, unique for the company in the accounting platform.
supplierRef See reference typesSupplier against which the payment is recorded in the accounting platform.
accountRef See reference typesAccount the payment is linked to in the accounting platform.
totalAmount decimalAmount 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.
currency string
See currency
ISO currency code in which the bill payment is recorded in the accounting platform.
currencyRate decimal
see currency rate
Rate to convert the total amount of the bill payment into the base currency for the company, at the time of the payment.
date string
See date
Date the bill payment was recorded in the accounting software.
note stringAny additional information associated with the payment.
paymentMethodRefSee reference typesPaymentMethod the payment is linked to in the accounting platform.
lines An array of BillPaymentLines.
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.

Supplier reference

FieldTypeDescription
id stringUnique identifier for the supplier the payment is recorded against in the accounting platform.
supplierName stringName of the supplier the payment is recorded against in the accounting platform.

Lines

A bill payment line is an allocation of the portion of the bill payment. The sum of the line amounts should be equal to the total amount.

FieldTypeDescription
amount decimalAmount in the bill payment currency.
links See BillPaymentLineLink.

Links

The allocations of the bill payment. The sum of the amount in links plus the line amount must be equal to zero.

FieldTypeDescription
type stringTypes of links to bill payment lines, either:
+ Unlinked - Not used

+ Bill - ID refers to the bill that was paid

+ CreditNote - ID refers to the credit note used payment

+ Refund - ID refers to the sibling payment

+ BillPayment - ID refers to the sibling payment

+ PaymentOnAccount - ID refers to the supplier

+ Other - Not currently supported by Codat
id stringUnique identifier of the transaction represented by the link.
amount decimalAmount by which the balance of the linked entity is altered, in the currency of the linked entity.
+ A negative link amount reduces the outstanding amount on the accounts payable account.

+ A positive link amount increases the outstanding amount on the accounts payable account.
currencyRate decimalCalculated as the amount of the bill payment allocated in the currency of the bill payment divided by the amount of the linked entity in the currency of the entity. When bill payment currencies and linked entity currencies are always the same, the currencyRate is 1.

🚧

Requirements for reference fields

The supplier reference fields 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 suppliers data type for supplierRef.

Bill payment types

Payment of a bill

A payment paying a single bill has one entry in its lines array.

The line has the following properties:

  • An amount indicating the amount of the bill that was paid. This is always positive.
  • 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 for the link is 0 totalAmount or the amount of the payment allocated to the bill.
      The amount field of the line equals the totalAmount on the bill payment.

Payment of multiple bills

It is possible for one payment to pay multiple bills. This can be represented in two possible formats depending on how the supplier keeps their books:

  • 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.
  • 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.

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 packages 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.
{
    "id": "123",
    "note": ""
    "totalAmount": 99.99,
    "currency": "GBP",
    "lines": [
        {
            "amount": 99.99,
            "links": [
                {
                    "type": "Invoice",
                    "id": "178",
                    "amount": -50,
                    "currencyRate":  1.9998,
                }
            ]
        }
    ]
}

Example data

📘

Object properties

For the sake of brevity, the examples here may omit properties from objects. For the full object definition, see BillPayments.

Simple 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
                }
            ]
        }
    ]
}
{
    "id" : billpayment-001",
    "totalAmount": 1000,
    "lines": [
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Refund",
                    "id" : "refund-001",
                    "amount" : -1000
                }
            ]
        }
    ]
}
{
    "id" : "refund-001",
    "totalAmount": -1000,
    "lines": [
        {
            "amount" : -1000,
            "links" : [
                {
                    "type" : "BillPayment",
                    "id" : "billpayment-001",
                    "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
                }
            ]
        }
    ]
}

Complex examples

{
    "totalAmount": 1000,
    "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
                }
            ]
        }
    ]
}
{
    "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": 2000,
    "lines": [
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Bill",
                    "id" : "w",
                    "amount" : -1000
                },
                {
                    "type" : "Bill",
                    "id" : "x",
                    "amount" : -1000
                },
                {
                    "type" : "Bill",
                    "id" : "u",
                    "amount" : -1000
                },
                {
                    "type" : "CreditNote",
                    "id" : "y",
                    "amount" : 1000
                },
                {
                    "type" : "CreditNote",
                    "id" : "z",
                    "amount" : 1000
                }
            ]
        },
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Refund",
                    "id" : "refund-001",
                    "amount" : -1000
                }
            ]
        }
    ]
}
{
    "id" : "refund-001",
    "totalAmount": -1000,
    "lines": [
        {
            "amount" : -1000,
            "links" : [
                {
                    "type" : "BillPayment",
                    "id" : "payment-001",
                    "amount" : 1000
                }
            ]
        }
    ]
}

Bill Payment on account is used to pay invoice in January and February:

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

Did this page help you?