Invoices

The Invoice object

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.

FieldTypeDescription
id
sortable, filterable
string Identifier for the invoice, unique for the business in the accounting service.
invoiceNumber
sortable, filterable
stringThe buyer facing document number of the invoice.
customerRefReference TypesReference to the customer the invoice was sent to.
postedDate
sortable, filterable
string
See Date
Date on which the invoice was posted to the accounting service, and had an impact on the general ledger. This may be different from the creation date.
dueDate
sortable, filterable
string
See Date
Date the customer is due to pay.
currency stringISO-4217 currency code of the invoice.
currencyRate decimalRate to convert the total amount of the transaction into the base currency for the business at the time of the transaction.
lines arrayAn array of invoice lines.
status
sortable, filterable
stringCurrent status of the invoice.
totalDiscount
sortable, filterable
decimalTotal amount of discounts applied to the invoice.
discountPercentage
sortable, filterable
decimalDiscount percentage applied to the invoice.
subTotal
sortable, filterable
decimalAmount of the invoice, inclusive of discounts but exclusive of tax.
taxAmount
sortable, filterable
decimalAmount of tax on the invoice.
totalAmount
sortable, filterable
decimalTotal amount of the invoice, inclusive of tax.
amountDue
sortable, filterable
decimalAmount outstanding of the invoice.
memo stringAny additional information or business notes about the invoice.
payments arrayAn array of payments allocations.
sourceModifiedDate
sortable, filterable
string
See Date
The date on which this record was last modified in the accounting service.

Lines

FieldTypeDescription
id
sortable, _filterable
stringThe Id of the line item.
description string Description of the line item.
unitAmount
sortable, filterable
decimal Line item unit amount.
quantity
sortable, filterable
integerLine item quantity.
discountAmount
sortable, filterable
decimalLine item discount amount.
discountPercentage
sortable, filterable
stringLine item discount percentage.
taxAmount
sortable, filterable
decimalLine item tax amount.
amount
sortable, filterable
decimalLine item total amount, inclusive of discounts & tax.
accountRef Reference TypesReference to the account the line item is linked to.
taxRateRef Reference TypesReference to the tax rate 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.
inventoryRefReference TypesReference to the product or inventory 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.
trackingCategoryRefsReference TypesReference to the tracking categories associated with this line item, e.g. classes or departments.

Payments

FieldTypeDescription
amount
sortable, filterable
decimal Total amount that was paid.
paymentId
sortable, filterable
string Identifier of the allocated payment.
date
sortable, filterable
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.

How to - User Guide

Step-by-step guide on utilizing this endpoint.