Bills

An itemized record of goods purchased from or services provided by a vendor.

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

Reference Types

Purchase order 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.

sourceModifiedData

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

decimal

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.

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.

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

{
  "data":
  [
    {
      "id": "1",
      "vendorRef":
      {
        "id": "1",
        "name": "Home Reno Inc"
      },
      "purchaseOrderRef":
      {
        "id": "15",
        "purchaseOrderNumber": "1500"
      },
      "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,
          "accountRef":
          {
            "id": "145",
            "name": "Professional Services"
          },
          "discountPercentage": 10.5,
          "taxRateRef":
          {
            "id": "1",
            "name": "HST",
            "effectiveTaxRate": 13
          },
          "inventoryRef":
          {
            "id": "1",
            "name": "Digital Services"
          }
        }
      ],
      "status": "open",
      "subTotal": 301.5,
      "taxAmount": 20.5,
      "totalAmount": 322,
      "amountDue": 322,
      "memo": "Sample bill memo.",
      "payments":
      [
        {
          "amount": 50.5,
          "paymentId": "50",
          "date": "2021-03-09T10:18:29.985Z"
        }
      ],
      "sourceModifiedDate": "2021-03-09T10:18:29.985Z"
    }
  ]
}

Did this page help you?