Invoices

An itemized record of goods purchased by or services provided to a customer.

Overview

An Invoice is an Accounts Receivable transaction representing a request-for-payment to Customers for goods/services rendered, sent, or both. From the Invoice endpoint, you can retrieve a list of all invoices for a specified business. See Invoices endpoint for more details.

Data Model

Field

Type

Description

id

string

Identifier for the invoice, unique to the business in the accounting service provider.

invoiceNumber

string

Friendly reference for the invoice. If available, this appears in the file name of invoice attachments.

customerRef

Reference Types

Reference to the customer the invoice has been issued to.

postedDate
sortable, filterable

string
See Date

Date of the invoice as recorded in the accounting service provider.

dueDate
sortable, filterable

string
See Date

Date the invoice is due to be paid by.

currencyRef

Reference Types

Currency of the invoice.

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 invoice and the base currency of the business. Not applicable when multi-currency is not supported.

lines

array

An array of invoice lines.

status
sortable, filterable

string

Current status of an invoice.

subTotal
sortable, filterable

decimal

Value of the invoice, including discounts and excluding tax.

taxAmount
sortable, filterable

decimal

Any tax applied to the invoice amount.

totalAmount
sortable, filterable

decimal

Amount of the invoice, inclusive of tax.

amountDue
sortable, filterable

decimal

Amount outstanding on the invoice.

memo

string

User-friendly reference for the invoice.

payments

array

An array of invoice 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, a valid tax rate reference must be used by querying Tax Rates and using the id parameter as a value. For Xero, use code parameter as a value.

inventoryRef

Reference Types

Reference to the product or inventory item to which the line item is linked to.

When pushing data, a valid inventory item reference must be used by querying Inventory and using the id parameter as a value. For Xero, use code parameter as a value.

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

paymentId

string

Identifier of the invoice payments data type.

date

string
See Date.

Date of the payment.

Invoice Status

  • open - Invoice is no longer a draft. It has been processed and/or sent to the customer. In this state, it will impact the ledger. It also has no payments made against it (amountDue == totalAmount).
  • partiallyPaid - The balance paid against the invoice is positive, but less than the total invoice amount (0 < amountDue < totalAmount).
  • paid - Invoice is paid in full. This includes if the invoice has been credited or overpaid. (amountDue == 0).
  • void - An invoice can become void by being deleted, refunded, written off, or cancelled. A voided invoice may still be partially paid and so all outstanding amounts on voided invoices are removed from the accounts receivable account.
  • draft - Invoice is yet to be authorized and sent to the customer, 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 invoice. This can be due to missing values in the accounting service provider or unavailable in the data we received.

Example Data

{
  "data":
  [
    {
      "id": "1",
      "invoiceNumber": "INV-1001",      
      "customerRef":
      {
        "id": "1",
        "name": "Home Reno Inc"
      },
      "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 invoice 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?