Bills

Overview

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. See Bills endpoint for more details.

📘
Direct Purchases
Some accounting service providers refer to direct purchases, such as something bought on a credit card or online payment. One example of this would be QuickBooks Online's expenses. These items don't have a separate data type, so you'll see the itemized breakdown of the purchase here and the corresponding payment in Bill Payments. The payment information will also be populated in the bill's payments.

Data Model

Field	Type	Description
id	string	Identifier for the bill, unique to the business in the accounting service provider.
vendorRef	Reference Types	Vendor that issued the bill.
purchaseOrderRef	deprecated, Reference Types	Please use the `purchaseOrderRefs` field, `purchaseOrderRef` will be deprecated in the future.
purchaseOrderRefs	Reference Types	An array of purchase orders against the bill.
postedDate sortable, filterable	string See Date	Date of the bill as recorded in the accounting service provider.
dueDate sortable, filterable	string See Date	Date the vendor is due to be paid.
currencyRef	Reference Types	Currency 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	decimal	Rate between the currency of the bill and the base currency of the business. Not applicable when multi-currency is not supported.
lines	array	An array of bill lines.
status sortable, filterable	string	Current status of a bill.
subTotal sortable, filterable	decimal	Value of the bill, including discounts and excluding tax.
taxAmount sortable, filterable	decimal	Any tax applied to the bill amount.
totalAmount sortable, filterable	decimal	Amount of the bill, inclusive of tax.
amountDue sortable, filterable	decimal	Amount outstanding on the bill.
memo	string	User-friendly reference for the bill.
payments	array	An array of bill payments.
subsidiaryRefs	Reference Types	An array of subsidiaries the bill refers to.
locationRef	Reference Types	The business location associated with the bill.
sourceModifiedData sortable, filterable	string See Date	Date the record was last changed in the accounting service provider.

Lines

Field	Type	Description
description	string	Friendly name of the goods or services received.
unitAmount	decimal	Price of each unit of goods or services.
quantity	integer	Number of units of goods or services.
discountAmount	decimal	Numerical value of any discounts applied.
discountPercentage	decimal	Percentage rate (from 0 to 100) of any discounts applied to the unit amount.
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, inclusive of discounts and tax.
accountRef	Reference Types	Reference to the account to which the line item is linked to.
locationRef	Reference Types	Reference to the location to which the line item is linked to.
taxRateRef	Reference Types	Reference 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.
inventoryRef	Reference Types	Reference to the product or inventory item to which the line item is linked to.
trackingCategoryRef	Reference Types	Reference to the tracking category to which the line item is linked to.

Payments

Field	Type	Description
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.

Example Data

{
  "id": "1",
  "vendorRef":
  {
    "id": "1",
    "name": "Home Depot"
  },
  "purchaseOrderRef":
  {
    "id": "15",
    "purchaseOrderNumber": "1500"
  },
  "purchaseOrderRefs":
  [
    {
      "id": "21",
      "purchaseOrderNumber": "PO324"
    }
  ],
  "postedDate": "2021-03-09T10:18:29.985Z",
  "dueDate": "2021-03-09T10:18:29.985Z",
  "currencyRef":
  {
    "id": "CAD",
    "name": "Canadian Dollar"
  },
  "currencyRate": 1.13,
  "lines":
  [
    {
      "description": "Services rendered.",
      "unitAmount": 100.5,
      "quantity": 3,
      "discountAmount": 0,
      "subTotal": 301.5,
      "taxAmount": 20.5,
      "totalAmount": 322,
      "discountPercentage": 10.5,
      "taxRateRef":
      {
        "id": "1",
        "name": "HST",
        "effectiveTaxRate": 13
      },
      "inventoryRef":
      {
        "id": "1",
        "name": "Digital Services"
      },
      "trackingCategoryRef":
      {
        "id": "4040",
        "name": "Region",
        "option": "East",
        "optionId": "40401"
      },
      "accountRef":
      {
        "id": "145",
        "name": "Depreciation Expense"
      }
    }
  ],
  "status": "open",
  "subTotal": 301.5,
  "taxAmount": 20.5,
  "totalAmount": 322,
  "amountDue": 322,
  "memo": "Example bill memo.",
  "payments":
  [
    {
      "amount": 50.5,
      "paymentId": "50",
      "date": "2021-03-09T10:18:29.985Z"
    }
  ],
  "subsidiaryRefs":
  [
    {
      "id": "1",
      "name": "Railz Financial"
    }
  ],
  "locationRef":
  {
    "id": "52",
    "name": "United States"
  },
  "sourceModifiedDate": "2021-03-09T10:18:29.985Z"
}

Overview

📘Direct Purchases

Data Model

Lines

Payments

Bill Status

Example Data

📘
Direct Purchases