Payments

Used to query, insert, and delete payment records within Xero. Payments include transactions made to suppliers or received from customers.

Table Specific Information

The Payments table allows you to SELECT and INSERT payments for a Xero organization.

Note that this tables does not include payments on expense claims - to retrieve those, you will need to read from the ExpenseClaimPayments view.

Optimized Filters and High Volume Thresholds

The Xero API defines a list of optimized filters for certain tables and views. If any query filter not included in this list is applied to any such table or view, and the number of records available in that table or view exceeds a certain value (what Xero calls a "high volume threshold"), the Xero API will block the query.

To avoid the rejection of your queries by the Xero API, if the the number of records in your table or view exceed the high volume threshold, make sure to use filters from the list of optimized filters.

Note that the high volume threshold, as well as the exact list of optimized filters, is subject to change as Xero updates its API.

The Payments table has a high volume threshold of 100,000. The Xero API lists the following optimized filters for this table:

Optimized columns (when used in WHERE clauses):
- Optimized for standalone use in WHERE clause or in an AND clause:
  - PaymentType
  - Status
  - Date
  - Invoice.InvoiceId
  - Reference
- Optimized for use in OR clause:
  - Invoice.InvoiceId
  - PaymentID
Optimized ORDER BY columns:
- PaymentID
- UpdatedDateUTC
- Date

SELECT

The Xero API allows extensive filtering and ordering. You can define WHERE and ORDER BY clauses in a query to filter and order the results using any non-line-item column.

Note: The Xero API does not support filtering on line items or journal lines.

INSERT

To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new payment record, the InvoiceNumber and AccountCode fields are required.

Columns


Name	Type	ReadOnly	Description
PaymentId [KEY]	String	True	The unique identifier assigned to the payment. This ID is used to reference and track the payment transaction in the system.
Date	Date	False	The date when the payment was made. This represents the transaction date and helps in recording when the payment occurred in the accounting system.
Amount	Decimal	False	The total amount of the payment. This value should not exceed the outstanding balance on the invoice it is being applied to, ensuring the payment is applied correctly.
CurrencyRate	Decimal	False	The exchange rate applied when the payment is received, particularly for non-base currency invoices and credit notes. This helps in calculating the payment amount in the base currency.
Reference	String	False	An optional field to provide additional reference information for the payment, such as payment method or transaction reference.
PaymentType	String	False	The type of payment, which helps categorize the nature of the transaction (for example, 'BANK', 'CREDIT', 'CASH').
Status	String	False	The current status of the payment. This could indicate whether the payment is 'PENDING', 'COMPLETED', or 'FAILED'.
UpdatedDateUTC	Datetime	False	The timestamp when the payment was last updated. This helps track changes and updates made to the payment after it was initially recorded.
IsReconciled	Boolean	False	Indicates whether the payment has been reconciled with the relevant financial accounts. This is only available when querying a single payment.
BatchPaymentId	String	True	The identifier of the batch payment, if the payment was processed as part of a batch. This links the payment to the corresponding batch transaction.
InvoiceId	String	False	The identifier of the invoice being paid. When applying a payment, specify either the 'InvoiceId' or 'InvoiceNumber' to identify the associated invoice.
InvoiceNumber	String	False	The invoice number for the invoice or credit note being paid. This field allows for identifying the invoice when making payments, and can be used instead of the 'InvoiceId'.
CreditNoteId	String	False	The identifier of the credit note associated with the payment. Specify either the 'CreditNoteId' or 'CreditNoteNumber' when applying a payment to a credit note.
CreditNoteNumber	String	False	The credit note number for the credit note being paid. This field can be used instead of the 'CreditNoteId' to apply payments to a credit note.
AccountId	String	False	The identifier of the account from which the payment was made. The account type must be 'BANK', or payments must be enabled for the account.
AccountCode	String	False	The account code of the account used for the payment. This code helps specify the correct account to apply the payment against in the financial system.
TenantId	String	False	The unique identifier for the tenant. This ensures that the query retrieves payment data specific to a particular tenant in multi-tenant systems.

Copyright (c) 2025 CData Software, Inc. - All rights reserved.

Build 25.0.9434