The Bill Object

A Bill is an Accounts Payable transaction representing a request-for-payment from Vendors for goods/services rendered, received, or both. From the Bills endpoint, you can retrieve a list of all bills for a specified business.

idstring Identifier for the bill, unique to the business in the accounting service provider.
vendorRef Reference TypesVendor that issued the bill.
purchaseOrderRefdeprecated, Reference TypesPlease use the purchaseOrderRefs field, purchaseOrderRef will be deprecated in the future.
purchaseOrderRefsReference TypesAn array of purchase orders against the bill.
sortable, filterable
See Date
Date of the bill as recorded in the accounting service provider.
sortable, filterable
See Date
Date the vendor is due to be paid.
currencyRef Reference TypesCurrency of the bill.

Pushing data will fail if the business has not enabled or does not support multiple currency. Leaving this blank would default to the business' default currency.
currencyRate decimalRate between the currency of the bill and the base currency of the business. Not applicable when multi-currency is not supported.
lines arrayAn array of bills lines.
sortable, filterable
stringCurrent status of a bill.
sortable, filterable
decimalValue of the bill, including discounts and excluding tax.
sortable, filterable
decimalAny tax applied to the bill amount.
sortable, filterable
decimalAmount of the bill, inclusive of tax.
sortable, filterable
decimalAmount outstanding on the bill.
memo stringUser-friendly reference for the bill.
payments arrayAn array of bill payments.
subsidiaryRefsReference TypesAn array of subsidiaries the bill refers to.
locationRefReference TypesThe business location associated with the bill.
sortable, filterable
See Date
Date the record was last changed in the accounting service provider.


description string Friendly name of the goods or services received.
unitAmount decimal Price of each unit of goods or services.
quantity integerNumber of units of goods or services.
discountAmount decimalNumerical value of any discounts applied.
discountPercentage decimalPercentage rate (from 0 to 100) of any discounts applied to the unit amount.
subTotal decimalAmount of the line, inclusive of discounts but exclusive of tax.
taxAmount decimalAmount of tax for the line.
totalAmount decimalTotal amount of the line, inclusive of discounts and tax.
accountRef Reference TypesReference to the account to which the line item is linked to.
locationRefReference TypesReference to the location to which the line item is linked to.
taxRateRef Reference TypesReference to the tax rate to which the line item is linked to.

When pushing data to Xero, use a valid tax rate reference by querying Tax Rates and using the code parameter as a value.
inventoryRefReference TypesReference to the product or inventory item to which the line item is linked to.
trackingCategoryRefReference TypesReference to the tracking category to which the line item is linked to.


amount decimal Payment amount in the currency of the bill.
paymentId string Identifier of the bill payments data type.
date string
See Date.
Date of the payment.

Bill Status

  • open - Bill is no longer a draft. It has been processed and/or sent to the vendor. 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.
  • draft - Bill is yet to be authorized and sent by the vendor, and will not be used in any reports. It may contain incomplete line items.
  • unknown - Railz was not able to recognize the status of the bill. This can be due to missing values in the accounting service provider or unavailable in the data we received.