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
idstring Identifier for the invoice, unique to the business in the accounting service provider.
invoiceNumberstringFriendly reference for the invoice. If available, this appears in the file name of invoice attachments.
customerRefReference TypesReference 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 TypesCurrency 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 decimalRate between the currency of the invoice and the base currency of the business. Not applicable when multi-currency is not supported.
lines arrayAn array of invoice lines.
status
sortable, filterable
stringCurrent status of an invoice.
subTotal
sortable, filterable
decimalValue of the invoice, including discounts and excluding tax.
taxAmount
sortable, filterable
decimalAny tax applied to the invoice amount.
totalAmount
sortable, filterable
decimalAmount of the invoice, inclusive of tax.
amountDue
sortable, filterable
decimalAmount outstanding on the invoice.
memo stringUser-friendly reference for the invoice.
payments arrayAn array of invoice payments.
subsidiaryRefsReference TypesAn array of subsidiaries the invoice refers to.
sourceModifiedDate
sortable, filterable
string
See Date
Date the record was last changed in the accounting service provider.

Lines

FieldTypeDescription
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 stringPercentage 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, 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 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.
trackingCategoryRefReference TypesReference to the tracking category to which the line item is linked to.

Payments

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