CData Cloud offers access to Xero across several standard services and protocols, in a cloud-hosted solution. Any application that can connect to a SQL Server database can connect to Xero through CData Cloud.
CData Cloud allows you to standardize and configure connections to Xero as though it were any other OData endpoint or standard SQL Server.
This page provides a guide to Establishing a Connection to Xero in CData Cloud, as well as information on the available resources, and a reference to the available connection properties.
Establishing a Connection shows how to authenticate to Xero and configure any necessary connection properties to create a database in CData Cloud
Accessing data from Xero through the available standard services and CData Cloud administration is documented in further details in the CData Cloud Documentation.
Connect to Xero by selecting the corresponding icon in the Database tab. Required properties are listed under Settings. The Advanced tab lists connection properties that are not typically required.
When the Cloud starts, it opens a browser and requests your login information. The Cloud uses the credentials you provide to access your Xero data. These credentials are saved and automatically refreshed as needed.
To enable this authentication from all OAuth flows, you must set AuthScheme to OAuth, and you must create a custom OAuth application.
The following subsections describe how to authenticate to Xero from three common authentication flows:
For information about how to create a custom OAuth application, see Creating a Custom Authentication Application.
For a complete list of connection string properties available in Xero, see Connection.
Automatic refresh of the OAuth access token:
To have the Cloud automatically refresh the OAuth access token, do the following:
Manual refresh of the OAuth access token:
The only value needed to manually refresh the OAuth access token is the OAuth refresh token.
Store the OAuth refresh token so that you can use it to manually refresh the OAuth access token after it has expired.
The Cloud supports several Xero APIs. To connect to them, set the appropriate connection property:
Specifying Permitted Organization Access
For any of the above APIs, we also recommend setting the Tenant property, which enables you to authorize the Cloud to access multiple organizations. Tenant is normally set to identify one or more organizations that the Cloud can access. Legal entries for Tenant can be either the name of the organization or its ID. (Since multiple organizations can have the same name, we recommend using the ID to set the Tenant property.)
To register a custom connection application in Xero:
The Xero API has usage limitations that may be encountered while using the CData Cloud. Note that all of these apply on a per-application and per-organization basis. An application may exceed these limits if it is querying multiple organizations as long as it obeys the limits within each organization.
At most 5 API calls from the application may be active against the same organization at once. Typically this limit is not an issue because the Cloud will automatically retry the current request if this occurs.
At most 60 API calls per minute may be made from the application to the same organization. This limit is also not an issue as Xero reports a recommended delay time that the Cloud will use to avoid hitting the limit again.
Uncertified OAuth applications are limited to 25 connections. There is no limit on connections for certified apps.
At most 5000 API calls per day may be made from the application to the same organization. Hitting this limit is rare but can happen with certain tables (such as history tables and some reports) or certain settings (such as AutoExpandDetails) are used, as they require the Cloud to make a single API call for each invoice/contact/etc. that is read.
If this limit is hit frequently then the first step should be avoiding the
tables or settings that trigger it. It is also possible to convert the queries
into versions which read fewer rows at one time. This is usually done by
replacing simple selects with subqueries that pick out small groups of rows,
and then using multiple versions of these queries at different times:
/* Retrieves history for about 1/16 of the invoices */ SELECT * FROM HistoryInvoices WHERE InvoiceId IN ( SELECT InvoiceId FROM Invoices WHERE InvoiceId LIKE '0%' )
The RetryDailyLimit option is also available but its use is strongly discouraged, as in the worst cases the delays that Xero suggests can span several hours during which the Cloud will be unavailable. It is typically better to restructure how you request data to fit within the limits than to ignore the limits and execute queries that take multiple hours to run.
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.
See the pages for individual Tables and Views for their full list of optimized filters.
By default, the Cloud attempts to negotiate TLS with the server. The server certificate is validated against the default system trusted certificate store. You can override how the certificate gets validated using the SSLServerCert connection property.
To specify another certificate, see the SSLServerCert connection property.
To authenticate to an HTTP proxy, set the following:
Set the following properties:
The CData Cloud models five Xero APIs as easy-to-use SQL databases: Accounting, Australian Payroll, Files, Fixed Assets, and Projects. Set the Schema property and use the information in each section to select the proper API based on your project needs.
The Accounting Data Model contains the company's financial information, such as contacts, invoices and reporting. It also contains history tables which records changes to most kinds of entities.
INSERTs to specific tables which model line items in the Accounting API have batch support enabled. The recommended BatchSize setting for maximum performance is 50.
The Australian Payroll Data Model contains information on the company's employees, such as timesheets, leave and tax declarations.
INSERTs to specific tables which model line items in the Australian Payroll API have batch support enabled. The recommended BatchSize setting for maximum performance is 50.
The Files Data Model contains information on the files and attachments managed by Xero. It can be used to upload and download files, and attach them to accounting entities.
The Fixed Assets Data Model contains information on the company's fixed assets, such as registration, depreciation and resale.
The Projects Data Model contains information on the company's projects, such as billing and time tracking.
API limitations and requirements are documented in this section; you can use the SupportEnhancedSQL feature, set by default, to circumvent most of these limitations.
The Tables section, which details standard SQL tables, and the Views section, which lists read-only SQL tables, contain samples of what you might have access to in your Xero account.
Common tables include:
| Table | Description |
| Accounts | Allows for the querying, insertion, updating, and deletion of accounts for a Xero organization. Accounts represent the various financial categories used to track and record the organization's financial transactions, such as assets, liabilities, and equity. |
| BankTransactions | Queries, inserts, and updates bank transactions within Xero. Bank transactions include deposits, withdrawals, and other activities that affect the cash accounts of the organization. |
| Invoices | Used to query, insert, and update invoices within Xero. Invoices are sent to customers for payment for goods or services provided. |
| Payments | Used to query, insert, and delete payment records within Xero. Payments include transactions made to suppliers or received from customers. |
| Contacts | Used for querying, inserting, and updating contact records within a Xero organization. Contacts include customers, suppliers, and other entities that the organization interacts with for business transactions. |
| CreditNotes | Used to query, insert, and update credit notes for a Xero organization. Credit notes are used to adjust invoices, typically in cases of overpayment, returns, or errors. |
| Employees | Used for querying, inserting, and updating employee records within a Xero organization. Employees are individuals working for the organization and their data includes payroll, tax, and employment information. |
| ExpenseClaims | Used for querying, inserting, and updating expense claims. Expense claims are submitted by employees or contractors for reimbursement of business-related expenses. |
| BankTransfers | Manages bank transfer records. It allows for querying and editing transfers between accounts, helping track money movements between different bank accounts. |
| PurchaseOrders | Used to query, insert, and update purchase orders in Xero. Purchase orders are used to track items or services that the organization intends to buy from suppliers. |
| Receipts | Enables querying, inserting, and updating receipts for a Xero organization. Receipts confirm that payments have been made, and they help track money received by the organization. |
| ManualJournals | Used to query, insert, and update manual journals. Manual journals are used to record financial transactions that don't follow standard processes. |
| Items | Manages items in Xero. Items can be products, services, or other billable units used in transactions. |
| Journals | Used for querying line items in journals. Journals in Xero are used to record debits and credits for financial transactions. |
| TaxRates | Manages tax rates in Xero. It allows you to query, insert, and update tax rates, which are necessary for calculating tax liabilities on sales and purchases. |
| Users | Allows querying the list of users in a Xero organization. It includes user details like name, role, and access permissions, which are crucial for managing user access to financial data. |
| TrackingCategories | Enables querying tracking categories, which are used to segment financial transactions for better analysis and reporting. For example, you can track sales by region or department. |
| Prepayments | Used to query prepayment records. Prepayments refer to money paid before goods or services are received. |
| Overpayments | Used to query overpayments made within a Xero organization. This helps manage and apply payments that exceed the amount owed. |
| RepeatingInvoices | Allows you to query templates for repeating invoices in Xero. Repeating invoices are automatically generated for regular billing cycles such as monthly or yearly, reducing the need for manual invoicing. |
API limitations and requirements are documented in each table.
Stored Procedures are actions that are invoked via SQL queries. They perform tasks beyond standard create, read, update, delete (CRUD) operations, including managing invoices, attachments, and OAuth tokens.
The Cloud models the data in Xero as a list of tables in a relational database that can be queried using standard SQL statements.
| Name | Description |
| Accounts | Allows for the querying, insertion, updating, and deletion of accounts for a Xero organization. Accounts represent the various financial categories used to track and record the organization's financial transactions, such as assets, liabilities, and equity. |
| BankTransactions | Queries, inserts, and updates bank transactions within Xero. Bank transactions include deposits, withdrawals, and other activities that affect the cash accounts of the organization. |
| BankTransfers | Manages bank transfer records. It allows for querying and editing transfers between accounts, helping track money movements between different bank accounts. |
| BatchPayments | Queries and inserts batch payments in Xero. Batch payments group multiple payments together, making it easier to process large sets of payments to vendors or suppliers. |
| ContactGroups | Allows for the querying, insertion, updating, and deletion of contact groups. Contact groups enable the categorization of contacts into different segments for easier management and reporting. |
| Contacts | Used for querying, inserting, and updating contact records within a Xero organization. Contacts include customers, suppliers, and other entities that the organization interacts with for business transactions. |
| CreditNotes | Used to query, insert, and update credit notes for a Xero organization. Credit notes are used to adjust invoices, typically in cases of overpayment, returns, or errors. |
| Employees | Used for querying, inserting, and updating employee records within a Xero organization. Employees are individuals working for the organization and their data includes payroll, tax, and employment information. |
| ExpenseClaims | Used for querying, inserting, and updating expense claims. Expense claims are submitted by employees or contractors for reimbursement of business-related expenses. |
| HistoryBankTransactions | Used for querying and inserting the history and notes of bank transactions. This helps maintain historical records of financial activity within Xero. |
| HistoryBatchPayments | Used to query and insert history and notes of batch payments. This helps track historical data on bulk payments made to vendors or suppliers. |
| HistoryContacts | Queries and maintains the history and notes of contact records. It helps keep track of all actions and updates related to contacts within the Xero organization. |
| HistoryCreditNotes | Records the history and notes of credit notes issued within Xero. This is used for auditing purposes and tracking past credit note activities. |
| HistoryInvoices | Used to query and insert the history of invoices issued within a Xero organization. It records all changes made to invoices over time. |
| HistoryPurchaseOrders | Used to query and insert the history and notes of purchase orders within Xero. This helps track the lifecycle of purchase orders. |
| Invoices | Used to query, insert, and update invoices within Xero. Invoices are sent to customers for payment for goods or services provided. |
| Items | Manages items in Xero. Items can be products, services, or other billable units used in transactions. |
| LinkedTransactions | Used to manage linked transactions, allowing users to associate related transactions in Xero for better tracking and reporting. |
| ManualJournals | Used to query, insert, and update manual journals. Manual journals are used to record financial transactions that don't follow standard processes. |
| Payments | Used to query, insert, and delete payment records within Xero. Payments include transactions made to suppliers or received from customers. |
| PurchaseOrders | Used to query, insert, and update purchase orders in Xero. Purchase orders are used to track items or services that the organization intends to buy from suppliers. |
| Quotes | Allows querying and managing quotes for a Xero organization. Quotes are used to provide potential customers with a detailed offer of goods or services at specified prices before an order is placed. |
| Receipts | Enables querying, inserting, and updating receipts for a Xero organization. Receipts confirm that payments have been made, and they help track money received by the organization. |
| TaxRates | Manages tax rates in Xero. It allows you to query, insert, and update tax rates, which are necessary for calculating tax liabilities on sales and purchases. |
Allows for the querying, insertion, updating, and deletion of accounts for a Xero organization. Accounts represent the various financial categories used to track and record the organization's financial transactions, such as assets, liabilities, and equity.
The Accounts table allows you to SELECT and INSERT accounts for a Xero organization.
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.
To insert a single row, set the required fields. A new table object is created as a single entry.
The following fields are required for inserts: Code, Name, and Type.
INSERT INTO Accounts (Name, Code, Type) VALUES ('John Doe', '2000', 'BANK')
| Name | Type | ReadOnly | Description |
| AccountId [KEY] | String | True |
A unique identifier assigned by Xero to the account. |
| Code | String | False |
User-defined alphanumeric code for the account, such as 200 or SALES. |
| Name | String | False |
The name of the account as defined in the chart of accounts. |
| Type | String | False |
The account type. Valid values include BANK, CURRENT, CURRLIAB, DEPRECIATN, DIRECTCOSTS, EQUITY, EXPENSE, FIXED, LIABILITY, NONCURRENT, OTHERINCOME, OVERHEADS, PREPAYMENT, REVENUE, SALES, TERMLIAB, PAYGLIABILITY, SUPERANNUATIONEXPENSE, SUPERANNUATIONLIABILITY, and WAGESEXPENSE. |
| Description | String | False |
A text description of the account's purpose. Not returned for bank accounts. |
| TaxType | String | False |
The applicable tax type for the account (for example, INPUT or NONE). |
| EnablePaymentsToAccount | Boolean | False |
Indicates whether payments can be directly applied to this account. |
| ShowInExpenseClaims | Boolean | False |
Indicates whether this account is available for use in employee expense claims. |
| Class | String | True |
The high-level classification of the account, such as ASSET, LIABILITY, EQUITY, EXPENSE, or REVENUE. |
| Status | String | False |
The current status of the account (for example, ACTIVE or ARCHIVED). |
| SystemAccount | String | True |
Returned only if the account is a system-defined account, such as DEBTORS or CREDITORS. |
| BankAccountNumber | String | False |
The bank account number associated with this account. Applicable only to BANK account types. |
| CurrencyCode | String | False |
The ISO 4217 currency code associated with this bank account (for example, USD, NZD). BANK account types only. |
| ReportingCode | String | True |
The reporting code used for compliance reporting. Available for NZ-based organizations only. |
| ReportingCodeName | String | True |
The name of the reporting code. Available for NZ-based organizations only. |
| UpdatedDateUTC | Datetime | True |
The UTC timestamp of the last update made to the account. |
| HasAttachments | Boolean | True |
Indicates whether the account record includes any attachments (true or false). |
| BankAccountType | String | False |
The type of bank account. Valid values: BANK, CREDITCARD, PAYPAL. |
| TenantId | String | False |
The tenant ID to use for the query, useful for accessing a specific organization in multi-tenant environments. |
Queries, inserts, and updates bank transactions within Xero. Bank transactions include deposits, withdrawals, and other activities that affect the cash accounts of the organization.
The BankTransactions table allows you to SELECT, INSERT, UPDATE, and DELETE bank transactions for a Xero organization.
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 Xero API does not list a high volume threshold for the BankTransactions table. The Xero API lists the following optimized filters for this table:
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To create a new bank transaction record, the following fields are required in addition to at least one line item: Type, Contact_ContactName or Contact_ContactId, and BankAccount_AccountId or BankAccount_Code. To create a new line item, the following fields are required: LineItem_Description, LineItem_Quantity, LineItem_UnitAmount, and LineItem_AccountCode.
In addition to inserting a single row, line item tables offer two additional ways to insert into a table.
INSERT INTO BankTransactions (Type, Contact_ContactName, BankAccount_Code, LineItemAggregate) VALUES (
'RECEIVE',
'John Doe',
'200',
'<LineItem>
<Description>Monthly account fee</Description>
<UnitAmount>49.90</UnitAmount>
<TaxType>NONE</TaxType>
<TaxAmount>0.00</TaxAmount>
<LineAmount>49.90</LineAmount>
<AccountCode>404</AccountCode>
<Quantity>1.0000</Quantity>
</LineItem>'
)
Note: This method must be used for inserting multiple parent BankTransaction records in a single query.INSERT INTO BankTransactions (BankTransactionId, LineItem_Description, LineItem_Quantity, LineItem_UnitAmount, LineItem_AccountCode, LineItem_LineAmount, Total, SubTotal)
VALUES ('XXXXX-XXXXX-XXXXX-XXXXX', 'New Line Item Desc', 1, 1.00, 150, 1.00, 3.00, 3.00)Note: The 'Total' and 'Subtotal' columns are for the entire record. As such, they need to be set to the total and subtotal for all line items attached to the record, including those that already exist prior to INSERT execution.
Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
The Xero API has limited support for deleting any object. In order to delete objects, you must update their Status to an appropriate value.
Applicable values for this field may be state-dependent. For example, invoices can only have their status set to DELETED when the invoice status is currently DRAFT or SUBMITTED.
In order to delete a record from the BankTransactions table, the BankTransactionId column should be set:
DELETE FROM BankTransactions WHERE BankTransactionId='2355f1d6-91f3-4a4b-b7e2-d13b1f58c531'
Note: This is equivalent to updating the status column to 'DELETED'. Additionally, delete functionality is not available for BankTransactions of type RECEIVE-OVERPAYMENT, RECEIVE-PREPAYMENT, SPEND-OVERPAYMENT, or SPEND-PREPAYMENT.
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the row, combining the line item index with the ID of the bank transaction. This identifier is used to reference a specific bank transaction entry. |
| BankTransactionId | String | False |
The unique identifier for the bank transaction. This ID links the transaction to the corresponding record in the system. |
| Type | String | False |
The type of the transaction. Valid values include RECEIVE (money received), SPEND (money spent), RECEIVE-OVERPAYMENT, RECEIVE-PREPAYMENT, RECEIVE-TRANSFER, SPEND-OVERPAYMENT, SPEND-PREPAYMENT, and SPEND-TRANSFER, each representing different transaction types. |
| LineAmountTypes | String | False |
Indicates how the line item values are calculated relative to tax. Possible values are 'Exclusive' (tax excluded from the amount), 'Inclusive' (tax included in the amount), or 'NoTax' (no tax applied). |
| Contact_ContactName | String | False |
The name of the contact associated with the transaction. This identifies the party (for example, customer or vendor) involved in the transaction. |
| Contact_ContactId | String | False |
The unique ID of the contact associated with the transaction. This links the transaction to a specific contact in the system. |
| BankAccount_AccountId | String | False |
The unique ID of the bank account associated with the transaction. This ID links the transaction to the relevant account in the system. |
| BankAccount_AccountName | String | False |
The name of the bank account associated with the transaction. This is the user-friendly label for the bank account. |
| BankAccount_Code | String | False |
The code for the bank account, used for identifying the account in financial transactions or reports. |
| LineItem_LineItemId | String | True |
The Xero-generated ID for the line item within the bank transaction. Each line item within a transaction has a unique ID. |
| LineItem_Description | String | False |
A description for the line item in the bank transaction. This typically includes details such as the nature of the transaction, goods or services involved, or reference information. |
| LineItem_Quantity | Double | False |
The quantity of items involved in the line item. This value must be greater than or equal to zero and represents the amount or number of items in the transaction. |
| LineItem_UnitAmount | Decimal | False |
The unit amount for the line item. This is the price or cost per unit of the item, and must be a positive value. |
| LineItem_AccountCode | String | False |
The code for the account referenced by the line item. Including this field is recommended when posting to ensure the correct account is used in the transaction. |
| LineItem_Item_ItemId | String | False |
The unique ID of the item the line item refers to. This links the line item to a specific product or service in the system. |
| LineItem_Item_Name | String | False |
The name of the item the line item refers to. This is the human-readable label for the product or service associated with the transaction. |
| LineItem_Item_Code | String | False |
The code associated with the item referenced in the line item. This code can be used for identifying and categorizing items in the system. |
| LineItem_TaxType | String | False |
The tax type for the transaction line item. This overrides the default tax code for the account, allowing customization of tax rules for specific transactions. |
| LineItem_TaxAmount | Decimal | False |
The automatically calculated amount of tax applied to the line item, based on the tax rate and the line amount. |
| LineItem_LineAmount | Decimal | False |
The total amount of the line item, including any applicable taxes. If either Quantity or UnitAmount is omitted, Xero calculates the missing value from this field. |
| LineItem_TrackingCategory1_CategoryId | String | False |
The ID of the first tracking category associated with the line item. The API supports two optional tracking categories for organizing transactions. |
| LineItem_TrackingCategory1_CategoryName | String | False |
The name of the first tracking category associated with the line item. This allows users to categorize transactions for reporting purposes. |
| LineItem_TrackingCategory1_OptionId | String | False |
The ID of the first tracking category option selected for the line item. This allows for finer classification within the tracking category. |
| LineItem_TrackingCategory1_OptionName | String | False |
The name of the option selected within the first tracking category. This value provides additional classification for the line item. |
| LineItem_TrackingCategory1_Option_Stat | String | False |
The status of the option selected within the first tracking category. This field indicates whether the tracking category option is active or inactive. |
| LineItem_TrackingCategory2_CategoryId | String | False |
The ID of the second tracking category associated with the line item. The API allows two optional tracking categories to be defined for more detailed categorization. |
| LineItem_TrackingCategory2_CategoryName | String | False |
The name of the second tracking category associated with the line item. This provides additional classification options for the transaction. |
| LineItem_TrackingCategory2_OptionId | String | False |
The ID of the second tracking category option selected for the line item. This enables the classification of transactions using a second category. |
| LineItem_TrackingCategory2_OptionName | String | False |
The name of the option selected within the second tracking category. This allows the user to apply additional categorization for reporting. |
| LineItem_TrackingCategory2_Option_Stat | String | False |
The status of the option selected within the second tracking category. This field indicates whether the second tracking category option is active or inactive. |
| LineItemAggregate | String | False |
Used to define line item rows using XML values. This field should only be provided during an INSERT operation to define how the line items should be structured. |
| IsReconciled | Boolean | False |
Indicates whether the transaction has been reconciled with the bank statement. A value of 'true' means the transaction has been matched with a bank statement entry, and 'false' indicates it has not been reconciled. |
| Date | Date | False |
The date when the transaction took place. This is the date the transaction was recorded in the system, marking the event. |
| Reference | String | False |
An internal reference for the transaction within Xero. This could be a unique identifier or code used for tracking or linking transactions. |
| CurrencyRate | Decimal | False |
The exchange rate applied to the transaction when it is not in the base currency. For transactions in a foreign currency, this field records the rate used to convert the amount to the base currency. |
| URL | String | False |
A link to a source document related to the transaction, such as an invoice or receipt, providing further context or supporting documentation. |
| Status | String | False |
The status of the bank transaction. Possible values are 'AUTHORISED' (transaction approved and processed) and 'DELETED' (transaction removed or voided). |
| SubTotal | Decimal | False |
The total of the transaction before tax is applied. This is the sum of all line items, excluding taxes. |
| TotalTax | Decimal | False |
The total tax applied to the transaction. This amount reflects the sum of taxes calculated based on the transaction's tax rules. |
| Total | Decimal | False |
The total amount of the transaction, including taxes. This is the final amount after adding the taxes to the subtotal. |
| PrepaymentId | String | False |
The unique identifier generated by Xero for a prepayment. This is used when a transaction involves a prepayment, such as in 'SPEND-PREPAYMENT' or 'RECEIVE-PREPAYMENT' types. |
| OverpaymentId | String | False |
The unique identifier generated by Xero for an overpayment. This is used when a transaction involves an overpayment, such as in 'SPEND-OVERPAYMENT' or 'RECEIVE-OVERPAYMENT' types. |
| UpdatedDateUTC | Datetime | True |
The date and time when the transaction was last updated, provided in UTC format. |
| FullyPaidOnDate | Date | False |
The date on which the transaction was fully paid, marking the completion of the payment process. |
| TenantId | String | False |
The unique identifier of the tenant, allowing queries to access data specific to a particular tenant instead of using the default connection tenant. |
Manages bank transfer records. It allows for querying and editing transfers between accounts, helping track money movements between different bank accounts.
The BankTransfers table allows you to SELECT and INSERT bank transfers for a Xero organization.
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.
To insert a single row, set the required fields. A new table object is created as a single entry.
The following fields are required for inserts: FromBankAccount_Code, ToBankAccount_Code, and Amount
INSERT INTO BankTransfers (FromBankAccount_Code, ToBankAccount_Code, Amount) VALUES ('3d08fd48-434d-4c18-a57b-831663ab70d2', 'ceef65a5-a545-423b-9312-78a53caadbc4', '1000.00')
| Name | Type | ReadOnly | Description |
| BankTransferId [KEY] | String | True |
A unique identifier assigned by Xero to each bank transfer. This ID is used to reference a specific bank transfer transaction in the system. |
| FromBankAccount_Code | String | False |
The code associated with the bank account from which the money is being transferred. This code identifies the source account in financial transactions. |
| FromBankAccount_AccountId | String | False |
The unique identifier for the bank account from which the money is being sent. This ID links the transfer to the specific source account. |
| FromBankAccount_Name | String | False |
The name of the bank account from which the money is being transferred. This is a user-friendly label for the source account. |
| ToBankAccount_Code | String | False |
The code associated with the bank account to which the money is being transferred. This code identifies the destination account. |
| ToBankAccount_AccountId | String | False |
The unique identifier for the bank account to which the money is being sent. This ID links the transfer to the specific destination account. |
| ToBankAccount_Name | String | False |
The name of the bank account to which the money is being transferred. This is a user-friendly label for the destination account. |
| Amount | Decimal | False |
The amount of money being transferred. This represents the value being moved from the source bank account to the destination account. |
| Date | Date | False |
The date on which the bank transfer occurred, represented in the format YYYY-MM-DD. This is the date when the transaction was processed. |
| CurrencyRate | Decimal | True |
The exchange rate applied to the transfer if the source and destination accounts use different currencies. This rate determines the conversion between currencies. |
| FromBankTransactionID | String | True |
The unique identifier for the bank transaction associated with the source account. This ID links the bank transfer to the original transaction in the source account. |
| ToBankTransactionID | String | True |
The unique identifier for the bank transaction associated with the destination account. This ID links the bank transfer to the corresponding transaction in the destination account. |
| HasAttachments | Boolean | True |
A boolean value indicating whether the bank transfer includes any attachments, such as receipts, documents, or other supporting files. |
| TenantId | String | False |
The unique identifier for the tenant, allowing queries to access data specific to a particular tenant rather than using the default connection tenant. |
Queries and inserts batch payments in Xero. Batch payments group multiple payments together, making it easier to process large sets of payments to vendors or suppliers.
The BatchPayments table allows you to SELECT and INSERT batch payments for a Xero organization. The Id column is generated by the Cloud this value combines the index of the individual payment within the batch with the unique, Xero-generated BatchPaymentId
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 Xero API does not list a high volume threshold for the BatchPayments table. The Xero API lists the following optimized filters for this table:
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To create a new batch payment, the AccountId, Date and Reference are required in addition to at least one payment item; the Payment_InvoiceId and Payment_Amount fields are required to insert a payment item.
You can also provide multiple payments using an XML aggregate which contains the data for each payment in the batch.
Please refer to the Xero API documentation for more details on what elements are supported within each payment entry.
INSERT INTO BatchPayments (AccountId, Reference, Date, PaymentAggregate) VALUES (
'AAAAA-AAAAA-AAAAA-AAAAA',
'2019-03-01',
'<Payment>
<Invoice>
<InvoiceID>5aa9451d-95d1-4f95-a966-bbab2573f71c</InvoiceID>
<HasErrors>false</HasErrors>
<IsDiscounted>false</IsDiscounted>
</Invoice>
<PaymentID>a22a64cb-364e-43fa-9a1f-bb2cd1f4adde</PaymentID>
<Reference>ref/cheque</Reference>
<Amount>913.55</Amount>
</Payment>
<Payment>
...
</Payment>'
)
The Xero API has limited support for deleting any object. In order to delete objects, you must update their Status to an appropriate value.
Applicable values for this field may be state-dependent. For example, invoices can only have their status set to DELETED when the invoice status is currently DRAFT or SUBMITTED.
In order to delete a record from the BatchPayments table, the BatchPaymentId column should be set:
DELETE FROM BatchPayments WHERE BatchPaymentId='79f60299-7138-4d67-ae3c-50f1d4231dde'
Note: This will only set the 'Status' column to 'DELETED' for the given record. The record will still be visible in an unfiltered result.
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the batch payment, combining the batch payment index with the Xero-assigned ID for the batch payment. |
| BatchPaymentId | String | True |
The unique identifier assigned by Xero to the batch payment. This ID links the batch payment to its corresponding record in the system. |
| AccountId | String | False |
The ID of the account from which the payment is made. It must be either a bank account or an account with payments enabled, ensuring the payment can be processed. |
| AccountCurrencyCode | String | False |
The code of the currency used by the account. |
| Particulars | String | False |
(NZ only) The particulars field for New Zealand transactions, representing specific transaction details that appear on the bank statement for the payment. |
| Code | String | False |
(NZ only) The transaction code for New Zealand transactions that appears on the bank statement, providing additional information about the payment type. |
| Reference | String | False |
(NZ only) The transaction reference for New Zealand transactions that appears on the statement, typically used for identification purposes. |
| Details | String | False |
(Non-NZ only) The reference details for non-New Zealand payments that are sent to the organization's bank. This is used to provide context for the bank transaction. |
| Narrative | String | False |
(UK only) A description that appears on the Xero statement line for UK users. This field is only visible within Xero and is not included in the bank statement. |
| Date | Date | False |
The date on which the payment is made. This marks the transaction date for processing and reporting purposes. |
| Payment_PaymentId | String | True |
The unique ID assigned by Xero to the payment made within the batch. This ID links the payment to the corresponding invoice or record. |
| Payment_InvoiceId | String | False |
The unique ID of the invoice that the payment is made against. This ensures that the payment is properly allocated to the correct invoice. |
| Payment_InvoiceCurrencyCode | String | False |
The code of the currency used in the invoice that the payment is made against. |
| Payment_BankAccountNumber | String | False |
The account number of the bank where the payment is being made. This field is used to specify the destination account for the payment. |
| Payment_BankAmount | Decimal | False |
The bank amount of this particular payment line. |
| Payment_Particulars | String | False |
(NZ only) The particulars that appear on the statement for New Zealand transactions, providing a reference to the payment details. |
| Payment_Code | String | False |
(NZ only) The transaction code that will appear on the supplier's bank account for New Zealand transactions, helping to identify the transaction. |
| Payment_Reference | String | False |
(NZ only) The reference that will appear on the supplier's bank account for New Zealand transactions. This helps identify the transaction on the bank statement. |
| Payment_Details | String | False |
The reference details sent to the supplier's bank for non-NZ transactions. This serves as the bank's reference for the transaction. |
| Payment_Amount | Decimal | False |
The amount being paid in this particular payment line. This value represents the monetary value transferred to the recipient. |
| PaymentAggregate | String | False |
Used to define the payment rows with XML values. This is typically provided during an INSERT operation to specify how the payment rows should be structured. |
| Type | String | True |
Specifies the type of batch payment. 'PAYBATCH' refers to bill payments, and 'RECBATCH' refers to sales payments, distinguishing between the payment types in the batch. |
| Status | String | False |
Indicates the current status of the batch payment. Valid values are 'AUTHORISED' (payment is approved) or 'DELETED' (payment has been voided or removed). |
| TotalAmount | Decimal | True |
The total amount of all payments included in the batch. This is the sum of all individual payment amounts within the batch. |
| IsReconciled | Boolean | True |
Indicates whether the batch payment has been reconciled with the bank statement. 'True' means the payment is reconciled, while 'false' means it has not yet been reconciled. |
| UpdatedDateUTC | Datetime | True |
The date and time when the batch payment was last updated. This timestamp reflects the most recent modification made to the payment record. |
| TenantId | String | False |
The unique identifier of the tenant, allowing queries to access data for a specific tenant other than the default connection tenant. |
Allows for the querying, insertion, updating, and deletion of contact groups. Contact groups enable the categorization of contacts into different segments for easier management and reporting.
The ContactGroups table allows you to manage both contact groups as well as the members of those contact groups.
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.
When inserting with a contact group, you can either insert a new contact group or add contacts into an existing group.
To insert a new contact group, only the Name field should be given:
INSERT INTO ContactGroups (Name) VALUES ('Contractors')
To add a contact into an existing group, both the ContactGroupId and the Contact_ContactId must be provided. The
value for the Contact_ContactId field can be retrieved by querying the Contacts table.
INSERT INTO ContactGroups (ContactGroupId, Contact_ContactId) VALUES ('11111-11111-11111-11111', '22222-22222-22222-22222')
Multiple contacts may be provided using the ContactAggregate:
INSERT INTO ContactGroups (ContactGroupId, ContactAggregate) VALUES (
'11111-11111-11111-11111',
'<Contact>
<ContactID>22222-22222-22222-22222</ContactID>
</Contact>
<Contact>
<ContactID>33333-33333-33333-33333</ContactID>
</Contact>')
-- Renaming the group
UPDATE ContactGroup SET Name = 'External Contractors' WHERE ContactGroupId = '11111-11111-11111-1111'
-- Deleting the group
UPDATE ContactGroup SET Status = 'DELETED' WHERE ContactGroupId = '11111-11111-11111-1111'
DELETE FROM ContactGroups WHERE Id = '3|11111-11111-11111-11111'
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the line item, combining the index of the line item with the ID of the Contact Group. This identifier helps reference a specific entry in the Contact Group. |
| ContactGroupId | String | False |
The unique Xero identifier for the contact group. This ID links the group to its corresponding record in the system, making it distinguishable from other groups. |
| Name | String | False |
The name of the contact group. This label is used to identify and differentiate the group of contacts within the system. |
| Status | String | False |
The current status of the contact group, such as 'Active' or 'Inactive', reflecting whether the group is currently in use or archived. |
| ContactAggregate | String | False |
Used to define multiple contact rows for the group using XML values. This field is only allowed when performing an 'INSERT' operation into an existing Contact Group to add contacts. |
| Contact_ContactId | String | False |
The unique identifier of a contact group member. This ID links the contact to a specific person or entity within the contact group. |
| Contact_Name | String | True |
The name of the contact group member. This provides a human-readable label for the contact, used for identification purposes within the group. |
| TenantId | String | False |
The unique identifier for the tenant, allowing queries to access data specific to a particular tenant rather than using the default connection tenant, especially useful in multi-tenant systems. |
Used for querying, inserting, and updating contact records within a Xero organization. Contacts include customers, suppliers, and other entities that the organization interacts with for business transactions.
The Contacts table allows you to SELECT, INSERT, and UPDATE contacts for a Xero organization.
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 Xero API does not list a high volume threshold for the Contacts table. The Xero API lists the following optimized filters for this table:
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.
To insert a single row, set the required fields. A new table object is created as a single entry.
The Name field is required to add a new contact.
INSERT INTO Contacts (Name) VALUES ('John Doe')
INSERT INTO Contacts (Name) VALUES ('John Doe'), ('Johnny')
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
| Name | Type | ReadOnly | Description |
| ContactId [KEY] | String | True |
The unique identifier assigned by Xero to the contact. This ID links the contact to their corresponding record in the system, ensuring it is distinct from other contacts. |
| Name | String | False |
The name of the contact. This is used to identify the contact in the system and may be the full name of a person or the name of an organization. |
| AccountNumber | String | False |
The account number associated with the contact, used for referencing the specific account in transactions or financial records. |
| ContactNumber | String | False |
An identifier from an external system for the contact. This field can be updated via the API, although it is read-only on the Xero contact screen. |
| CompanyNumber | String | False |
The company registration number for the contact, typically used for official identification purposes. The maximum length for this field is 50 characters. |
| ContactStatus | String | False |
The current status of the contact, indicating whether they are active or archived. 'ACTIVE' means the contact is in use, while 'ARCHIVED' means the contact is no longer active. |
| FirstName | String | False |
The first name of the contact, applicable to individual contacts. The maximum length for this field is 255 characters. |
| LastName | String | False |
The last name of the contact, applicable to individual contacts. The maximum length for this field is 255 characters. |
| EmailAddress | String | False |
The email address associated with the contact. This allows for communication and invoicing. The maximum length for this field is 500 characters. |
| SkypeUserName | String | False |
The Skype username of the contact, which can be used for communication through Skype. |
| ContactPerson1_FirstName | String | False |
The first name of the primary contact person for this contact. |
| ContactPerson1_LastName | String | False |
The last name of the primary contact person for this contact. |
| ContactPerson1_EmailAddress | String | False |
The email address of the primary contact person for this contact. |
| ContactPerson1_IncludeInEmails | Boolean | False |
Indicates whether the primary contact person should be included in email communications. |
| ContactPerson2_FirstName | String | False |
The first name of the second contact person for this contact. |
| ContactPerson2_LastName | String | False |
The last name of the second contact person for this contact. |
| ContactPerson2_EmailAddress | String | False |
The email address of the second contact person for this contact. |
| ContactPerson2_IncludeInEmails | Boolean | False |
Indicates whether the second contact person should be included in email communications. |
| ContactPerson3_FirstName | String | False |
The first name of the third contact person for this contact. |
| ContactPerson3_LastName | String | False |
The last name of the third contact person for this contact. |
| ContactPerson3_EmailAddress | String | False |
The email address of the third contact person for this contact. |
| ContactPerson3_IncludeInEmails | Boolean | False |
Indicates whether the third contact person should be included in email communications. |
| ContactPerson4_FirstName | String | False |
The first name of the fourth contact person for this contact. |
| ContactPerson4_LastName | String | False |
The last name of the fourth contact person for this contact. |
| ContactPerson4_EmailAddress | String | False |
The email address of the fourth contact person for this contact. |
| ContactPerson4_IncludeInEmails | Boolean | False |
Indicates whether the fourth contact person should be included in email communications. |
| BankAccountDetails | String | False |
The bank account number associated with the contact. This is used for processing payments or transactions involving the contact. |
| TaxNumber | String | False |
The region-specific tax number of the contact, such as the ABN (Australia), GST (New Zealand), VAT (UK), or Tax ID Number (US and global). This is required for tax reporting. |
| AccountsReceivableTaxType | String | False |
The default tax type applied to accounts-receivable invoices for this contact. It specifies the tax rules for sales made to the contact. |
| AccountsPayableTaxType | String | False |
The default tax type applied to accounts-payable invoices for this contact. It specifies the tax rules for purchases made from the contact. |
| Street_AddressLine1 | String | False |
The first line of the contact's street address. This is the main address for the contact, often including the street name and building number. |
| Street_AddressLine2 | String | False |
The second line of the contact's street address. This is used for additional address details like apartment or suite numbers. |
| Street_AddressLine3 | String | False |
The third line of the contact's street address, used if further address details are needed. |
| Street_AddressLine4 | String | False |
The fourth line of the contact's street address, used for further address information if applicable. |
| Street_City | String | False |
The city of the contact's street address. This helps to geographically locate the contact. |
| Street_Region | String | False |
The region or state of the contact's street address. |
| Street_PostalCode | String | False |
The postal code of the contact's street address. This code is used for mail sorting and location identification. |
| Street_Country | String | False |
The country of the contact's street address. |
| Street_AttentionTo | String | False |
The attention-to line of the contact's street address, used to specify the recipient for mail or packages. |
| POBox_AddressLine1 | String | False |
The first line of the contact's PO Box address. |
| POBox_AddressLine2 | String | False |
The second line of the contact's PO Box address. |
| POBox_AddressLine3 | String | False |
The third line of the contact's PO Box address. |
| POBox_AddressLine4 | String | False |
The fourth line of the contact's PO Box address. |
| POBox_City | String | False |
The city of the contact's PO Box address. |
| POBox_Region | String | False |
The region or state of the contact's PO Box address. |
| POBox_PostalCode | String | False |
The postal code of the contact's PO Box address. |
| POBox_Country | String | False |
The country of the contact's PO Box address. |
| POBox_AttentionTo | String | False |
The attention-to line for the contact's PO Box address, indicating the recipient for mail or packages. |
| DDI_PhoneNumber | String | False |
The phone number for the contact, excluding the area or country code. |
| DDI_PhoneAreaCode | String | False |
The area code for the contact's phone number, indicating the geographical region of the phone. |
| DDI_PhoneCountryCode | String | False |
The country code for the contact's phone number, used for international dialing. |
| Default_PhoneNumber | String | False |
The default phone number for the contact, excluding the area or country code. |
| Default_PhoneAreaCode | String | False |
The area code for the contact's default phone number. |
| Default_PhoneCountryCode | String | False |
The country code for the contact's default phone number. |
| Fax_PhoneNumber | String | False |
The fax number for the contact, excluding the area or country code. |
| Fax_PhoneAreaCode | String | False |
The area code for the contact's fax number. |
| Fax_PhoneCountryCode | String | False |
The country code for the contact's fax number. |
| Mobile_PhoneNumber | String | False |
The mobile phone number for the contact, excluding the area or country code. |
| Mobile_PhoneAreaCode | String | False |
The area code for the contact's mobile phone number. |
| Mobile_PhoneCountryCode | String | False |
The country code for the contact's mobile phone number. |
| UpdatedDateUTC | Datetime | True |
The timestamp indicating when the contact information was last updated in the system. |
| ContactGroupId | String | True |
The unique identifier of the contact group that the contact is part of. This field indicates which group the contact belongs to. |
| MergedToContactID | String | True |
The ID of the contact that this contact has been merged into. This field shows the destination contact after the merge process. |
| IsSupplier | Boolean | True |
Indicates whether the contact is marked as a supplier. If the value is 'true', the contact has accounts-payable (AP) invoices, meaning they are a vendor in the system. |
| IsCustomer | Boolean | True |
Indicates whether the contact is marked as a customer. If the value is 'true', the contact has accounts-receivable (AR) invoices, meaning they are a customer in the system. |
| DefaultCurrency | String | False |
The default currency used for transactions with the contact. This currency is applied to invoices and payments unless otherwise specified. |
| Website | String | True |
The website URL associated with the contact. This could be the contact's business or personal website. |
| BrandingThemeId | String | True |
The unique identifier for the branding theme applied to the contact's invoices or documents. |
| BrandingThemeName | String | True |
The name of the branding theme applied to the contact's invoices or documents. |
| PurchasesDefaultAccountCode | String | False |
The default account code used for purchases from this contact. This helps categorize expenses related to purchases from the contact. |
| PurchasesDefaultLineAmountType | String | True |
The default line amount type for purchases from this contact. Valid values are 'INCLUSIVE', 'EXCLUSIVE', or 'NONE', indicating how tax is applied to purchases. |
| SalesDefaultAccountCode | String | False |
The default account code used for sales to this contact. This helps categorize revenue from sales to the contact. |
| SalesDefaultLineAmountType | String | True |
The default line amount type for sales to this contact. Valid values are 'INCLUSIVE', 'EXCLUSIVE', or 'NONE', indicating how tax is applied to sales. |
| BatchPayments_BankAccountNumber | String | True |
The bank account number for batch payments associated with this contact. |
| BatchPayments_BankAccountName | String | True |
The bank account name for batch payments associated with this contact. |
| BatchPayments_Details | String | True |
The details associated with batch payments for this contact. |
| Discount | Decimal | True |
The default discount rate applied to transactions with this contact. This rate reduces the total amount due on invoices. |
| Balances_AccountsReceivable_Outstanding | Decimal | True |
The outstanding balance for accounts-receivable (AR) invoices for this contact, indicating the amount owed by the contact. |
| Balances_AccountsReceivable_Overdue | Decimal | True |
The overdue balance for accounts-receivable (AR) invoices for this contact, representing the amount that is past due. |
| Balances_AccountsPayable_Outstanding | Decimal | True |
The outstanding balance for accounts-payable (AP) invoices for this contact, indicating the amount owed to the contact. |
| Balances_AccountsPayable_Overdue | Decimal | True |
The overdue balance for accounts-payable (AP) invoices for this contact, representing the amount that is past due. |
| PaymentTerms_Bills_Day | Int | True |
The default payment terms for bills associated with this contact. This value specifies the number of days within which the bill should be paid. |
| PaymentTerms_Bills_Type | String | True |
The default payment terms type for bills associated with this contact, such as 'Net 30' or 'Due on Receipt'. |
| PaymentTerms_Sales_Day | Int | True |
The default payment terms for sales associated with this contact. This value specifies the number of days within which the sales invoice should be paid. |
| PaymentTerms_Sales_Type | String | True |
The default payment terms type for sales associated with this contact, such as 'Net 30' or 'Due on Receipt'. |
| SalesTrackingCategory1_Name | String | False |
The default sales tracking category name for this contact, used for categorizing sales transactions. |
| SalesTrackingOption1_Name | String | False |
The default sales tracking option name for this contact, providing more specific categorization for sales transactions. |
| SalesTrackingCategory2_Name | String | False |
The default sales tracking category name for this contact, providing a second level of categorization for sales transactions. |
| SalesTrackingOption2_Name | String | False |
The default sales tracking option name for this contact, providing a second level of categorization for sales transactions. |
| PurchaseTrackingCategory1_Name | String | False |
The default purchase tracking category name for this contact, used for categorizing purchase transactions. |
| PurchaseTrackingOption1_Name | String | False |
The default purchase tracking option name for this contact, providing more specific categorization for purchase transactions. |
| PurchaseTrackingCategory2_Name | String | False |
The default purchase tracking category name for this contact, providing a second level of categorization for purchase transactions. |
| PurchaseTrackingOption2_Name | String | False |
The default purchase tracking option name for this contact, providing a second level of categorization for purchase transactions. |
| HasAttachments | Boolean | True |
Indicates whether the contact has any attachments, such as documents or receipts, associated with their record. |
| TenantId | String | False |
The unique identifier for the tenant, allowing queries to access data specific to a particular tenant rather than using the default connection tenant. |
Used to query, insert, and update credit notes for a Xero organization. Credit notes are used to adjust invoices, typically in cases of overpayment, returns, or errors.
The CreditNotes table allows you to SELECT, INSERT, UPDATE, and DELETE credit note line items for a Xero organization. The Id column is generated by the Cloud; the value of this field combines the index of the line item with the unique, Xero-generated CreditNoteId.
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 Xero API does not list a high volume threshold for the CreditNotes table. The Xero API lists the following optimized filters for this table:
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new credit note, the Contact_Name field is required. For a credit note to be approved, the following fields must be defined in addition to at least one line item: Contact_Name, Date, and LineAmountTypes.
In addition to inserting a single row, line item tables offer two additional ways to insert into a table.
INSERT INTO CreditNotes (Type, Contact_Name, LineItemAggregate) VALUES (
'ACCPAYCREDIT',
'John Doe',
'<LineItem>
<Description>LineItemDesc1</Description>
<Quantity>1</Quantity>
</LineItem>
<LineItem>
<Description>LineItemDesc2</Description>
<Quantity>2</Quantity>
</LineItem>'
)INSERT INTO CreditNotes (CreditNoteId, LineItem_Description, LineItem_Quantity) VALUES ('XXXXX-XXXXX-XXXXX-XXXXX', 'New Line Item Desc', 1)Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
The Xero API has limited support for deleting any object. In order to delete objects, you must update their Status to an appropriate value.
Applicable values for this field may be state-dependent. For example, invoices can only have their status set to DELETED when the invoice status is currently DRAFT or SUBMITTED.
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the credit note allocation line item. This combines the allocation index with the ID of the credit note, ensuring each allocation is uniquely identifiable within the system. |
| CreditNoteId | String | False |
The unique identifier of the credit note. This links the allocation to the specific credit note, making it possible to track which credit note is being applied to an invoice. |
| CreditNoteNumber | String | False |
A user-friendly reference number for the credit note. This helps users identify and differentiate credit notes, typically displayed on invoices or statements. |
| Reference | String | False |
An optional field for storing additional reference information related to the credit note. This could include external identifiers or internal references for tracking purposes. |
| Type | String | False |
The type of the credit note. Valid values are 'ACCPAYCREDIT' (credit note for accounts payable) and 'ACCRECCREDIT' (credit note for accounts receivable), indicating the nature of the transaction. |
| Contact_ContactId | String | False |
The unique identifier of the contact associated with this credit note. This links the credit note to a specific customer or vendor in the system. |
| Contact_Name | String | False |
The name of the contact associated with this credit note. This is typically the customer or supplier linked to the credit note. |
| Date | Date | False |
The date when the credit note was created. This marks the date the credit note was issued and typically appears on the credit note document. |
| Status | String | False |
The status of the credit note, which could indicate whether it is 'DRAFT', 'SUBMITTED', 'APPROVED', or 'DELETED', reflecting the current state of the credit note in the system. |
| LineAmountTypes | String | False |
The line amount type, determining how the line amounts are calculated relative to tax. Possible values are 'Exclusive' (tax excluded), 'Inclusive' (tax included), and 'NoTax' (no tax applied). This field must be defined for credit notes to be approved. |
| LineItem_LineItemId | String | False |
The unique identifier for a line item in the credit note. This Xero-generated ID is used to reference specific line items within the credit note. If line item IDs are not provided in updates, line items are deleted and recreated. |
| LineItem_Description | String | False |
The description for the line item in the credit note. This is typically a short text that describes the goods or services being credited. The description must be at least one character long for the credit note to be approved. |
| LineItem_Quantity | Double | False |
The quantity of the items involved in the line item. This must be a non-negative value and represents how many units of the product or service are being credited. |
| LineItem_UnitAmount | Decimal | False |
The unit price of the items involved in the line item. This must be a positive value, representing the price per unit of the credited items or services. |
| LineItem_ItemCode | String | False |
The user-defined item code for the product or service being credited. This code helps identify the item, usually for inventory or sales tracking. |
| LineItem_AccountCode | String | False |
The account code associated with the line item. This account code must be active for the organization and is used to categorize the financial impact of the credit note line item. |
| LineItem_Item_ItemId | String | False |
The unique identifier for the item being credited. This ID links the line item to a specific product or service in the system. |
| LineItem_Item_Name | String | False |
The name of the item being credited. This is typically the product or service description, providing clarity on what the credit is applied to. |
| LineItem_Item_Code | String | False |
The code of the item being credited. This code helps identify and classify the credited product or service within the system. |
| LineItem_TaxType | String | False |
The tax type for the line item. This overrides the default tax code for the account, allowing customization of tax rules specific to this credit note line. |
| LineItem_TaxAmount | Decimal | False |
The calculated tax amount for the line item, based on the 'UnitAmount' and 'Quantity' with the applied tax rate. This reflects the tax charged for the credited item. |
| LineItem_LineAmount | Decimal | False |
The total value of the line item, calculated as 'Quantity x UnitAmount', with discounts and taxes applied. This amount represents the monetary value of the credited item. |
| LineItem_TrackingCategory1_CategoryId | String | False |
The ID of the first tracking category associated with the line item. Xero allows up to two tracking categories for each transaction, helping to categorize the transaction for reporting. |
| LineItem_TrackingCategory1_CategoryName | String | False |
The name of the first tracking category. This provides a label for the category used in the line item, offering further classification of the credit note. |
| LineItem_TrackingCategory1_OptionId | String | False |
The ID of the option selected within the first tracking category. This ID links the line item to a specific option within the tracking category. |
| LineItem_TrackingCategory1_OptionName | String | False |
The name of the option selected within the first tracking category. This provides a label for the selected option used to further categorize the line item. |
| LineItem_TrackingCategory1_Option_Stat | String | False |
The status of the option selected within the first tracking category. This indicates whether the selected option is active or inactive. |
| LineItem_TrackingCategory2_CategoryId | String | False |
The ID of the second tracking category associated with the line item. This allows additional categorization of the line item for more detailed financial reporting. |
| LineItem_TrackingCategory2_CategoryName | String | False |
The name of the second tracking category. This provides a label for the second category used to classify the line item. |
| LineItem_TrackingCategory2_OptionId | String | False |
The ID of the option selected within the second tracking category. This links the line item to a specific option within the second tracking category. |
| LineItem_TrackingCategory2_OptionName | String | False |
The name of the option selected within the second tracking category. This provides a label for the selected option used to further categorize the line item. |
| LineItem_TrackingCategory2_Option_Stat | String | False |
The status of the option selected within the second tracking category. This indicates whether the selected option is active or inactive. |
| LineItem_DiscountRate | Double | False |
The discount percentage applied to the line item. This field is only supported on 'ACCREC' type credit notes and is used to reduce the total amount of the credit for this line item. |
| LineItemAggregate | String | False |
Defines how multiple line items should be structured when inserted into the system using XML values. This field is only used during the 'INSERT' operation to create new line items. |
| SubTotal | Decimal | False |
The total amount of the credit note excluding taxes. This value is calculated by summing all line item amounts before tax is applied. |
| TotalTax | Decimal | False |
The total tax applied to the credit note. This is calculated by summing the tax amounts of all line items based on their respective tax rates. |
| Total | Decimal | False |
The total amount of the credit note, including taxes. This is the sum of the 'SubTotal' and 'TotalTax', representing the full amount of the credit. |
| UpdatedDateUTC | Datetime | True |
The date and time when the credit note was last updated, stored in UTC format. This timestamp reflects any changes made to the credit note after its creation. |
| CurrencyCode | String | False |
The currency used for the credit note. This defines the currency for all amounts within the credit note, ensuring proper handling of different currencies. |
| FullyPaidOnDate | Date | False |
The date when the credit note was fully paid, marking the completion of the payment process and closing out the credit note. |
| SentToContact | Boolean | False |
Indicates whether the credit note has been sent to the contact (customer or supplier) via the Xero application. 'True' means it has been sent. |
| BrandingThemeId | String | False |
The unique identifier for the branding theme applied to this credit note. This allows the contact to customize the look of their credit note using a specific branding template. |
| CurrencyRate | Decimal | False |
The exchange rate used to convert the credit note's amounts to the base currency. This is applied only when the credit note involves a non-base currency. |
| RemainingCredit | Decimal | False |
The remaining balance of the credit note that has not yet been applied to invoices or payments. This field helps track the unallocated portion of the credit note. |
| Allocation1_AppliedAmount | Decimal | True |
The amount applied from this credit note to the first invoice. This value reduces the outstanding balance on the specified invoice. |
| Allocation1_Date | Date | True |
The date when the first allocation from the credit note was made to the invoice. |
| Allocation1_InvoiceId | String | True |
The unique identifier for the invoice that the first allocation has been applied to. |
| Allocation1_InvoiceNumber | String | True |
The reference number of the invoice that the first allocation has been applied to. |
| Allocation2_AppliedAmount | Decimal | True |
The amount applied from this credit note to the second invoice, reducing the outstanding balance of that invoice. |
| Allocation2_Date | Date | True |
The date when the second allocation from the credit note was made to the invoice. |
| Allocation2_InvoiceId | String | True |
The unique identifier for the invoice that the second allocation has been applied to. |
| Allocation2_InvoiceNumber | String | True |
The reference number of the invoice that the second allocation has been applied to. |
| PaymentIds | String | True |
A comma-separated list of payment IDs associated with this credit note, indicating which payments have been linked to this credit note. |
| HasAttachments | Boolean | True |
Indicates whether the credit note has any attached files, such as receipts or documents, supporting the transaction. |
| TenantId | String | False |
The unique identifier for the tenant, allowing queries to access data specific to a particular tenant rather than using the default connection tenant. |
Used for querying, inserting, and updating employee records within a Xero organization. Employees are individuals working for the organization and their data includes payroll, tax, and employment information.
The Employees table allows you to SELECT, INSERT, and UPDATE employees for a Xero organization.
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.
To insert a single row, set the required fields. A new table object is created as a single entry.
To insert a new employee record, the following fields are required: FirstName and LastName.
INSERT INTO Employees (FirstName, LastName) VALUES ('John', 'Doe')
Employees can also be added in bulk by specifying multiple records in the VALUES clause.
INSERT INTO Employees (FirstName, LastName)
VALUES
('John', 'Doe'),
('Jane', 'Doe')
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
| Name | Type | ReadOnly | Description |
| EmployeeId [KEY] | String | True |
The unique identifier assigned by Xero to the employee. This ID ensures that each employee can be uniquely identified within the system and is used for referencing the employee's records. |
| Status | String | False |
The current status of the employee. Valid values are 'ACTIVE' (indicating that the employee is currently active and their record is in use) and 'DELETED' (indicating that the employee's record has been deleted or archived and is no longer in use). |
| FirstName | String | False |
The first name of the employee. This field contains the given name of the employee and is used for personal identification and communication purposes. |
| LastName | String | False |
The last name of the employee. This field contains the surname of the employee, used in conjunction with the first name for identification purposes. |
| ExternalLink_URL | String | False |
A URL that points to an external resource related to the employee. This could link to external profiles, documents, or relevant websites. |
| ExternalLink_Description | String | False |
A description of the external link provided in 'ExternalLink_URL'. This field provides context or additional details about the link to help users understand its relevance. |
| UpdatedDateUTC | Datetime | True |
The timestamp (in UTC) indicating when the employee record was last updated. This field tracks changes to the employee's details and serves as a reference for data modifications. |
| TenantId | String | False |
The unique identifier for the tenant, allowing queries to access data specific to a particular tenant, especially useful in multi-tenant environments where data for different tenants is isolated. |
Used for querying, inserting, and updating expense claims. Expense claims are submitted by employees or contractors for reimbursement of business-related expenses.
The ExpenseClaims table allows you to SELECT, INSERT, and UPDATE expense claims for a Xero organization.
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.
To create a new expense claim record, the UserId field must be defined; in addition, at least one ReceiptId must be specified. One can be provided either via the ReceiptId column:
INSERT INTO ExpenseClaims (UserId, ReceiptId) VALUES (
'XXXXX-XXXXX-XXXXX-XXXXX', 'YYYYY-YYYYY-YYYYY-YYYYY'
)
Multiple may also be specified by including them in the ReceiptAggregate:
INSERT INTO ExpenseClaims (UserId, ReceiptAggregate) VALUES (
'XXXXX-XXXXX-XXXXX-XXXXX',
'<Receipt>
<ReceiptID>YYYYY-YYYYY-YYYYY-YYYYY</ReceiptID>
</Receipt>
<Receipt>
<ReceiptID>ZZZZZ-ZZZZZ-ZZZZZ-ZZZZZ</ReceiptID>
</Receipt>'
)
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
| Name | Type | ReadOnly | Description |
| ExpenseClaimId [KEY] | String | True |
The unique identifier assigned to the expense claim. This ID is used to link all receipts and related payments to a specific claim, ensuring the claim can be tracked and processed properly. |
| UserId | String | False |
The unique identifier of the user associated with the expense claim. This field links the claim to the employee or individual who submitted it, allowing for proper tracking of user-related expenses. |
| ReceiptAggregate | String | False |
Used to define multiple Receipt rows using XML values. This field is only applicable during an 'INSERT' operation to create new receipt records for the expense claim. It helps bundle multiple receipts under one claim. |
| ReceiptId | String | False |
The unique identifier for the receipt associated with the expense claim. This ID helps link individual receipts to the overall expense claim, ensuring that each receipt can be tracked independently. |
| Status | String | True |
The status of the expense claim. Valid values are 'SUBMITTED' (the claim is submitted but not yet processed), 'AUTHORISED' (the claim has been approved for payment), and 'PAID' (the claim has been paid). |
| UpdatedDateUTC | Datetime | True |
The timestamp, in UTC, indicating when the expense claim was last updated. This date helps track the most recent changes made to the claim, whether it's a status update or a modification to the claim's details. |
| Total | Decimal | True |
The total amount of the expense claim, representing the sum of all receipts submitted under the claim. This value is used to calculate the overall cost of the claim. |
| AmountDue | Decimal | True |
The amount that is due to be paid for the expense claim. This is typically the total amount minus any previous payments already made or allocated to the claim. |
| AmountPaid | Decimal | True |
The amount of the expense claim that has already been paid. This value is subtracted from the 'AmountDue' to determine what is still outstanding. |
| PaymentDueDate | Date | True |
The date by which the expense claim must be paid. This is typically based on the organization's payment terms or the date the claim is approved. |
| ReportingDate | Date | True |
The date on which the expense claim will be reported in Xero, typically used for financial reporting or accounting purposes to determine which period the claim falls into. |
| TenantId | String | False |
The unique identifier of the tenant. This is used to access data specific to a particular tenant, ensuring that queries or operations are performed within the correct organizational context in a multi-tenant environment. |
Used for querying and inserting the history and notes of bank transactions. This helps maintain historical records of financial activity within Xero.
The HistoryBankTransactions table allows you to read the notes created on a transaction, and the history of changes to that transaction. If a BankTransactionId is not provided, the history of all BankTransactions will be retrieved.
A BankTransactionId and Details is required for inserting a note:
INSERT INTO HistoryBankTransactions (BankTransactionId, Details) VALUES ('...', 'Refund for overpayment'),
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures each entry is distinctly identifiable in the log. |
| BankTransactionId | String | False |
The unique identifier of the bank transaction to which this history item is related. This field links the history entry to a specific bank transaction record, allowing users to track changes made to that transaction. |
| Changes | String | True |
Describes the type of change that occurred on the bank transaction. This could include updates such as changes to the transaction amount, category, date, or status, providing context for the nature of the modification. |
| Date | Datetime | True |
The timestamp of when the change occurred. This field records the exact time the change was made, providing a chronological record of modifications to the bank transaction. |
| User | String | True |
The name of the user who made the change. This field identifies the individual responsible for modifying the bank transaction, allowing for tracking and accountability in the system. |
| Details | String | False |
A detailed description of the change that was made. This provides specific information about what exactly was altered in the transaction, offering transparency into the modifications made. |
| TenantId | String | False |
The unique identifier of the tenant. This allows the query to access data specific to a particular tenant in multi-tenant environments, ensuring that the history item belongs to the correct organization. |
Used to query and insert history and notes of batch payments. This helps track historical data on bulk payments made to vendors or suppliers.
The HistoryBatchPayments table allows you to read the notes created on a batch payment, and the history of changes to that batch payment. If a BatchPaymentId is not provided, the history of all batch payments will be retrieved.
An BatchPaymentId and Details is required for inserting a note:
INSERT INTO HistoryBatchPayments (BatchPaymentId, Details) VALUES ('...', 'Batch submitted on 3/1/2019')
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures each entry is distinctly identifiable and provides chronological tracking of changes. |
| BatchPaymentId | String | False |
The unique identifier of the item (such as a batch payment) that this history item belongs to. This links the history entry to a specific payment batch, enabling users to track changes made to that batch. |
| Changes | String | True |
Describes the type of change that happened on the item. This could include modifications to the batch payment details, such as changes to the amount, payment status, or accounts involved. |
| Date | Datetime | True |
The timestamp of when the change occurred. This field provides a clear record of when a particular modification was made, allowing for precise tracking of the changes in the system. |
| User | String | True |
The name of the user who made the change. This field identifies the individual who performed the modification, helping to ensure accountability and transparency in the system. |
| Details | String | False |
A detailed description of the specific change that was made. This could include information on which fields were modified and how, providing users with context and clarity on the adjustments made to the item. |
| TenantId | String | False |
The unique identifier of the tenant. This field allows the query to access data specific to a particular tenant in multi-tenant environments, ensuring that changes are isolated to the correct tenant's data. |
Queries and maintains the history and notes of contact records. It helps keep track of all actions and updates related to contacts within the Xero organization.
The HistoryContacts table allows you to read the notes created on a contact, and the history of changes to that contact. If a ContactId is not provided, the history of all Contacts will be retrieved.
A ContactId and Details is required for inserting a note:
INSERT INTO HistoryContacts (ContactId, Details) VALUES ('...', 'Reliable customer'),
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures each entry is distinctly identifiable, allowing for accurate tracking of changes over time. |
| ContactId | String | False |
The unique identifier of the contact that this history item belongs to. This links the history entry to a specific contact, allowing users to trace changes made to that particular contact record. |
| Changes | String | True |
Describes the type of change that happened on the contact. This could include modifications such as updates to the contact's details (for example, address, email), status (for example, active or archived), or other related information. |
| Date | Datetime | True |
The timestamp of when the change occurred. This field records the exact time the modification was made, providing a chronological record of changes to the contact's information. |
| User | String | True |
The name of the user who made the change. This field identifies the individual responsible for modifying the contact, ensuring accountability and transparency for actions performed in the system. |
| Details | String | False |
A detailed description of the specific change that was made. This provides clarity on what exactly was altered in the contact record, offering transparency and context to the change. |
| TenantId | String | False |
The unique identifier of the tenant. This ensures that the query accesses data specific to a particular tenant, especially in multi-tenant environments where data for different tenants is isolated and needs to be queried separately. |
Records the history and notes of credit notes issued within Xero. This is used for auditing purposes and tracking past credit note activities.
The HistoryCreditNotes table allows you to read the notes created on a
credit note, and the history of changes to that credit note. If a
CreditNoteId is not provided, the history of all CreditNotes will be
retrieved.
SELECT * FROM HistoryCreditNotes WHERE CreditNoteId = '...'
A CreditNoteId and Details is required for inserting a note:
INSERT INTO HistoryCreditNotes (CreditNoteId, Details) VALUES ('...', 'Offered 12% discount'),
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures each history entry is distinctly identifiable, enabling accurate tracking of changes to the credit note. |
| CreditNoteId | String | False |
The unique identifier of the credit note to which this history item belongs. This field links the history entry to a specific credit note, making it easy to track changes to that credit note over time. |
| Changes | String | True |
Describes the type of change that happened to the credit note. This could include modifications such as updates to the credit note's amount, status, or details of the items being credited. |
| Date | Datetime | True |
The exact timestamp of when the change occurred. This field records the time at which the modification was made, providing a chronological history of changes for auditing and tracking purposes. |
| User | String | True |
The name of the user who made the change. This field identifies the person responsible for altering the credit note, ensuring accountability for updates made within the system. |
| Details | String | False |
A detailed description of the specific change that was made to the credit note. This provides clarity on what exactly was altered, such as the updated amount, status, or other details that were modified. |
| TenantId | String | False |
The unique identifier of the tenant. This ensures that the query retrieves data specific to a particular tenant, especially in multi-tenant environments where each tenant's data is kept separate and secure. |
Used to query and insert the history of invoices issued within a Xero organization. It records all changes made to invoices over time.
The HistoryInvoices table allows you to read the notes created on a invoice, and the history of changes to that invoice. If a InvoiceId is not provided, the history of all Invoices will be retrieved.
An InvoiceId and Details is required for inserting a note:
INSERT INTO HistoryInvoices (InvoiceId, Details) VALUES ('...', 'Payment expected on December 1st'),
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures that each history entry is distinctly identifiable and enables accurate tracking of changes over time. |
| InvoiceId | String | False |
The unique identifier of the invoice to which this history item belongs. This field links the history entry to a specific invoice, providing context for the changes made to that invoice. |
| Changes | String | True |
Describes the type of change that occurred on the invoice. This could include modifications such as updates to the invoice amount, status, payment details, or the items listed on the invoice. |
| Date | Datetime | True |
The timestamp indicating when the change occurred. This field captures the exact time the modification was made, allowing for a chronological history of changes to the invoice. |
| User | String | True |
The name of the user who made the change. This field identifies the individual responsible for altering the invoice, ensuring accountability and transparency for the updates. |
| Details | String | False |
A detailed description of the specific change made to the invoice. This provides additional context on what was altered, such as the updated amount, new items, or payment terms. |
| TenantId | String | False |
The unique identifier for the tenant. This ensures that the query retrieves data specific to a particular tenant in multi-tenant environments, ensuring proper data isolation for different organizations. |
Used to query and insert the history and notes of purchase orders within Xero. This helps track the lifecycle of purchase orders.
The HistoryPurchaseOrders table allows you to read the notes created on a purchase order, and the history of changes to that purchase order. If a PurchaseOrderId is not provided, the history of all PurchaseOrders will be retrieved.
A PurchaseOrderId and Details is required for inserting a note:
INSERT INTO HistoryPurchaseOrders (PurchaseOrderId, Details) VALUES ('...', 'Rescheduled delivery for October 9th'),
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures each history entry is distinctly identifiable, enabling precise tracking of changes to the purchase order. |
| PurchaseOrderId | String | False |
The unique identifier of the purchase order that this history item belongs to. This field links the history entry to a specific purchase order, ensuring the changes made to that order are tracked. |
| Changes | String | True |
Describes the type of change that occurred on the purchase order. This could include updates to the order's amount, status, items, or delivery details, providing insight into the nature of the modification. |
| Date | Datetime | True |
The timestamp of when the change occurred. This field records the exact time the modification was made, ensuring a clear and accurate record of changes over time. |
| User | String | True |
The name of the user who made the change. This identifies the individual responsible for the modification, ensuring accountability and transparency for updates to the purchase order. |
| Details | String | False |
A detailed description of the specific change made to the purchase order. This includes information on what was altered, such as item adjustments, quantity changes, or status updates. |
| TenantId | String | False |
The unique identifier of the tenant. This ensures the query retrieves data specific to a particular tenant in multi-tenant environments, isolating the changes to the correct organization's data. |
Used to query, insert, and update invoices within Xero. Invoices are sent to customers for payment for goods or services provided.
The Invoices table allows you to SELECT, INSERT, UPDATE, and DELETE invoice line items for a Xero organization. The Id column is generated by the Cloud this value combines the index of the line item with the unique, Xero-generated InvoiceId.
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 Invoices table has a high volume threshold of 500,000. The Xero API lists the following optimized filters for this table:
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To create a new invoice, the Type and ContactName fields must be set in addition to at least one line item. Note that also at least the LineItem_LineAmount or LineItem_UnitAmount are also required fields for the LineItem aggregate.
In addition to inserting a single row, line item tables offer two additional ways to insert into a table.
INSERT INTO Invoices (Type, ContactName, LineItemAggregate) VALUES (
'ACCPAY',
'Boom FM',
'<LineItem>
<ItemCode>12</ItemCode>
<Description>Onsite project management </Description>
<Quantity>1.0000</Quantity>
<UnitAmount>1800.00</UnitAmount>
<TaxType>OUTPUT</TaxType>
<TaxAmount>225.00</TaxAmount>
<LineAmount>1800.00</LineAmount>
<AccountCode>200</AccountCode>
<AccountId>4f2a3169-8454-4012-a642-05a88ef32982</AccountId>
<Tracking>
<TrackingCategory>
<Name>Activity/Workstream</Name>
<Option>Onsite consultancy</Option>
</TrackingCategory>
</Tracking>
<LineItemID>52208ff9-528a-4985-a9ad-b2b1d4210e38</LineItemID>
</LineItem>
<LineItem>
...
</LineItem>'
)
Note: This method must be used for inserting multiple new Invoices in a single query.INSERT INTO Invoices (InvoiceId, LineItem_Description, LineItem_Quantity, LineItem_UnitAmount) VALUES ('XXXXX-XXXXX-XXXXX-XXXXX', 'New Line Item Desc', 1, 10)Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
The Xero API has limited support for deleting any object. In order to delete objects, you must update their Status to an appropriate value.
Applicable values for this field may be state-dependent. For example, invoices can only have their status set to DELETED when the invoice status is currently DRAFT or SUBMITTED.
This means that, out the three fields LIneItem_DiscountAmount, LineItem_DiscountAmount and LineItem_DiscountRate, only one can be used as part of an INSERT or UDPATE query. For example, neither of the below queries are valid:
INSERT INTO Invoices (Invoice, LineItem_LineAmount, LineItem_DiscountRate) VALUES ('2bf5f07b-edf0-4b05-9200-cc2cd6b89b1e', 4999.99, 6.75)
UPDATE Invoices SET LineItem_DiscountRate = 12.50, LineItem_DiscountAmount = 99.99 WHERE Id = '1|2bf5f07b-edf0-4b05-9200-cc2cd6b89b1e'
It also means that the Cloud will remove the two other values when assigning any one of these fields. For example, if you were to assign a LineItem_LineAmount to an Invoice, the Cloud would remove any discount values attached to that Invoice.
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the line item, combining its position in the history log with the Xero-generated identifier for the invoice. This ensures that each line item is distinctly identifiable for tracking changes made to it. |
| InvoiceId | String | False |
The unique identifier of the invoice to which this line item belongs. This field links the line item to a specific invoice, ensuring that changes to the invoice can be traced and tracked. |
| Type | String | False |
The type of invoice. Valid values are 'ACCPAY' (Accounts Payable) and 'ACCREC' (Accounts Receivable), indicating whether the invoice pertains to an expense (ACCPAY) or income (ACCREC). |
| ContactId | String | False |
The unique identifier of the contact associated with the invoice. This field links the invoice to a specific customer or supplier. |
| ContactName | String | False |
The name of the contact associated with the invoice. This value is required when creating an invoice, as it identifies the individual or business to whom the invoice is issued. |
| LineItem_LineItemId | String | False |
The unique Xero-generated identifier for the line item. If 'LineItemIDs' are not included in an update request, the existing line items are deleted and recreated. |
| LineItem_Description | String | False |
A description for the line item. This field must contain at least one character and is required for creating an approved invoice, providing context for the goods or services being billed. |
| LineItem_Quantity | Double | False |
The quantity of the item listed in the line item. This field is required for invoice approval and must be zero or positive. |
| LineItem_UnitAmount | Decimal | False |
The unit amount for the item in the line item. This field is required for invoice approval and reflects the price per unit of the item or service. |
| LineItem_ItemCode | String | False |
The unique code that identifies the item. This is typically used for categorizing products or services in the system. |
| LineItem_AccountCode | String | False |
The account code associated with the line item. This must be an active account in the organization's chart of accounts, and it is required for invoice approval. |
| LineItem_Item_ItemId | String | False |
The unique ID of the item the line item refers to. This ID helps link the line item to the actual product or service in the system. |
| LineItem_Item_Name | String | False |
The name of the item the line item refers to. This provides a human-readable reference for the item being billed. |
| LineItem_Item_Code | String | False |
The code of the item the line item refers to. This field helps identify the product or service linked to the invoice line. |
| LineItem_TaxType | String | False |
The tax type applied to the line item. This field can override the default tax code for the selected account, allowing for different tax treatments. |
| LineItem_TaxAmount | Decimal | False |
The calculated tax for the line item, based on the tax rate. This value is automatically generated based on the tax type and line amount. |
| LineItem_LineAmount | Decimal | False |
The total amount for the line item, calculated by multiplying the 'Quantity' by the 'UnitAmount', adjusted for any discounts or tax treatments. |
| LineItem_TrackingCategory1_CategoryId | String | False |
The ID of the first tracking category for the line item. Xero allows up to two optional tracking categories, used to further categorize transactions for detailed reporting. |
| LineItem_TrackingCategory1_CategoryName | String | False |
The name of the first tracking category. This provides a label for the category, helping users understand how the line item is classified in financial reports. |
| LineItem_TrackingCategory1_OptionId | String | False |
The ID of the selected option within the first tracking category. This helps specify the exact classification option chosen for the line item. |
| LineItem_TrackingCategory1_OptionName | String | False |
The name of the selected option within the first tracking category. This provides clarity on the option selected for further classification. |
| LineItem_TrackingCategory1_Option_Stat | String | False |
The status of the first tracking category option, which indicates whether it is active or inactive for reporting purposes. |
| LineItem_TrackingCategory2_CategoryId | String | False |
The ID of the second tracking category for the line item. This allows for further categorization using two tracking categories in Xero. |
| LineItem_TrackingCategory2_CategoryName | String | False |
The name of the second tracking category. This provides a label for the category, helping classify the line item for more detailed reporting. |
| LineItem_TrackingCategory2_OptionId | String | False |
The ID of the selected option within the second tracking category, used to specify which option the line item belongs to. |
| LineItem_TrackingCategory2_OptionName | String | False |
The name of the selected option within the second tracking category. This provides more context on how the line item is categorized. |
| LineItem_TrackingCategory2_Option_Stat | String | False |
The status of the second tracking category option, indicating whether the option is active or inactive for reporting. |
| LineItem_DiscountRate | Double | False |
The discount rate applied to the line item. This percentage reduces the amount billed for the item. Discounts are only supported on 'ACCREC' (sales) invoices. |
| LineItem_DiscountAmount | Decimal | False |
The total discount applied to the line item, calculated based on the discount rate and the line item's amount. Discounts are only supported on 'ACCREC' (sales) invoices. |
| LineItemAggregate | String | False |
Used to define multiple line item rows using XML values. This field should only be provided during an 'INSERT' operation to create new line items for the invoice. |
| Date | Date | False |
The date the invoice was created. This field indicates when the invoice was issued, which can be used for aging reports and other financial analyses. |
| DueDate | Date | False |
The date the invoice is due for payment. This field helps determine when payment is expected and is used to track overdue invoices. |
| LineAmountTypes | String | False |
This field specifies whether line amounts include tax. The valid values are 'Exclusive' (tax is excluded), 'Inclusive' (tax is included), and 'NoTax' (no tax is applied). If this field is not specified, line amounts are treated as exclusive by default. |
| InvoiceNumber | String | False |
The unique alphanumeric code identifying the invoice. For 'ACCREC' invoices, this field is automatically generated unless specified. For 'ACCPAY' invoices, it stores a non-unique identifier for the invoice. |
| Reference | String | False |
An additional reference number for 'ACCREC' invoices. This field is used to store extra identifying information related to the invoice. |
| BrandingThemeId | String | False |
The unique identifier of the branding theme used for the invoice. This field allows users to apply custom branding and templates to the invoice. |
| URL | String | False |
A URL linking to a source document associated with the invoice, such as a scanned copy or a related external document. |
| CurrencyCode | String | False |
The ISO 4217 currency code used for the invoice. This specifies the currency in which the invoice is issued. |
| CurrencyRate | Decimal | False |
The exchange rate applied to the invoice if it is a multicurrency invoice. If not provided, the XE.com daily rate is used for currency conversion. |
| Status | String | False |
The current status of the invoice. The valid status values are 'DRAFT', 'SUBMITTED', and 'AUTHORISED', indicating whether the invoice is in draft, submitted for approval, or fully authorized. |
| SentToContact | Boolean | False |
Indicates whether the invoice has been sent to the contact. This field is only available for invoices that have been approved and ready to be sent to the customer or supplier. |
| ExpectedPaymentDate | Date | True |
The expected payment date for sales invoices ('ACCREC'). This date indicates when the payment is expected from the customer. |
| PlannedPaymentDate | Date | True |
The planned payment date for bills ('ACCPAY'). This field indicates when the payment is scheduled to be made to a supplier. |
| SubTotal | Decimal | True |
The subtotal of the invoice, excluding taxes. This represents the sum of the line items before tax is applied. |
| TotalTax | Decimal | True |
The total tax applied to the invoice. This is calculated based on the tax rates for each line item. |
| Total | Decimal | True |
The total amount of the invoice, including tax. This is the sum of 'SubTotal' and 'TotalTax'. |
| TotalDiscount | Decimal | True |
The total discount applied to the invoice. This is the sum of all discounts provided on line items, if applicable. |
| HasAttachments | Boolean | True |
Indicates whether the invoice has any attachments, such as scanned documents or supporting files. |
| PaymentIds | String | True |
A comma-delimited list of payment IDs associated with the invoice. This links the invoice to the payments made towards it. |
| PrePaymentIds | String | True |
A comma-delimited list of prepayment IDs applied to the invoice. This links any prepayments to the invoice. |
| OverPaymentIds | String | True |
A comma-delimited list of overpayment IDs applied to the invoice. This links any overpayments to the invoice. |
| CreditNoteIds | String | True |
A comma-delimited list of credit note IDs applied to the invoice. This shows which credit notes have been used to reduce the invoice amount. |
| AmountDue | Decimal | True |
The remaining amount due on the invoice, which is the difference between the total invoice amount and any payments, prepayments, or credits applied. |
| AmountPaid | Decimal | True |
The total amount of payments received for the invoice. |
| CISDeduction | Decimal | True |
The Construction Industry Scheme (CIS) deduction withheld from the payment, applicable only to UK organizations. |
| FullyPaidOnDate | Date | True |
The date the invoice was fully paid. This is only returned for invoices that have been marked as fully paid. |
| AmountCredited | Decimal | True |
The total amount credited to the invoice from credit notes, overpayments, or prepayments. |
| UpdatedDateUTC | Datetime | True |
The timestamp of when the invoice was last updated. This field provides the last modification time for the invoice. |
| TenantId | String | False |
The unique identifier of the tenant. This ensures the query retrieves data specific to a particular tenant, ensuring proper data isolation in multi-tenant environments. |
Manages items in Xero. Items can be products, services, or other billable units used in transactions.
The Items table allows you to SELECT, INSERT, and UPDATE items for a Xero organization.
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new item record, the Code field must be defined.
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
| Name | Type | ReadOnly | Description |
| ItemId [KEY] | String | True |
The unique, Xero-assigned identifier for the item. This field helps to uniquely identify and reference each item within the Xero system. |
| Code | String | False |
A user-defined code that identifies the item. This code is used to categorize or reference the item in transactions and reports. |
| InventoryAssetAccountCode | String | False |
The inventory asset account associated with the item. The account must be of type 'INVENTORY', and a 'COGSAccountCode' in 'PurchaseDetails' is also required to create a tracked item. This ensures proper accounting for inventory items. |
| Name | String | False |
The name of the item. This field holds the item's primary identifier, used in various documents and reports to refer to the item. |
| PurchaseDescription | String | False |
A description of the item for purchase transactions. This field helps clarify the details of the item when being purchased. |
| Description | String | False |
A general description of the item. This provides additional details about the item to be used in reports and transaction documents. |
| PurchaseDetails_UnitPrice | String | False |
The unit price of the item in purchase transactions. This value determines how much is paid per unit when purchasing the item. |
| PurchaseDetails_COGSAccountCode | String | False |
The cost of goods sold (COGS) account associated with the purchase of the item. Only applicable to tracked items. This account reflects the expense of items sold and is essential for proper inventory tracking. |
| PurchaseDetails_AccountCode | String | False |
The account code associated with the purchased item. This determines which account is used for accounting purposes when the item is purchased. |
| PurchaseDetails_TaxType | String | False |
The tax rate applied to the item during purchase. The tax rate varies by country, and user-defined tax rates are represented as 'TAX001', 'TAX002' |
| SalesDetails_UnitPrice | String | False |
The unit price of the item in sales transactions. This price is used when the item is sold and reflects the amount charged to the customer per unit. |
| SalesDetails_COGSAccountCode | String | False |
The cost of goods sold (COGS) account associated with the sale of the item. Only applicable to tracked items. This helps allocate the cost of goods sold during a sale. |
| SalesDetails_AccountCode | String | False |
The account code associated with the sale of the item. This code determines which account is used for accounting purposes during a sale. |
| SalesDetails_TaxType | String | False |
The tax rate applied to the item during sales. Like 'PurchaseDetails_TaxType', the tax rate varies by country, with user-defined tax rates represented as 'TAX001', 'TAX002' |
| IsTrackedAsInventory | Boolean | False |
Indicates whether the item is tracked as inventory. The value is 'true' for items where the 'InventoryAssetAccountCode' and 'COGSAccountCode' are set, meaning they are managed and monitored in inventory. |
| TotalCostPool | Decimal | True |
The total value of the item on hand, calculated using average cost accounting. This value reflects the overall value of the inventory item based on purchase history. |
| QuantityOnHand | Double | True |
The current quantity of the item available in inventory. This number represents how many units of the item are currently in stock. |
| IsSold | Boolean | False |
Boolean value indicating whether the item is available for sales transactions in Xero. If the value is 'false', the item will not appear in the sales section, and related sales values (Description, SalesDetails) will be nulled. |
| IsPurchased | Boolean | False |
Boolean value indicating whether the item is available for purchase transactions in Xero. If the value is 'false', the item will not appear in the purchase section, and related purchase values (PurchaseDescription, PurchaseDetails) will be nulled. |
| UpdatedDateUTC | Datetime | True |
The timestamp of the last update made to the item record. This helps track when the item details were last modified. |
| TenantId | String | False |
The unique identifier of the tenant. This ensures the query retrieves data specific to a particular tenant, especially in multi-tenant environments where data needs to be isolated between tenants. |
Used to manage linked transactions, allowing users to associate related transactions in Xero for better tracking and reporting.
| Name | Type | ReadOnly | Description |
| LinkedTransactionID [KEY] | String | True |
The unique Xero identifier for a linked transaction. This field ties together the source and target transactions, enabling users to track related transactions within the system. |
| SourceTransactionID | String | False |
The identifier of the source transaction, such as the purchase component of a billable expense. Currently, only invoices with the type 'ACCPAY' (Accounts Payable) can be used as source transactions. |
| SourceLineItemID | String | False |
The unique line item identifier from the source transaction. This specifies which line item from the source transaction is linked to the current transaction, providing detailed traceability for the expense. |
| ContactID | String | False |
The identifier for the contact associated with the target transaction. In this context, it represents the customer to whom the expense is being billed, linking the expense to a specific customer or client. |
| TargetTransactionID | String | False |
The unique identifier of the target transaction, which is the sales component of a billable expense. Currently, only invoices with the type 'ACCREC' (Accounts Receivable) can be used as target transactions. |
| TargetLineItemID | String | False |
The line item identifier from the target transaction. This is used when allocating a billable expense to a target transaction. It is optional and can be omitted if not needed for the transaction allocation. |
| Status | String | False |
The current status of the linked transaction. This is derived from the statuses of both the source and target transactions and reflects the overall status of the linked transaction. The status cannot be manually set or updated. |
| Type | String | False |
The type of the linked transaction. This field is set to 'BILLABLEEXPENSE', representing a billable expense type. Additional types may be introduced in future updates to accommodate different transaction categories. |
| UpdatedDateUTC | Datetime | True |
The timestamp indicating the last modification of the linked transaction in UTC format. This helps track when changes were made to the linked transaction and ensures up-to-date information is available. |
| TenantId | String | False |
The unique identifier of the tenant. This ensures that the query retrieves data specific to a particular tenant, especially in multi-tenant environments where data must be isolated between different organizations. |
Used to query, insert, and update manual journals. Manual journals are used to record financial transactions that don't follow standard processes.
The ManualJournals table allows you to SELECT, INSERT, and UPDATE manual journals journal lines for a Xero organization. The Id column is generated by the Cloud; it combines the index of the line item with the unique, Xero-generated ManualJournalId.
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 Xero API does not list a high volume threshold for the ManualJournals table. The Xero API lists the following optimized filters for this table:
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new manual journal record, the Narration field is required in addition to at least two line items. A journal record must contain at least one credit and one debit, so that the record as a whole is balanced.
INSERT INTO ManualJournals (Narration, JournalLineAggregate) VALUES (
'Accrued expenses',
'<JournalLine>
<Description>Coded incorrectly Office Equipment should be Computer Equipment</Description>
<TaxType>NONE</TaxType>
<LineAmount>-2569</LineAmount>
<AccountCode>720</AccountCode>
</JournalLine>
<JournalLine>
...
</JournalLine>'
)
Note: This method must be used for inserting multiple parent ManualJournals in a single query.INSERT INTO ManualJournals (ManualJournalId, JournalLine_LineAmount, JournalLine_AccountCode) VALUES ('XXXXX-XXXXX-XXXXX-XXXXX', 55.00, '200')Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the journal line, combining its position in the history log with the Xero-generated identifier of the manual journal. This ensures that each journal entry can be traced and tracked accurately. |
| ManualJournalId | String | False |
The unique identifier of the manual journal. This links each journal line item to a specific manual journal, allowing for easy reference and organization. |
| Narration | String | False |
A description of the journal being posted. This field provides additional context or explanation about the journal entry, helping users understand the purpose of the journal. |
| JournalLine_LineAmount | Decimal | False |
The total for the journal line item. This value is positive for debits and negative for credits, reflecting the financial impact of the line item on the account. |
| JournalLine_AccountCode | String | False |
The account code that identifies the account associated with the journal line item. This field links the journal line to a specific account in the organization's chart of accounts. |
| JournalLine_Description | String | False |
The description for the manual journal line item. This provides more details about the transaction and is used to explain the nature of the entry being recorded. |
| JournalLine_TaxType | String | False |
The tax type applied to the journal line item. This field allows overriding the default tax code for the selected account, enabling specific tax treatments for individual journal lines. |
| JournalLine_TrackingCategory1_CategoryId | String | False |
The ID of the first tracking category associated with the journal line item. Xero allows two optional tracking categories to be defined for more granular reporting. |
| JournalLine_TrackingCategory1_CategoryName | String | False |
The name of the first tracking category. This helps users understand how the journal line item is categorized for detailed financial reporting. |
| JournalLine_TrackingCategory1_OptionId | String | False |
The ID of the selected option within the first tracking category. This further refines the categorization of the journal line item. |
| JournalLine_TrackingCategory1_OptionName | String | False |
The name of the selected option within the first tracking category. This provides more clarity on how the journal line item is classified within the category. |
| JournalLine_TrackingCategory1_Option_Stat | String | False |
The status of the selected option in the first tracking category. This indicates whether the option is active or inactive, affecting how the journal item is reported. |
| JournalLine_TrackingCategory2_CategoryId | String | False |
The ID of the second tracking category for the journal line item. This enables further categorization, providing additional classification in financial reporting. |
| JournalLine_TrackingCategory2_CategoryName | String | False |
The name of the second tracking category. This field helps classify the journal line item in a second category, further breaking down the financial data. |
| JournalLine_TrackingCategory2_OptionId | String | False |
The ID of the selected option within the second tracking category. This further refines the classification of the journal line item. |
| JournalLine_TrackingCategory2_OptionName | String | False |
The name of the selected option within the second tracking category. This provides more context about how the journal line item is categorized. |
| JournalLine_TrackingCategory2_Option_Stat | String | False |
The status of the selected option in the second tracking category. This indicates whether the option is active or inactive, impacting the item's inclusion in reports. |
| JournalLineAggregate | String | False |
Used to define multiple journal line items in XML format. This field should only be provided during an 'INSERT' operation to create new line items for the journal. |
| Date | Date | False |
The date the journal was posted. This field indicates when the journal entry was officially recorded in the system and helps track when financial transactions occurred. |
| Status | String | False |
The status code of the manual journal. The valid values are 'VALID', 'POSTED', 'DELETED', and 'VOIDED', representing the journal's current state in the system. |
| URL | String | False |
A URL to a source document associated with the journal. This could link to external references, supporting documentation, or scanned copies of receipts and invoices. |
| ShowOnCashBasisReports | Boolean | False |
Indicates whether this journal should be included in cash-basis reports. By default, this field is set to 'true', meaning the journal will be included in reports based on cash accounting. |
| LineAmountTypes | String | False |
The line amount type, which specifies whether line amounts include tax. Valid values are 'Exclusive' (tax is excluded), 'Inclusive' (tax is included), and 'NoTax' (no tax is applied). This ensures accurate tax reporting. |
| UpdatedDateUTC | Datetime | True |
The timestamp of when the manual journal was last updated. This helps track when changes were made to the journal, ensuring up-to-date information is available. |
| HasAttachments | Boolean | True |
Indicates whether the journal entry has any attachments, such as receipts or supporting documents. This field helps identify journals with additional documentation. |
| TenantId | String | False |
The unique identifier of the tenant. This ensures the query retrieves data specific to a particular tenant in multi-tenant environments, isolating the data for a specific organization. |
Used to query, insert, and delete payment records within Xero. Payments include transactions made to suppliers or received from customers.
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.
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:
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.
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.
| 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. |
Used to query, insert, and update purchase orders in Xero. Purchase orders are used to track items or services that the organization intends to buy from suppliers.
The PurchaseOrders table allows you to SELECT, INSERT, and UPDATE PurchaseOrder lines for a Xero organization. The Id column is generated by the Cloud; it combines the index of the line item with the unique, Xero-generated PurchaseOrderId.
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new Purchase Order, the ContactId and Date fields are required in addition to at least one line item. A PurchaseOrder line item must at minimum contain a description (LineItem_Description).
INSERT INTO PurchaseOrders (Contact_ContactId, LineItemAggregate) VALUES (
'883628bc-7f22-4234-8a4c-81571816a8a1',
'<LineItem>
<Description>Example Description</Description>
</LineItem>
<LineItem>
...
</LineItem>'
)INSERT INTO PurchaseOrders (Contact_ContactId, LineItem_Description)
VALUES
('37ec4d02-dc3f-4a4c-a943-e8ae8c7db93a', 'Example1'),
('abcd1234-1234-1b2c-a123-abcde12345ab', 'Example2')INSERT INTO PurchaseOrders (PurchaseOrderId, LineItem_Description)
VALUES
('fbb38812-dcc4-4e07-9ebd-2c38e1409b18', 'Example1'),
('fbb38812-dcc4-4e07-9ebd-2c38e1409b18', 'Example2')Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
The unique combination of the position of the history item and its associated purchase order ID. |
| PurchaseOrderId | String | False |
The unique Xero identifier for the purchase order, linking the item to the corresponding purchase order. |
| PurchaseOrderNumber | String | False |
A unique identifier that represents the purchase order, making it easy to track and refer to the order. |
| Reference | String | False |
An optional field to store a reference number for the purchase order for further identification or tracking. |
| Type | String | False |
The purchase order type. Valid values are 'ACCPAYCREDIT' for credit notes related to accounts payable, and 'ACCRECCREDIT' for credit notes related to accounts receivable. |
| Contact_ContactId | String | False |
The unique identifier of the contact associated with the purchase order, linking it to a specific supplier or customer. |
| Contact_Name | String | False |
The name of the contact associated with the purchase order, typically the name of the supplier or customer. |
| DeliveryDate | Date | False |
The date when the goods or services are scheduled to be delivered as per the purchase order. |
| ExpectedArrivalDate | Date | False |
The expected date of arrival for the goods or services specified in the purchase order. |
| DeliveryAddress | String | False |
The address where the goods or services from the purchase order are to be delivered. |
| AttentionTo | String | False |
The person to whom the delivery is directed or who is responsible for receiving it. |
| Telephone | String | False |
The phone number of the person receiving the delivery, allowing for easy contact in case of issues. |
| DeliveryInstructions | String | False |
A free-form field to include any specific instructions or details required to complete the delivery. |
| Date | Date | False |
The date when the purchase order was created, marking its initiation in the system. |
| Status | String | False |
The current status of the purchase order. Common statuses include 'DRAFT', 'SUBMITTED', 'AUTHORISATION_PENDING', and 'CLOSED'. |
| LineAmountTypes | String | False |
Specifies whether the line amounts in the purchase order include tax (default). Valid values are 'Exclusive', 'Inclusive', and 'NoTax'. |
| LineItem_LineItemId | String | False |
The unique Xero-generated identifier for a line item in the purchase order. If 'LineItemIds' are not provided during an update request, the existing line items are deleted and recreated. |
| LineItem_Description | String | False |
The description for each line item, explaining the product or service being purchased. This field must contain at least one character and is required for invoice approval. |
| LineItem_Quantity | Double | False |
The quantity of the item being ordered in the line item. This value must be a positive number or zero for the order to be approved. |
| LineItem_UnitAmount | Decimal | False |
The unit price of the item, which is the cost per single unit of the product or service ordered. |
| LineItem_ItemCode | String | False |
The code that uniquely identifies the item being purchased, as defined by the supplier or organization. |
| LineItem_AccountCode | String | False |
The account code associated with the item. This account code must be active within the organization for the purchase order to be approved. |
| LineItem_TaxType | String | False |
The tax type that applies to the line item, overriding the default tax code for the account, if necessary. |
| LineItem_TaxAmount | Decimal | False |
The total tax applied to the line item, calculated based on the 'TaxType' and 'UnitAmount'. |
| LineItem_LineAmount | Decimal | False |
The total amount of the line item, calculated as the quantity multiplied by the unit amount, with discounts applied if any. |
| LineItem_DiscountRate | Double | False |
The discount percentage applied to the line item. Discounts are only supported for 'ACCREC'-type (sales) purchase orders. |
| LineItemAggregate | String | False |
This field is used to define multiple line item rows using XML values. It should only be included when performing an INSERT operation. |
| SubTotal | Decimal | False |
The subtotal of the purchase order, which excludes any applicable taxes. |
| TotalTax | Decimal | False |
The total tax amount applied to the entire purchase order. |
| Total | Decimal | False |
The total amount of the purchase order, including both the subtotal and the applicable tax. |
| LineItem_TrackingCategory1_CategoryId | String | False |
The ID of the first tracking category, if used. The API allows up to two optional tracking categories to be defined for each line item. |
| LineItem_TrackingCategory1_CategoryName | String | False |
The name of the first tracking category, if used. |
| LineItem_TrackingCategory1_OptionId | String | False |
The ID of the first tracking category option, if used. Tracking categories allow you to track multiple attributes in your accounts. |
| LineItem_TrackingCategory1_OptionName | String | False |
The name of the first tracking category option, if used. |
| LineItem_TrackingCategory1_Option_Stat | String | False |
The status of the first tracking category option, if used. |
| LineItem_TrackingCategory2_CategoryId | String | False |
The ID of the second tracking category, if used. |
| LineItem_TrackingCategory2_CategoryName | String | False |
The name of the second tracking category, if used. |
| LineItem_TrackingCategory2_OptionId | String | False |
The ID of the second tracking category option, if used. |
| LineItem_TrackingCategory2_OptionName | String | False |
The name of the second tracking category option, if used. |
| LineItem_TrackingCategory2_Option_Stat | String | False |
The status of the second tracking category option, if used. |
| UpdatedDateUTC | Datetime | True |
The timestamp for when the purchase order was last updated in the system. |
| HasAttachments | Boolean | True |
Indicates whether the purchase order has any attached files or documents. |
| CurrencyCode | String | False |
The currency used for the purchase order. This value corresponds to the ISO 4217 currency code. |
| BrandingThemeId | String | False |
The ID of the branding theme used for the purchase order. |
| CurrencyRate | Decimal | False |
The exchange rate applied when the purchase order is processed in a non-base currency. If this is not provided, either the user-defined rate or the XE.com day rate will be applied. |
| TenantId | String | False |
The ID of the tenant to query, used for multi-tenant environments to ensure the correct data is returned. |
Allows querying and managing quotes for a Xero organization. Quotes are used to provide potential customers with a detailed offer of goods or services at specified prices before an order is placed.
The Quotes table allows you to SELECT, INSERT, and UPDATE Quote lines for a Xero organization. The Id column is generated by the Cloud; it combines the index of the line item with the unique, Xero-generated QuoteId.
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new Quote, the ContactId and Date fields are required in addition to at least one line item. A Quote line item must at minimum contain a description (LineItem_Description).
INSERT INTO Quotes (ContactId, Date, LineItemAggregate) VALUES (
'883628bc-7f22-4234-8a4c-81571816a8a1',
'2023-11-21',
'<LineItem>
<Description>Example Description</Description>
</LineItem>'
)INSERT INTO Quotes (ContactId, Date, LineItem_Description)
VALUES
('883628bc-7f22-4234-8a4c-81571816a8a1', '2023-11-21', 'Example Description'),
('883628bc-7f22-4234-8a4c-81571816a8a1', '2023-11-21', 'Example Description')INSERT INTO Quotes (QuoteId, LineItem_Description)
VALUES
('fbb38812-dcc4-4e07-9ebd-2c38e1409b18', 'newItem1'),
('fbb38812-dcc4-4e07-9ebd-2c38e1409b18', 'newItem2')Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | False |
A combination of the line item index and the unique Xero identifier for the Quote. |
| QuoteId | String | False |
The unique Xero identifier for the quote, linking the line item to the quote. |
| ContactId | String | False |
The unique identifier for the contact associated with the quote, representing the customer. |
| ContactName | String | False |
The name of the contact person for the quote, typically the customer or company. |
| Date | Date | False |
The date the quote was created or issued to the customer. |
| ExpiryDate | Date | False |
The date when the quote expires, after which it is no longer valid. |
| Status | String | False |
The current status of the quote. For example, 'DRAFT', 'SUBMITTED', 'ACCEPTED', 'DECLINED', or 'EXPIRED'. |
| LineItem_LineItemId | String | False |
The Xero-generated identifier for a specific line item in the quote. |
| LineItem_Description | String | False |
A brief description of the item or service being quoted. This field is required for each line item. |
| LineItem_Quantity | Double | False |
The quantity of the item or service being quoted, must be a positive value. |
| LineItem_UnitAmount | Decimal | False |
The unit price of the quoted item or service, before any taxes or discounts. |
| LineItem_ItemCode | String | False |
A user-defined code that uniquely identifies the quoted item, useful for inventory management. |
| LineItem_AccountCode | String | False |
The account code associated with the item or service being quoted. This must be a valid and active account in the organisation. |
| LineItem_TaxType | String | False |
The tax type applied to the line item, overriding the default tax code for the selected account. |
| LineItem_TaxAmount | Decimal | False |
The calculated amount of tax applied to the line item, based on the 'TaxType' and 'UnitAmount'. |
| LineItem_LineAmount | Decimal | False |
The total value of the line item, calculated by multiplying 'Quantity' by 'UnitAmount', including any discounts. |
| LineItem_DiscountRate | Double | False |
The percentage discount applied to the line item. Discounts are optional and are typically applied to 'ACCREC'-type (sales) quotes. |
| LineItem_TrackingCategory1_CategoryId | String | False |
The ID of the first tracking category used for tracking the line item. Two tracking categories can be defined per item. |
| LineItem_TrackingCategory1_CategoryName | String | False |
The name of the first tracking category used for categorizing the line item. |
| LineItem_TrackingCategory1_OptionId | String | False |
The ID of the first option in the tracking category. |
| LineItem_TrackingCategory1_OptionName | String | False |
The name of the first option in the tracking category. |
| LineItem_TrackingCategory2_CategoryId | String | False |
The ID of the second tracking category used for tracking the line item. |
| LineItem_TrackingCategory2_CategoryName | String | False |
The name of the second tracking category. |
| LineItem_TrackingCategory2_OptionId | String | False |
The ID of the second option in the tracking category. |
| LineItem_TrackingCategory2_OptionName | String | False |
The name of the second option in the tracking category. |
| QuoteNumber | String | False |
The unique alphanumeric identifier for the quote, used for tracking and referencing the quote. |
| LineAmountTypes | String | False |
Specifies whether line amounts include tax. Valid values are 'Exclusive', 'Inclusive', and 'NoTax'. |
| Reference | String | False |
An additional reference number associated with 'ACCREC'-type (sales) quotes. |
| CurrencyCode | String | False |
The ISO 4217 currency code indicating the currency used for the quote. |
| CurrencyRate | Decimal | False |
The exchange rate applied to the quote if it's a multicurrency transaction. If not specified, XE.com daily rates are used. |
| SubTotal | Decimal | False |
The subtotal of the quote, which excludes taxes and additional charges. |
| TotalTax | Decimal | False |
The total tax amount for the quote, calculated based on applicable tax rates. |
| Total | Decimal | False |
The total amount for the quote, including both the subtotal and the total tax. |
| TotalDiscount | Decimal | False |
The total value of discounts applied to the quote's line items. |
| BrandingThemeId | String | False |
The ID of the branding theme used for the quote, which affects its appearance. |
| Terms | String | False |
The terms of the quote, outlining the conditions under which the quote is valid or any specific terms agreed upon. |
| UpdatedDateUTC | Datetime | False |
The timestamp of when the quote was last updated or modified. |
| TenantId | String | False |
The ID of the tenant to query instead of the connection tenant, useful for multi-tenant environments. |
| LineItemAggregate | String | False |
Used to define multiple 'Quote LineItem' rows using XML values. This should be included only when performing an 'INSERT' operation. |
Enables querying, inserting, and updating receipts for a Xero organization. Receipts confirm that payments have been made, and they help track money received by the organization.
The Receipts table allows you to SELECT, INSERT, UPDATE, and DELETE receipt line items for a Xero organization. The Id column is generated by the Cloud; it combines the index of the line item with the unique, Xero-generated ReceiptId.
Note that this table only includes draft receipts - to retrieve receipts that have already been claimed, you will need to read from the ExpenseClaimReceipts view.
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To insert a receipt record, the following fields are required in addition to at least one line item: Date, Contact_Name, and User_UserId. To add a new line item, the following fields are required: LineItem_Description, LineItem_UnitAmount, and LineItem_AccountCode.
In addition to inserting a single row, line item tables offer two additional ways to insert into a table.
INSERT INTO Receipts (Date, Contact_Name, User_UserId, LineItemAggregate) VALUES (
'4/19/2006 9:16:48 AM',
'John Doe',
'c81045b2-5740-4aea-bf8a-3956941af387',
'<LineItem>
<Description>Coffee with client</Description>
<UnitAmount>13.00</UnitAmount>
<AccountCode>200</AccountCode>
</LineItem>
<LineItem>
<Description>Bagel</Description>
<UnitAmount>2.00</UnitAmount>
<AccountCode>200</AccountCode>
</LineItem>'
)INSERT INTO Receipts (ReceiptId, LineItem_Description, LineItem_UnitAmount) VALUES ('XXXXX-XXXXX-XXXXX-XXXXX', 'Coffee with client', 13.80)Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
The Xero API has limited support for deleting any object. In order to delete objects, you must update their Status to an appropriate value.
Applicable values for this field may be state-dependent. For example, invoices can only have their status set to DELETED when the invoice status is currently DRAFT or SUBMITTED.
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A combination of the line item index and the unique Xero-generated identifier for the receipt. |
| ReceiptId | String | False |
The unique Xero-generated identifier for the receipt, linking it to the transaction. |
| Date | Date | False |
The date when the receipt was issued or created. |
| Contact_ContactId | String | False |
The unique identifier for the contact associated with the receipt. A contact must be specified when creating a receipt. |
| Contact_Name | String | False |
The name of the contact associated with the receipt, typically the customer or company. |
| LineItem_Description | String | False |
A description for the item or service in the receipt. This field must contain at least one character and is required to create an approved receipt. |
| LineItem_UnitAmount | Decimal | False |
The unit price for the item or service listed on the receipt. |
| LineItem_AccountCode | String | False |
The account code associated with the receipt item. This must be an active account for the organisation. |
| LineItem_Quantity | Double | False |
The quantity of the item or service being purchased. This value must be zero or positive. |
| LineItem_TaxType | String | False |
The tax type applied to the item. This field can be used to override the default tax code for the selected account. |
| LineItem_LineAmount | Decimal | False |
The total amount for the line item, calculated by multiplying 'Quantity' by 'UnitAmount', including applicable discounts. |
| LineItem_TrackingCategory1_CategoryId | String | False |
The ID of a tracking category used to classify the line item. Two tracking categories can be defined for each item. |
| LineItem_TrackingCategory1_CategoryName | String | False |
The name of the tracking category associated with the line item. |
| LineItem_TrackingCategory1_OptionId | String | False |
The ID of the specific option within the tracking category. |
| LineItem_TrackingCategory1_OptionName | String | False |
The name of the tracking category option for the line item. |
| LineItem_TrackingCategory1_Option_Stat | String | False |
The status of the tracking category option. Defines the current state of the option. |
| LineItem_TrackingCategory2_CategoryId | String | False |
The ID of a second tracking category, if applicable, for the line item. |
| LineItem_TrackingCategory2_CategoryName | String | False |
The name of the second tracking category, if defined. |
| LineItem_TrackingCategory2_OptionId | String | False |
The ID of the second tracking category option. |
| LineItem_TrackingCategory2_OptionName | String | False |
The name of the second tracking category option. |
| LineItem_TrackingCategory2_Option_Stat | String | False |
The status of the second tracking category option. |
| LineItem_DiscountRate | Double | False |
The discount rate applied to the line item, expressed as a percentage. |
| LineItemAggregate | String | False |
Used to define multiple LineItem rows in XML format. Should only be provided during an INSERT operation. |
| User_UserId | String | False |
The ID of the user within the organisation that the expense claim receipt is associated with. |
| Reference | String | False |
An additional reference number to help identify the receipt or tie it to an external reference. |
| LineAmountTypes | String | False |
Specifies whether line amounts include tax. Valid values are 'Exclusive', 'Inclusive', and 'NoTax'. |
| SubTotal | Decimal | False |
The total value of the receipt, excluding taxes and discounts. |
| TotalTax | Decimal | False |
The total amount of tax applied to the receipt based on applicable rates. |
| Total | Decimal | False |
The total amount for the receipt, including both the subtotal and the total tax. |
| Status | String | True |
The current status of the receipt. Valid values are 'DRAFT', 'SUBMITTED', 'AUTHORISED', and 'DECLINED'. |
| ReceiptNumber | String | True |
The Xero-generated number identifying the receipt in the current sequence for the given user. |
| UpdatedDateUTC | Datetime | True |
The date and time when the receipt was last updated in the system. |
| HasAttachments | Boolean | True |
Indicates whether the receipt has any attachments linked to it. |
| URL | String | True |
A link to a source document associated with the receipt for reference. |
| TenantId | String | False |
The ID of the tenant to query, used when querying multiple tenants instead of the connection tenant. |
Manages tax rates in Xero. It allows you to query, insert, and update tax rates, which are necessary for calculating tax liabilities on sales and purchases.
The TaxRates table allows you to SELECT, INSERT, and UPDATE tax components for tax rates in a Xero organization. The Id column is generated by the Cloud this value combines the index of the line item with the unique, Xero-generated TaxType.
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To create a new tax rate, the Name field must be set in addition to at least one tax component; the TaxComponent_Name, TaxComponent_Rate, and TaxComponent_IsCompound fields are required to insert a new line item.
In addition to inserting a single row, this table offers two additional ways to insert into a table.
INSERT INTO TaxRates (Name, TaxComponentAggregate) VALUES (
'My Tax Rate',
'<TaxComponent>
<Name>customTax1</Name>
<Rate>1.0000</Rate>
<IsCompound>false</IsCompound>
</TaxComponent>
<TaxComponent>
<Name>customTax2</Name>
<Rate>2.0000</Rate>
<IsCompound>false</IsCompound>
</TaxComponent>'
)INSERT INTO TaxRates (TaxType, TaxComponent_Name, TaxComponent_Rate, TaxComponent_IsCompound) VALUES ('TAX001', 'customTax2', '2.0000', 'False')Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
Note: You cannot update predefined tax rates through the Xero API.
The Xero API has limited support for deleting any object. In order to delete objects, you must update their Status to an appropriate value.
Applicable values for this field may be state-dependent. For example, invoices can only have their status set to DELETED when the invoice status is currently DRAFT or SUBMITTED.
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | True |
A unique identifier for the tax component, which is a combination of the tax component index and the TaxType. |
| TaxType | String | True |
The type of tax rate applied. Default tax rates are provided by Xero, but new tax rates can be created. TaxTypes for new rates are assigned in the format TAX001, TAX002 |
| Name | String | False |
The name assigned to the tax rate, typically describing the nature of the tax (for example, VAT or GST). |
| TaxComponent_Name | String | False |
The name of the specific tax component within the tax rate. |
| TaxComponent_Rate | Double | False |
The rate of the tax component expressed as a percentage. This is accurate to 4 decimal places. |
| TaxComponent_IsCompound | Boolean | False |
A boolean value that indicates whether the tax rate is compounded. Compound tax rates mean the tax is applied on top of previous tax rates. |
| TaxComponentAggregate | String | False |
This field is used to define multiple TaxComponent rows using XML values. This is provided only during an INSERT operation. |
| Status | String | False |
The current status of the tax rate. Possible values include ACTIVE and DELETED. |
| ReportTaxType | String | False |
The report tax type. This element is required for Australian (AU), New Zealand (NZ), and UK organisations. It is not applicable to US and global organisations. |
| CanApplyToAssets | Boolean | True |
A boolean indicating whether the tax rate can be applied to asset accounts. |
| CanApplyToEquity | Boolean | True |
A boolean indicating whether the tax rate can be applied to equity accounts. |
| CanApplyToExpenses | Boolean | True |
A boolean indicating whether the tax rate can be applied to expense accounts. |
| CanApplyToLiabilities | Boolean | True |
A boolean indicating whether the tax rate can be applied to liability accounts. |
| CanApplyToRevenue | Boolean | True |
A boolean indicating whether the tax rate can be applied to revenue accounts. |
| DisplayTaxRate | Double | True |
The tax rate displayed as a decimal, rounded to 4 decimal places (for example, 12.5000). |
| EffectiveRate | Double | True |
The effective tax rate, also expressed as a decimal and accurate to 4 decimal places (for example, 12.5000). |
| TenantId | String | False |
The ID of the tenant for querying, which overrides the connection tenant for this query. |
Views are similar to tables in the way that data is represented; however, views are read-only.
Queries can be executed against a view as if it were a normal table.
| Name | Description |
| AgedPayablesByContact | Provides a way to query aged payables for a specific contact. It shows outstanding amounts owed by the organization to its contacts, broken down by aging periods (for example, 30, 60, or 90 days). |
| AgedReceivablesByContact | Allows for querying aged receivables for a contact. It displays amounts owed to the organization by its customers, categorized by aging periods, helping track the overdue invoices. |
| BalanceSheet | Queries the monthly balance sheet of a Xero organization. The balance sheet provides a snapshot of the organization's assets, liabilities, and equity at a given point in time. |
| BankStatement | Queries the transactions listed on a particular bank account. It includes deposits, withdrawals, and other banking activities associated with the organization's accounts. |
| BankSummary | Displays a summary of balances and cash movements for each bank account in a Xero organization. It is useful for analyzing cash flow and understanding the financial status of bank accounts. |
| BrandingThemes | Queries the branding themes defined for a Xero organization. Branding themes are used to customize the appearance of invoices, quotes, and other financial documents to align with the organization's branding. |
| BudgetLines | Queries the budget line items for a Xero organization. It allows users to track and manage detailed budget items within a larger financial plan. |
| Budgets | Queries budgets for a Xero organization. Budgets are used to track expected income and expenses over a specified period, providing valuable insight into financial performance. |
| BudgetSummary | Provides a monthly summary of the organization's budget. It compares actual income and expenses against the budgeted amounts, helping organizations track their financial goals. |
| ContactCISSettings | Queries Construction Industry Scheme (CIS) settings for contacts in a Xero organization. It is relevant for UK-based organizations involved in construction projects under the CIS tax regime. |
| CreditNoteAllocations | Allows for querying credit note allocations within a Xero organization. Credit note allocations are used to match credit notes with invoices or payments. |
| Currencies | Queries the currencies used in a Xero organization, providing information on the organization's base currency as well as any additional currencies used for multi-currency transactions. |
| ExecutiveSummary | Provides a summary of the changes between a given month and the previous month. It allows quick analysis of financial changes in income, expenses, and key performance indicators. |
| ExpenseClaimPayments | Allows querying the payments made for expense claims within a Xero organization. It tracks reimbursements made to employees for work-related expenses. |
| ExpenseClaimReceipts | Allows for querying claimed receipts in Xero. It includes receipts submitted by employees for reimbursement under an expense claim. |
| HistoryBankTransfers | Tracks the history and notes for bank transfers within a Xero organization. It provides insights into past transfers between accounts. |
| HistoryExpenseClaims | Queries the history and notes of expense claims in Xero. This helps track all past activities related to employee expense reimbursements. |
| HistoryItems | Used to query the history and notes of items (products or services) within a Xero organization. This tracks changes and updates made to items used in transactions. |
| HistoryOverpayments | Used to query the history and notes of overpayments in Xero. Overpayments occur when a customer pays more than the amount due. |
| HistoryPayments | Queries the payment history and notes for a Xero organization. It helps track the details of payments made to suppliers or received from customers. |
| HistoryPrepayments | Queries the history and notes of prepayments. Prepayments refer to amounts paid in advance for goods or services. |
| HistoryReceipts | Tracks the history and notes of receipts within Xero. Receipts confirm payments received by the organization. |
| HistoryRepeatingInvoices | Queries the history and notes of repeating invoices in Xero. Repeating invoices are generated automatically for recurring billing. |
| Journals | Used for querying line items in journals. Journals in Xero are used to record debits and credits for financial transactions. |
| Organisation | Used to query general organization data in Xero, including company details, settings, and configurations. |
| OrganisationActions | Used to query the actions performed on a Xero organization. This includes tax filings, internal reports, and administrative changes. |
| OverpaymentAllocations | Used to query the allocation of overpayments within Xero. This helps track excess payments made by customers and how they are applied to outstanding invoices. |
| Overpayments | Used to query overpayments made within a Xero organization. This helps manage and apply payments that exceed the amount owed. |
| PrepaymentAllocations | Used to query prepayment allocations. Prepayments are amounts paid in advance but not yet invoiced, and this view helps manage their application. |
| Prepayments | Used to query prepayment records. Prepayments refer to money paid before goods or services are received. |
| ProfitAndLoss | Used to query a Profit and Loss report for a specified date range, providing insights into the organization's income and expenses over the period. It is used to analyze financial performance and profitability. |
| RepeatingInvoices | Allows you to query templates for repeating invoices in Xero. Repeating invoices are automatically generated for regular billing cycles such as monthly or yearly, reducing the need for manual invoicing. |
| Tenants | Allows querying the list of organizations connected to your Xero account. It provides basic information about each tenant organization, such as its name and ID. |
| TrackingCategories | Enables querying tracking categories, which are used to segment financial transactions for better analysis and reporting. For example, you can track sales by region or department. |
| TrialBalance | Provides a trial balance for the Xero organization, showing the debits and credits for all accounts in the general ledger. It's essential for checking the accuracy of financial statements. |
| Users | Allows querying the list of users in a Xero organization. It includes user details like name, role, and access permissions, which are crucial for managing user access to financial data. |
Provides a way to query aged payables for a specific contact. It shows outstanding amounts owed by the organization to its contacts, broken down by aging periods (for example, 30, 60, or 90 days).
If the ContactId is not provided, the Aged Payables report for all contacts will be returned, one after the other. Please note that this will generate one operation against the Xero API per contact in the organization. Consider filtering to a subset of contacts or adding a LIMIT clause to avoid exceeding API limits. See Xero API Limits for more information.
| Name | Type | Description |
| ID [KEY] | String | A unique identifier for the row, combining the row number with the contact's unique ID, used to reference this specific entry. |
| ContactId | String | The unique identifier of the contact for which this bill or transaction is being reported. |
| Date | Datetime | The date when the bill was created. This timestamp marks when the bill was generated in the system. |
| Reference | String | A reference number for the purchase order associated with the bill, helping to link the bill to the corresponding order. |
| DueDate | Datetime | The date by which the amount on the bill is due for payment. This defines the deadline for the transaction. |
| Overdue | Decimal | The amount that is due after the due date has passed, reflecting the unpaid balance that is now overdue. |
| Currency | String | The currency used for all amounts in this entry, except for 'DueLocal', or empty if the default currency is being used for the organization. |
| Total | Decimal | The total amount due, including all charges or fees, calculated based on the items and any other applicable charges. |
| Paid | Decimal | The amount that has already been paid toward the bill, reflecting payments made up to the current point. |
| Credited | Decimal | The amount credited back, possibly due to refunds or adjustments, reducing the overall amount owed. |
| Due | Decimal | The remaining amount still owed, typically equal to 'Total' minus 'Paid' and 'Credited'. |
| DueLocal | Decimal | The amount still owed in the default organization currency, useful for organizations dealing with multiple currencies. |
| InvoiceId | String | The unique identifier of the invoice related to this bill, connecting the bill to the original invoice record. |
| TenantId | String | The unique identifier of the tenant to query for this particular operation, allowing access to data from a different tenant than the default connection. |
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| fromDate | Datetime | Shows all payable invoices from the specified date for the contact, used to filter results starting from a given date. |
| toDate | Datetime | Shows all payable invoices up to the specified date for the contact, used to filter results ending at a given date. |
Allows for querying aged receivables for a contact. It displays amounts owed to the organization by its customers, categorized by aging periods, helping track the overdue invoices.
If the ContactId is not provided, the Aged Receivables report for all contacts will be returned, one after the other. Please note that this will generate one operation against the Xero API per contact in the organization. Consider filtering to a subset of contacts or adding a LIMIT clause to avoid exceeding API limits. See Xero API Limits for more information.
| Name | Type | Description |
| ID [KEY] | String | A unique identifier for the row, created by combining the row number and the contact's ID. This ID is used to uniquely reference this particular entry. |
| ContactId | String | The unique identifier for the contact associated with this transaction or bill. This links the bill to a specific contact in the system. |
| Date | Datetime | The date when the invoice was created, marking the official creation date of the transaction. |
| Reference | String | The sale order reference number associated with this invoice. This helps to link the invoice to the corresponding sale order in the system. |
| DueDate | Datetime | The date by which payment for the invoice is due. This is the payment deadline for the amount specified in the invoice. |
| Overdue | Decimal | The amount that is still due after the 'DueDate' has passed. This represents the unpaid portion of the invoice that is now overdue. |
| Currency | String | The currency used for the amounts in this invoice, except for the 'DueLocal' amount. It will be empty if multi-currency is not enabled for the organization. |
| Total | Decimal | The total amount that is due for payment on this invoice. This includes the sum of all charges, fees, and adjustments. |
| Paid | Decimal | The total amount that has been paid towards this invoice. This is the sum of payments made against the total due amount. |
| Credited | Decimal | The amount that has been credited back to the account, possibly due to refunds, adjustments, or returned items, reducing the overall payable amount. |
| Due | Decimal | The remaining amount still owed, which is the 'Total' minus the 'Paid' and 'Credited' amounts. |
| DueLocal | Decimal | The amount still due, but converted into the organization's default currency. This field is used when the transaction involves multiple currencies. |
| TenantId | String | The unique identifier for the tenant, allowing you to query data for a specific tenant other than the default connection tenant. |
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| fromDate | Datetime | Filters and shows all payable invoices from the specified start date for the contact. This allows for date-based filtering on the results. |
| toDate | Datetime | Filters and shows all payable invoices up to the specified end date for the contact, allowing for a date range filter on the results. |
Queries the monthly balance sheet of a Xero organization. The balance sheet provides a snapshot of the organization's assets, liabilities, and equity at a given point in time.
| Name | Type | Description |
| ID [KEY] | Integer | The unique identifier for each row in the BalanceSheet report. This ID helps to distinguish each entry in the dataset. |
| Label1 | String | The label for the first item in the BalanceSheet report, typically representing a specific financial category or account. |
| Label2 | String | The corresponding value for the first label in the BalanceSheet report, representing the financial amount or balance associated with Label1. |
| Label3 | String | The label for the second item in the BalanceSheet report, typically representing a different financial category or account. |
| Label4 | String | The corresponding value for the second label in the BalanceSheet report, representing the financial amount or balance associated with Label3. |
| Label5 | String | The label for the third item in the BalanceSheet report, typically representing another financial category or account. |
| Label6 | String | The corresponding value for the third label in the BalanceSheet report, representing the financial amount or balance associated with Label5. |
| Label7 | String | The label for the fourth item in the BalanceSheet report, typically representing another financial category or account. |
| Label8 | String | The corresponding value for the fourth label in the BalanceSheet report, representing the financial amount or balance associated with Label7. |
| Label9 | String | The label for the fifth item in the BalanceSheet report, typically representing another financial category or account. |
| Label10 | String | The corresponding value for the fifth label in the BalanceSheet report, representing the financial amount or balance associated with Label9. |
| Label11 | String | The label for the sixth item in the BalanceSheet report, typically representing another financial category or account. |
| Label12 | String | The corresponding value for the sixth label in the BalanceSheet report, representing the financial amount or balance associated with Label11. |
| Label13 | String | The value associated with the thirteenth label in the BalanceSheet report, typically representing another financial metric. |
| AccountId | String | The unique identifier of the account associated with the row in the BalanceSheet report. This ID links the row to a specific account. |
| TenantId | String | The unique identifier for the tenant. This allows the system to query data specific to a tenant other than the default connection tenant, useful in multi-tenant environments. |
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| Date | Datetime | The 'as at' date, which represents the date the financial data in the report is accurate up to. It specifies the cut-off date for the report data. |
| Periods | Int | The number of periods to look back from the 'ToDate'. This helps define the timeframe for the data being analyzed, allowing for historical comparisons. |
| Timeframe | String | Defines the size of each period in the query. Valid values are 'MONTH', 'QUARTER', or 'YEAR', indicating whether each period should span a month, a quarter, or a year. |
| TrackingOptionID1 | String | A parameter that filters the report based on a specific tracking option, often used to display payable invoices or other filtered data for a contact. |
| TrackingOptionID2 | String | Another parameter for filtering the report based on a second tracking option, useful for narrowing down the data based on different criteria. |
| PaymentsOnly | Boolean | If the value is set to 'true', the query will only return data related to cash transactions, filtering out non-cash transactions for a more specific financial report. |
| StandardLayout | Boolean | If the value is set to 'true', the report will use the standard layout without applying any custom report layouts, ensuring a consistent output across all users. |
Queries the transactions listed on a particular bank account. It includes deposits, withdrawals, and other banking activities associated with the organization's accounts.
A bankAccountId may be provided when querying this view. If one is not given, then this report will be run for each bank account stored in Xero.
Note: To access bank statements, you must complete additional security requirements:
For more information and to complete these steps, reach out directly to Xero API support.
| Name | Type | Description |
| BankAccountId | String | The unique identifier for the bank account associated with the transaction. This ID links the transaction to a specific bank account. |
| Date | Date | The date on which the transaction occurred, indicating when the transaction was recorded in the bank account. |
| Description | String | A brief description of the transaction, which can include details such as the type of transaction, the party involved, or the purpose of the payment. |
| Reference | String | A reference value for the transaction, which could be a unique identifier, invoice number, or transaction ID used for tracking or linking to other records. |
| Reconciled | String | Indicates whether the transaction has been reconciled with the bank statement. Possible values are 'Yes' if reconciled, and 'No' if it has not yet been reconciled. |
| Source | String | The origin of the transaction, such as a bank deposit, transfer, payment, or withdrawal, providing context for where the transaction originated. |
| Amount | Decimal | The monetary value of the transaction, representing either the payment made or the deposit received in the bank account. |
| Balance | Decimal | The running balance of the account after the transaction has been applied. This reflects the total amount in the account after the transaction is processed. |
| TenantId | String | The unique identifier of the tenant, allowing the query to access data for a specific tenant rather than using the default connection tenant. |
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| fromDate | Date | The start date for the bank statement period, which is used to filter transactions from this specific date onward. |
| toDate | Date | The end date for the bank statement period. This date must be within 365 days from the 'fromDate' and is used to filter transactions up to this date. |
Displays a summary of balances and cash movements for each bank account in a Xero organization. It is useful for analyzing cash flow and understanding the financial status of bank accounts.
| Name | Type | Description |
| ID [KEY] | Integer | A unique identifier for the row, representing the sequential number of the record in the report. |
| BankAccount | String | The unique number assigned to the bank account. This number is used to identify the specific bank account associated with the financial data. |
| OpeningBalance | Decimal | The amount of funds in the account at the start of the financial period. This is the balance carried forward from the previous period. |
| CashReceived | Decimal | The total amount of money added to the account during the financial period, such as deposits, transfers, or other income. |
| CashSpent | Decimal | The total amount of money spent or withdrawn from the account during the financial period, including payments or transfers out of the account. |
| FXGain | Decimal | The changes in the account balance caused by fluctuations in exchange rates. This reflects the impact of currency conversion on the account balance during the period. |
| ClosingBalance | Decimal | The amount of funds in the account at the end of the financial period, calculated by taking the opening balance and adjusting for cash received, cash spent, and Foreign Exchange (FX) gain or loss. |
| TenantId | String | The unique identifier for the tenant, allowing queries to access data specific to a tenant rather than using the default connection tenant. |
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| toDate | Datetime | The starting date for the financial period or report. This is used to filter data starting from this date. |
| fromDate | Datetime | The closing date for the financial period or report. This date marks the end of the reporting period and is used to filter data up to this date. |
| PaymentsOnly | Boolean | If the value is set to 'true', the query will return only cash transactions, filtering out non-cash-related entries such as transfers or credits. |
Queries the branding themes defined for a Xero organization. Branding themes are used to customize the appearance of invoices, quotes, and other financial documents to align with the organization's branding.
The BrandingThemes view allows you to SELECT branding themes for a Xero organization.
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.
| Name | Type | Description |
| BrandingThemeId [KEY] | String | The unique identifier assigned by Xero to each branding theme. This ID links the branding theme to its corresponding record in the system. |
| Name | String | The name of the branding theme, which is used to identify and differentiate the theme in the system. This is typically a user-defined label for the theme. |
| SortOrder | Int | The ranking or order in which the branding theme appears relative to other themes. The default branding theme has a 'SortOrder' value of 0, indicating its precedence over other themes. |
| CreatedDateUTC | Datetime | The timestamp indicating when the branding theme was created. This timestamp is recorded in UTC and reflects the exact time the theme was added to the system. |
| TenantId | String | The unique identifier for the tenant, allowing queries to access data specific to a particular tenant, rather than using the default connection tenant. |
Queries the budget line items for a Xero organization. It allows users to track and manage detailed budget items within a larger financial plan.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the line item, which is a combination of the line item index and the account ID. This identifier helps to reference specific budget line items. |
| BudgetId | String | The unique identifier assigned by Xero to the budget. This ID links the budget line item to the overall budget record in the system. |
| AccountId | String | The ID of the account associated with this budget line item. This links the budget line to a specific account in the chart of accounts. |
| AccountCode | String | The code of the account associated with the budget line item. This is used for identification and to link the budget item to its corresponding account in financial records. |
| Period | String | The year and month that the budget applies to, representing the time period for which the budget amount is set. This typically follows the format 'YYYY-MM'. |
| Amount | Decimal | The amount allocated to the account for the specified period. This is the budgeted amount for the account during the given period. |
| Notes | String | Any additional notes or comments related to the budget line item. This field allows users to provide context or explanations for the budget entry. |
| TenantId | String | The unique identifier for the tenant, allowing the query to access data specific to a particular tenant rather than using the default connection tenant. |
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| DateFrom | Datetime | The start date for the budget period, indicating when the budget applies. This filters budget periods that begin from this date onward. |
| DateTo | Datetime | The end date for the budget period, indicating when the budget applies. This filters budget periods that end on or before this date. |
Queries budgets for a Xero organization. Budgets are used to track expected income and expenses over a specified period, providing valuable insight into financial performance.
| Name | Type | Description |
| BudgetId [KEY] | String | The unique identifier assigned by Xero to the budget. This ID links the budget to the overall budget record in the system, ensuring each budget entry is uniquely identifiable. |
| Type | String | The type of the budget, which can either be 'OVERALL' (representing the total budget for an account or entity) or 'TRACKING' (representing a budget related to a specific tracking category or option). |
| Description | String | A user-defined description of the budget, providing additional context about its purpose, scope, or any other relevant information. |
| TrackingCategory1_CategoryId | String | The unique identifier for the first tracking category associated with the budget. Tracking categories help to categorize and track financial data for reporting purposes. |
| TrackingCategory1_OptionId | String | The unique identifier for the option within the first tracking category. This ID links the budget entry to a specific option in the tracking category. |
| TrackingCategory1_Name | String | The name of the first tracking category. This provides a human-readable label for the category, making it easier to understand how the budget is categorized. |
| TrackingCategory1_Option | String | The value of the tracking category option within the first tracking category. This represents the specific selection made for that category, such as a department or cost center. |
| TrackingCategory2_CategoryId | String | The unique identifier for the second tracking category associated with the budget. This provides an additional level of categorization for more complex budgets. |
| TrackingCategory2_OptionId | String | The unique identifier for the option within the second tracking category. This ID links the budget entry to a specific option in the second tracking category. |
| TrackingCategory2_Name | String | The name of the second tracking category. Like 'TrackingCategory1_Name', this provides a human-readable label for the second category. |
| TrackingCategory2_Option | String | The value of the tracking category option within the second tracking category. This represents the specific selection made for the second category, such as a specific project or initiative. |
| UpdatedDateUTC | Datetime | The date and time, in UTC, when the budget was last updated. This timestamp is useful for tracking changes or modifications made to the budget. |
| TenantId | String | The unique identifier for the tenant, allowing queries to access data specific to a particular tenant rather than using the default connection tenant. This is important in multi-tenant environments. |
Provides a monthly summary of the organization's budget. It compares actual income and expenses against the budgeted amounts, helping organizations track their financial goals.
| Name | Type | Description |
| ID [KEY] | Integer | The unique identifier for each row in the report, typically representing a sequential index or row number. |
| BankAccount | String | The unique identifier for the bank account, often a code or number used to reference the specific account in the report. |
| Period1 | String | Represents the data for the first period of the report. This period could correspond to the first month, quarter, or year, depending on the report's time frame. |
| Period2 | String | Represents the data for the second period of the report, following the same time frame conventions as Period1. |
| Period3 | String | Represents the data for the third period of the report, providing a snapshot of the account or financial data for that specific time period. |
| Period4 | String | Represents the data for the fourth period of the report, continuing the same structure across all periods in the report. |
| Period5 | String | Represents the data for the fifth period of the report, maintaining consistency in how periods are displayed for financial analysis. |
| Period6 | String | Represents the data for the sixth period of the report, ensuring a comprehensive view across all periods for evaluation. |
| Period7 | String | Represents the data for the seventh period of the report, following the same structure for clarity and consistency. |
| Period8 | String | Represents the data for the eighth period of the report, providing an additional time frame for deeper financial analysis. |
| Period9 | String | Represents the data for the ninth period of the report, offering further insight into trends over multiple periods. |
| Period10 | String | Represents the data for the tenth period of the report, contributing to a more detailed view of the account's performance over time. |
| Period11 | String | Represents the data for the eleventh period of the report, allowing for extended period analysis and trends tracking. |
| Period12 | String | Represents the data for the twelfth period of the report, providing the final period of the analysis and a complete picture for the year. |
| TenantId | String | The unique identifier for the tenant, allowing queries to access data specific to a particular tenant rather than using the default connection tenant. Useful in multi-tenant environments. |
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| Date | Datetime | The 'as at' date for the report, marking the date when the financial data or account information is considered accurate and final. |
| Periods | Integer | The number of periods to compare in the report. This value must be an integer between 1 and 12, indicating how many periods are being analyzed or compared. |
| Timeframe | Integer | The size of each period in the comparison. Specify '1' for month, '3' for quarter, or '12' for year. This determines how the periods are grouped for comparison purposes. |
Queries Construction Industry Scheme (CIS) settings for contacts in a Xero organization. It is relevant for UK-based organizations involved in construction projects under the CIS tax regime.
| Name | Type | Description |
| ContactId [KEY] | String | The unique identifier assigned by Xero to the contact. This ID links the contact to their corresponding record in the system, ensuring they can be referenced uniquely. |
| CISEnabled | Boolean | Indicates whether the contact is currently classified as a CIS subcontractor. If the value is 'true', the contact is considered a CIS subcontractor for tax deduction purposes; if the value is 'false', they are not. |
| Rate | Int | The CIS deduction rate for the contact, expressed as a percentage. This rate determines the amount of tax that will be deducted from the subcontractor's payments under the CIS scheme. |
| TenantId | String | The unique identifier for the tenant. This allows the query to access data specific to a particular tenant rather than using the default connection tenant, especially in multi-tenant environments. |
Allows for querying credit note allocations within a Xero organization. Credit note allocations are used to match credit notes with invoices or payments.
| Name | Type | Description |
| Id [KEY] | String | Unique identifier for this specific credit note allocation entry. It is typically a composite of the credit note's ID and an allocation index, ensuring each allocation (especially if one credit note is applied to multiple invoices) can be uniquely identified and referenced. |
| CreditNoteId | String | Unique identifier of the credit note from which credit is being allocated. This internal ID (usually a GUID in Xero's system) links the allocation to a specific credit note record. It is used in Xero's internal system and in API calls, and is not usually visible to users. |
| Allocation_AppliedAmount | Decimal | The portion of the credit note's total amount that is applied to this particular invoice, reducing the invoice's outstanding balance by that same value. It indicates how much of the credit note was used on this invoice and decreases the remaining credit available on that credit note. |
| Allocation_Date | Date | The date on which the credit note was applied to the invoice. Xero typically sets this to the later of the credit note's date or the invoice's date, ensuring both the credit note and the invoice exist by that date. This date determines which accounting period the allocation falls into, thereby affecting when this credit application is reflected in financial reports. |
| Allocation_InvoiceId | String | Unique identifier of the invoice that the credit note is allocated to. This internal invoice ID links the allocation record to a specific invoice in Xero's system. It's used by the system and in API calls to ensure the credit is applied to the correct invoice, as opposed to using the human-readable invoice number. |
| Allocation_InvoiceNumber | String | The reference number of the invoice that received the credit note allocation. This is the user-facing invoice number (for example 'INV-1001') assigned to the invoice, which appears in Xero and on the invoice document. It provides an easily recognizable reference for the credited invoice, unlike the internal InvoiceId. |
| TenantId | String | The unique identifier of the Xero organization (tenant) associated with this record. In scenarios where multiple Xero organizations are connected, this ID specifies which tenant's data is being accessed. It ensures the credit allocation is recorded under the correct Xero company (organization). |
Queries the currencies used in a Xero organization, providing information on the organization's base currency as well as any additional currencies used for multi-currency transactions.
The Currencies table allows you to SELECT currencies for a Xero organization.
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.
| Name | Type | Description |
| Code [KEY] | String | The ISO 4217 currency code, which is a three-letter code that uniquely identifies a specific currency (for example, USD for US Dollar, EUR for Euro, GBP for British Pound). This code follows international standards for currency representation. |
| Description | String | A user-friendly name or label that identifies the currency. This description typically includes the name of the currency (for example, 'US Dollar', 'Euro') and may also include its symbol (for example, '$', '€') for better recognition. |
| TenantId | String | The unique identifier for the tenant, allowing the query to access data specific to a particular tenant rather than using the default connection tenant. This is important in multi-tenant environments where data is isolated between different tenants. |
Provides a summary of the changes between a given month and the previous month. It allows quick analysis of financial changes in income, expenses, and key performance indicators.
A date may be provided when querying this view. If it is not provided, then this report will compare the current month with the previous month.
| Name | Type | Description |
| Metric | String | The specific value or performance indicator that is being tracked and compared across time periods. This could represent a financial metric, sales figure, or any key performance indicator (KPI) relevant to the business. |
| ThisMonth | Decimal | The value of the metric for the current month. This represents the measurement of the metric for the most recent period (current month), allowing for analysis of the current performance. |
| PreviousMonth | Decimal | The value of the metric for the previous month. This represents the measurement of the metric for the month immediately preceding the current month, providing a point of comparison. |
| Variance | Decimal | The percentage difference between the current month's metric and the previous month's metric. This value indicates the relative change in the metric between the two periods, highlighting trends or fluctuations. |
| TenantId | String | The unique identifier for the tenant, allowing the query to access data specific to a particular tenant in a multi-tenant environment. This ensures that data is queried from the correct tenant's environment. |
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| date | Date | The date representing the current month being compared to the previous month. This field allows users to specify the month they want to analyze and compare against the previous month's data. |
Allows querying the payments made for expense claims within a Xero organization. It tracks reimbursements made to employees for work-related expenses.
The ExpenseClaimPayments view allows you to SELECT payments to different expense claims for a Xero organization. The Id column is generated by the Cloud; it combines the index of the line item with the unique, Xero-generated ExpenseClaimID.
Note that this table does not include other types of Payments - to retrieve those, you will need to read from the Payments table.
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.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the line item, combining the line item index with the Xero-generated identifier for the expense claim. This ensures that each payment can be uniquely identified in the system. |
| ExpenseClaimId | String | The unique identifier of the expense claim that this payment belongs to. This links the payment directly to a specific expense claim, allowing for proper tracking and reconciliation of expenses. |
| Date | Date | The date the payment is made. This field reflects when the payment was processed, and it is essential for tracking the timing of payments made against the expense claim. |
| Amount | Decimal | The amount of the payment being made. This value must be equal to or less than the outstanding balance owed on the expense claim, ensuring that payments do not exceed the amount owed. |
| Reference | String | An optional field for adding a reference or description for the payment. This could be used for internal tracking, such as invoice numbers or notes related to the payment. |
| AccountId | String | The unique identifier of the account used to make the payment. This account must be of type 'BANK' or have payments enabled, ensuring that funds can be properly allocated from the correct financial source. |
| AccountCode | String | The account code of the account from which the payment is made. This code is used to categorize the transaction in the financial system, ensuring the correct account is used. |
| AccountName | String | The name of the account used for the payment. This provides a human-readable label for the account, which can help users quickly identify the source of the payment. |
| TenantId | String | The unique identifier for the tenant. This allows queries to access data specific to a particular tenant in multi-tenant environments, ensuring the payment is recorded under the correct tenant's account. |
Allows for querying claimed receipts in Xero. It includes receipts submitted by employees for reimbursement under an expense claim.
The ExpenseClaimReceipts view allows you to SELECT claimed receipt line items for a Xero organization. The Id column is generated by the Cloud; it combines the index of the line item with the unique, Xero-generated ExpenseClaimID.
Note that this table does not include draft receipts - to retrieve those, you will need to read from the Receipts table.
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.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the line item, combining the line item index with the Xero-generated identifier for the expense claim. This ensures that each receipt is uniquely tracked and associated with the correct expense claim. |
| ExpenseClaimId | String | The unique identifier of the expense claim that this receipt belongs to. This field links the receipt to a specific expense claim, ensuring that the receipt is properly associated with the claim it supports. |
| ReceiptId | String | The unique Xero-generated identifier for the receipt. This ID is used to reference the specific receipt in the system and ensures that the receipt is distinguishable from others. |
| Date | Date | The date when the receipt was issued or received. This is crucial for accounting and reporting purposes, determining when the receipt's associated expense occurred. |
| Contact_ContactId | String | The unique identifier of the contact associated with the receipt. A contact must be specified when creating a receipt, linking the receipt to a specific customer or supplier. |
| Contact_Name | String | The name of the contact associated with the receipt. This provides a human-readable reference to the contact that the receipt pertains to. |
| LineItem_Description | String | The description of the item on the receipt. This typically includes details such as the goods or services purchased, providing context for the line item. |
| LineItem_UnitAmount | Decimal | The unit price for the item on the receipt. This is the cost per unit of the item, excluding tax, which is used to calculate the total line item amount. |
| LineItem_AccountCode | String | The account code for the associated account, categorizing the expense for financial reporting. The account code must be active and valid in the organization's chart of accounts. |
| LineItem_Quantity | Double | The quantity of the item purchased or billed in the line item. This must be a non-negative number, indicating how many units of the item are included in the transaction. |
| LineItem_TaxType | String | The tax type applied to the line item. This can be used to override the default tax rate for the account, ensuring that the appropriate tax is applied to the receipt line item. |
| LineItem_LineAmount | Decimal | The total value of the line item, calculated as 'UnitAmount x Quantity'. This represents the monetary value of the item before tax, but may include discounts if applicable. |
| LineItem_TrackingCategory1_CategoryId | String | The ID of the first tracking category associated with the line item. Xero allows for up to two optional tracking categories, which can be used for categorizing and reporting transactions. |
| LineItem_TrackingCategory1_CategoryName | String | The name of the first tracking category. This provides a label for the category, helping to identify how the line item is classified in reports. |
| LineItem_TrackingCategory1_OptionId | String | The ID of the option within the first tracking category. This links the line item to a specific option within the tracking category, providing additional classification for financial reporting. |
| LineItem_TrackingCategory1_OptionName | String | The name of the option selected within the first tracking category. This is the value associated with the option used to categorize the transaction. |
| LineItem_TrackingCategory1_Option_Stat | String | The status of the option selected within the first tracking category, indicating whether it is active or inactive for reporting purposes. |
| LineItem_TrackingCategory2_CategoryId | String | The ID of the second tracking category associated with the line item. Xero supports up to two tracking categories, allowing for additional classification of the line item. |
| LineItem_TrackingCategory2_CategoryName | String | The name of the second tracking category. This provides a label for the second level of categorization, which is used in conjunction with the first tracking category. |
| LineItem_TrackingCategory2_OptionId | String | The ID of the option selected within the second tracking category. This allows for further classification of the line item using a second tracking option. |
| LineItem_TrackingCategory2_OptionName | String | The name of the option selected within the second tracking category. This value helps to categorize the line item for more detailed financial analysis. |
| LineItem_TrackingCategory2_Option_Stat | String | The status of the option selected within the second tracking category, indicating whether it is active or inactive for reporting purposes. |
| LineItem_DiscountRate | Double | The discount percentage applied to the line item. This rate reduces the total value of the line item, allowing for customized discounting of receipts. |
| User_UserId | String | The unique identifier of the user within the organization who the expense claim receipt is for. This helps track who the receipt pertains to within the organization. |
| Reference | String | An optional field for adding a reference number or description related to the receipt. This field can be used for additional internal tracking or identification purposes. |
| LineAmountTypes | String | Specifies whether line amounts include tax. The valid values are 'Exclusive' (tax excluded), 'Inclusive' (tax included), or 'NoTax' (no tax applied). If not specified, line amounts are considered to exclude tax by default. |
| SubTotal | Decimal | The total amount of the receipt, excluding taxes. This is the sum of the 'LineItem_LineAmount' for all line items before tax is applied. |
| TotalTax | Decimal | The total tax applied to the receipt. This is calculated based on the applicable tax rate for each line item, indicating how much tax was charged. |
| Total | Decimal | The total value of the receipt, which is the sum of 'SubTotal' and 'TotalTax', representing the final amount of the receipt after tax. |
| Status | String | The current status of the receipt. Valid values include 'DRAFT' (unapproved), 'SUBMITTED' (submitted for approval), 'AUTHORiSED' (approved), and 'DECLINED' (rejected or voided). |
| ReceiptNumber | String | The Xero-generated number assigned to the receipt. This number helps track and uniquely identify the receipt within the system for the specific expense claim. |
| UpdatedDateUTC | Datetime | The date and time, in UTC, when the receipt was last updated in the system. This timestamp reflects any changes made to the receipt after its creation. |
| HasAttachments | Boolean | Indicates whether the receipt has any attachments, such as scanned receipts or supporting documents, linked to it in Xero. |
| URL | String | A link to an external source document associated with the receipt, such as a scanned image or other supporting files stored outside of Xero. |
| TenantId | String | The unique identifier for the tenant. This allows the query to access data specific to a particular tenant in multi-tenant environments, ensuring data isolation between tenants. |
Tracks the history and notes for bank transfers within a Xero organization. It provides insights into past transfers between accounts.
The HistoryBankTransfers view allows you to read the notes created on a transfer, and the history of changes to that transfer. If a BankTransferId is not provided, the history of all BankTransfers will be retrieved.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures that each history item is uniquely identifiable within the log. |
| BankTransferId | String | The unique identifier of the bank transfer to which this history item is related. This field links the history entry to a specific bank transfer record, allowing users to track changes made to that transfer. |
| Changes | String | Describes the type of change that occurred on the bank transfer. This could include updates such as modifications to the transfer amount, sender/receiver details, date, or status, providing context for what was changed. |
| Date | Datetime | The timestamp indicating when the change occurred. This field records the exact date and time that the change was made, creating a chronological record of modifications to the bank transfer. |
| User | String | The name of the user who made the change. This field identifies the person responsible for modifying the bank transfer, ensuring accountability and tracking within the system. |
| Details | String | A detailed description of the specific change made. This field provides clear information on what exactly was altered in the bank transfer, offering transparency regarding the modifications. |
| TenantId | String | The unique identifier for the tenant. This ensures that the query is specific to a particular tenant in a multi-tenant environment, ensuring that the history item belongs to the correct tenant's records. |
Queries the history and notes of expense claims in Xero. This helps track all past activities related to employee expense reimbursements.
The HistoryExpenseClaims view allows you to read the notes created on a expense claim, and the history of changes to that expense claim. If a ExpenseClaimId is not provided, the history of all ExpenseClaims will be retrieved.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures that each history entry is distinctly identifiable and provides accurate tracking of changes over time. |
| ExpenseClaimId | String | The unique identifier of the expense claim to which this history item belongs. This field links the history entry to a specific expense claim, helping to track changes made to the claim. |
| Changes | String | Describes the type of change that occurred on the expense claim. This could include updates such as changes to the claim's status, amounts, or attached receipts, providing insight into the nature of the modification. |
| Date | Datetime | The exact timestamp of when the change occurred. This field records the time when the change was made, allowing for chronological tracking of modifications to the expense claim. |
| User | String | The name of the user who made the change. This field identifies the person responsible for altering the expense claim, ensuring accountability and transparency in the system. |
| Details | String | A detailed description of the specific change made to the expense claim. This could include specifics such as changes in the claim's amount, new receipts attached, or adjustments made to the claim. |
| TenantId | String | The unique identifier of the tenant. This ensures the query retrieves data specific to a particular tenant, which is important in multi-tenant environments where each tenant's data is isolated from others. |
Used to query the history and notes of items (products or services) within a Xero organization. This tracks changes and updates made to items used in transactions.
The HistoryItems view allows you to read the notes created on a item, and the history of changes to that item. If a ItemId is not provided, the history of all Items will be retrieved.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures each entry is distinctly identifiable, allowing accurate tracking of changes over time. |
| ItemId | String | The unique identifier of the item that this history entry belongs to. This links the history item to a specific record, such as an invoice, order, or product, ensuring that changes are tracked at the item level. |
| Changes | String | Describes the type of change that occurred on the item. This could include modifications such as updates to the item's details, quantity, price, or status, providing context on the nature of the change. |
| Date | Datetime | The exact timestamp when the change occurred. This field captures the time at which the modification was made, providing a clear timeline of updates to the item. |
| User | String | The name of the user who made the change. This field identifies the individual responsible for modifying the item, ensuring accountability and traceability in the system. |
| Details | String | A detailed description of the specific change that was made. This provides clarity on what exactly was altered, such as which fields were modified and how, offering transparency into the update process. |
| TenantId | String | The unique identifier of the tenant. This ensures the query retrieves data specific to a particular tenant in multi-tenant environments, ensuring proper isolation of data between tenants. |
Used to query the history and notes of overpayments in Xero. Overpayments occur when a customer pays more than the amount due.
The HistoryOverpayments view allows you to read the notes created on a overpayment, and the history of changes to that overpayment. If a OverpaymentId is not provided, the history of all Overpayments will be retrieved.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures each entry is distinctly identifiable, enabling accurate tracking of changes over time. |
| OverpaymentId | String | The unique identifier of the overpayment that this history item belongs to. This field links the history item to a specific overpayment record, ensuring changes to overpayments can be traced and monitored. |
| Changes | String | Describes the type of change that occurred on the overpayment. This could include modifications such as changes to the overpayment amount, status, or related transaction details, providing insight into the nature of the modification. |
| Date | Datetime | The timestamp when the change occurred. This field records the exact time the modification was made, providing a clear timeline of updates to the overpayment. |
| User | String | The name of the user who made the change. This field identifies the individual responsible for altering the overpayment, ensuring accountability for updates in the system. |
| Details | String | A detailed description of the specific change that was made to the overpayment. This provides further context about what was modified, such as updated amounts, statuses, or other relevant changes. |
| TenantId | String | The unique identifier of the tenant. This ensures the query retrieves data specific to a particular tenant in multi-tenant environments, ensuring proper data isolation between tenants. |
Queries the payment history and notes for a Xero organization. It helps track the details of payments made to suppliers or received from customers.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures that each history entry is distinctly identifiable, providing an accurate record of changes over time. |
| PaymentId | String | The unique identifier of the payment to which this history item belongs. This links the history entry to a specific payment record, enabling tracking of changes made to that particular payment. |
| Changes | String | Describes the type of change that occurred on the payment. This could include updates such as changes to the payment amount, status, or the method of payment, providing clarity on what was modified. |
| Date | Datetime | The exact timestamp when the change occurred. This field captures the time the modification was made, ensuring a clear and chronological record of changes to the payment. |
| User | String | The name of the user who made the change. This identifies the person responsible for modifying the payment, ensuring accountability and traceability in the system. |
| Details | String | A detailed description of the specific change that was made to the payment. This includes details such as which fields were updated and how, providing transparency into the changes. |
| TenantId | String | The unique identifier of the tenant. This ensures the query accesses data specific to a particular tenant in multi-tenant environments, ensuring that the correct data for the right tenant is retrieved. |
Queries the history and notes of prepayments. Prepayments refer to amounts paid in advance for goods or services.
The HistoryPrepayments view allows you to read the notes created on a prepayment, and the history of changes to that prepayment. If a PrepaymentId is not provided, the history of all Prepayments will be retrieved.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures each history entry is distinctly identifiable and allows accurate tracking of changes over time. |
| PrepaymentId | String | The unique identifier of the prepayment to which this history item belongs. This field links the history entry to a specific prepayment, enabling the tracking of changes made to that prepayment. |
| Changes | String | Describes the type of change that occurred on the prepayment. This could include modifications such as changes to the prepayment amount, status, allocation, or related details. |
| Date | Datetime | The timestamp of when the change occurred. This field records the exact time the modification was made, allowing for precise chronological tracking of changes to the prepayment. |
| User | String | The name of the user who made the change. This identifies the individual responsible for modifying the prepayment, ensuring accountability for the updates made. |
| Details | String | A detailed description of the specific change that was made to the prepayment. This includes details such as the modified amount, new status, or other relevant updates, providing transparency into the change process. |
| TenantId | String | The unique identifier of the tenant. This ensures the query retrieves data specific to a particular tenant, ensuring proper isolation of data in multi-tenant environments. |
Tracks the history and notes of receipts within Xero. Receipts confirm payments received by the organization.
The HistoryReceipts view allows you to read the notes created on a receipt, and the history of changes to that receipt. If a ReceiptId is not provided, the history of all Receipts will be retrieved.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures each history entry is distinctly identifiable, allowing for accurate tracking of changes made to the receipt. |
| ReceiptId | String | The unique identifier of the receipt to which this history item belongs. This links the history entry to a specific receipt, ensuring changes made to that receipt are clearly tracked. |
| Changes | String | Describes the type of change that occurred on the receipt. This could include updates to the receipt amount, status, items, or payment details, providing insight into the nature of the modification. |
| Date | Datetime | The timestamp when the change occurred. This field captures the exact time of the modification, ensuring a clear chronological record of changes to the receipt. |
| User | String | The name of the user who made the change. This identifies the individual responsible for modifying the receipt, ensuring accountability and transparency in the system. |
| Details | String | A detailed description of the specific change made to the receipt. This includes what was altered in the receipt, such as adjustments to the amount, items, or any other details that were modified. |
| TenantId | String | The unique identifier of the tenant. This ensures that the query retrieves data specific to a particular tenant in multi-tenant environments, isolating the changes to the correct tenant's data. |
Queries the history and notes of repeating invoices in Xero. Repeating invoices are generated automatically for recurring billing.
The HistoryRepeatingInvoices view allows you to read the notes created on a repeating invoice, and the history of changes to that repeating invoice. If a RepeatingInvoiceId is not provided, the history of all RepeatingInvoices will be retrieved.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the history item, combining its position in the history log with the timestamp of when the change occurred. This ensures each history entry is distinctly identifiable, allowing accurate tracking of changes over time. |
| RepeatingInvoiceId | String | The unique identifier of the repeating invoice to which this history item belongs. This links the history entry to a specific repeating invoice, ensuring changes made to that invoice are easily traced. |
| Changes | String | Describes the type of change that occurred on the repeating invoice. This could include modifications to the invoice amount, frequency, billing details, or other related attributes, providing insight into the nature of the change. |
| Date | Datetime | The exact timestamp when the change occurred. This field records the time of modification, ensuring a clear chronological history of changes made to the repeating invoice. |
| User | String | The name of the user who made the change. This field identifies the individual responsible for altering the repeating invoice, ensuring accountability for updates. |
| Details | String | A detailed description of the specific change made to the repeating invoice. This includes specifics such as which fields were updated, like invoice amounts, billing cycle adjustments, or any other modifications. |
| TenantId | String | The unique identifier of the tenant. This ensures the query accesses data specific to a particular tenant, especially in multi-tenant environments where each tenant's data is isolated from others. |
Used for querying line items in journals. Journals in Xero are used to record debits and credits for financial transactions.
The Journals view allows you to SELECT the journal lines in journals for a Xero organization. The Id column is generated by the Cloud; this value combines the index of the line item with the unique, Xero-generated JournalId.
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 Journals view has a high volume threshold of 100. The Xero API does not list any optimized filters for this view.
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.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the journal line, combining its position in the history log with the Xero-generated identifier of the journal. This ensures each journal entry is distinctly identifiable, enabling accurate tracking of changes. |
| JournalId | String | The unique identifier assigned by Xero to the journal. This field links the journal line to a specific journal entry, making it easier to track the source of the transaction. |
| JournalDate | Date | The date the journal was posted. This field indicates when the journal entry was officially recorded in Xero, providing a timestamp for when the financial action took place. |
| JournalNumber | Integer | The unique journal number assigned by Xero. This value helps identify and reference the journal for internal tracking purposes. |
| CreatedDateUTC | Datetime | The timestamp when the journal was entered into the system. This field indicates when the journal entry was initially created, which may differ from the journal posting date. |
| Reference | String | An optional reference value that provides additional context or identification for the journal entry. This is often used for cross-referencing within internal systems or reports. |
| SourceId | String | The identifier for the source transaction that generated the journal entry. For example, it could be an 'InvoiceId' or another reference that links the journal to a specific transaction. |
| SourceType | String | The type of the transaction that created the journal. Valid values include 'ACCREC', 'ACCPAY', 'ACCRECCREDIT', indicating the type of financial action (for example, sales or purchase). |
| JournalLine_JournalLineId | String | The unique identifier for the journal line item within the journal entry. This ID is generated by Xero and helps to track individual lines within a journal. |
| JournalLine_Description | String | A description of the journal line item, providing context for the transaction recorded in that line (for example, description of services or goods purchased). |
| JournalLine_AccountId | String | The account associated with the journal line item. This links the journal entry to a specific account in the organization's chart of accounts. |
| JournalLine_AccountCode | String | The customer-defined alphanumeric code for the account. For example, '200' or 'SALES'. This field helps identify which account the transaction is recorded under. |
| JournalLine_AccountType | String | The type of account associated with the journal line. Possible values include 'BANK', 'CURRENT', or 'CRRLIAB', indicating the account's classification within the general ledger. |
| JournalLine_AccountName | String | The name of the account associated with the journal line. This field provides a more descriptive label for the account (for example, 'Cash' or 'Accounts Receivable'). |
| JournalLine_NetAmount | Decimal | The net amount of the journal line item, representing the transaction amount before tax. This value is positive for debits and negative for credits. |
| JournalLine_GrossAmount | Decimal | The total amount of the journal line item, including the tax amount. This represents the full amount of the transaction after tax has been applied. |
| JournalLine_TaxAmount | Decimal | The total tax amount applied to the journal line, based on the applicable tax rate for the transaction. |
| JournalLine_TaxType | String | The tax rate applied to the journal line item. This field defines the specific tax treatment for the transaction, such as 'TAX001', 'TAX002', or other user-defined tax codes. |
| JournalLine_TaxName | String | The name associated with the tax type applied to the journal line item. This provides more descriptive context for the specific tax rate being used (for example, 'Standard VAT'). |
| LineItem_TrackingCategory1_CategoryId | String | The ID of the first tracking category associated with the journal line item. Xero allows two optional tracking categories to be defined for detailed reporting. |
| LineItem_TrackingCategory1_CategoryName | String | The name of the first tracking category. This helps categorize the journal line item for reporting and analysis based on internal classifications. |
| LineItem_TrackingCategory1_OptionId | String | The ID of the selected option within the first tracking category. This specifies which option within the category the journal line item belongs to. |
| LineItem_TrackingCategory1_OptionName | String | The name of the selected option within the first tracking category. This provides more detail about how the journal line item is classified. |
| LineItem_TrackingCategory1_Option_Stat | String | The status of the first tracking category option. This indicates whether the tracking option is active, inactive, or in some other status for reporting purposes. |
| LineItem_TrackingCategory2_CategoryId | String | The ID of the second tracking category for the journal line item. Like the first category, this allows further categorization of the item for reporting. |
| LineItem_TrackingCategory2_CategoryName | String | The name of the second tracking category. This provides a label for the second category used to classify the journal line item. |
| LineItem_TrackingCategory2_OptionId | String | The ID of the selected option within the second tracking category. This helps specify the option that the journal line item is classified under. |
| LineItem_TrackingCategory2_OptionName | String | The name of the selected option within the second tracking category. This gives more context about how the journal line item is categorized. |
| LineItem_TrackingCategory2_Option_Stat | String | The status of the second tracking category option. This indicates whether the second tracking option is active, inactive, or in another status. |
| TenantId | String | The unique identifier for the tenant. This ensures that the query retrieves data specific to a particular tenant in multi-tenant environments, ensuring proper isolation of data. |
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| ModifiedAfter | String | If set, only journals created or modified since this timestamp will be returned (for example, '2009-11-12T00:00:00'). This filter helps retrieve recent data for reporting or updates. |
| PaymentsOnly | Boolean | Set this to 'true' to retrieve only cash-based transactions (for example, payments) from the journal entries. This helps narrow down the results to specific types of transactions. |
| Offset | Int | If provided, only journals with a higher 'JournalNumber' will be returned. This filter helps paginate large result sets by skipping to a specific point in the journal entries. |
Used to query general organization data in Xero, including company details, settings, and configurations.
The organization view allows you to SELECT organization data for a Xero organization.
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.
| Name | Type | Description |
| ShortCode [KEY] | String | A unique identifier assigned to the organisation within Xero. This code is used to uniquely reference the organisation in Xero's system. |
| APIKey | String | A unique API key that facilitates Xero-to-Xero transactions. This key is used to authenticate and authorize communication between Xero organizations. |
| Name | String | The display name of the organisation as shown in the Xero interface. This is typically the official name used for identification. |
| LegalName | String | The legal name of the organisation, as it appears on official reports and documents. |
| PaysTax | Boolean | Indicates whether the organisation is registered with a local tax authority. If the value is 'true', the organisation is subject to tax regulations. |
| Version | String | The version of Xero used by the organisation. This is helpful for compatibility and support, as different versions may have different features. |
| BaseCurrency | String | The default currency used by the organisation in Xero. This currency is applied to all financial transactions unless otherwise specified. |
| CountryCode | String | The country code associated with the organisation. This is typically a two-letter ISO country code (for example, 'US', 'NZ', and 'GB'). |
| IsDemoCompany | String | Indicates whether the organisation is a demo company. 'True' means the organisation is a demo for testing, training, or evaluation purposes. |
| OrganisationStatus | String | The status of the organisation within Xero. It is set to 'ACTIVE' if you can connect to the organisation via the Xero API, otherwise, it will reflect other statuses like 'INACTIVE' or 'ARCHIVED'. |
| RegistrationNumber | String | The registration number for the organisation, applicable for NZ, AU, and UK organisations. This is a legal identifier used for tax and compliance purposes. |
| TaxNumber | String | The tax identification number of the organisation, such as 'ABN' (Australia), 'GST number' (New Zealand), 'VAT number' (UK), or equivalent based on the country. |
| FinancialYearEndDay | String | The day of the year on which the organisation's financial year ends. For example, '31' represents the last day of the year. |
| FinancialYearEndMonth | String | The month of the year on which the organisation's financial year ends. For example, '12' represents December. |
| PeriodLockDate | Date | The date when the organisation locks the period for accounting purposes. This prevents changes to financial data after this date. |
| EndOfYearLockDate | Date | The date when the organisation locks the end of the financial year, preventing modifications to financial data for the completed year. |
| CreatedDateUTC | Datetime | The timestamp indicating when the organisation was created in Xero. This helps track when the organisation was set up in the system. |
| UpdatedDateUTC | Datetime | The timestamp indicating when the organisation details were last updated. This helps track changes to the organisation's data. |
| OrganisationEntityType | String | The entity type of the organisation. Common entity types include 'COMPANY' and 'SOLEPROPRIETOR', and indicate the legal structure of the business. |
| Timezone | String | The time zone for the organisation, specified in IANA time zone format (for example, 'America/New_York' and 'Europe/London'). |
| Edition | String | The edition of Xero used by the organisation. Possible values are 'BUSINESS' for standard Xero users and 'PARTNER' for users with restricted functionality in the Xero partner program. |
| Class | String | The subscription class of the organisation, such as 'DEMO', 'TRIAL', 'STARTER', 'STANDARD', 'PREMIUM', or specific premium tiers like 'PREMIUM_20', 'PREMIUM_50' It defines the plan or tier the organisation is subscribed to. |
| LineOfBusiness | String | A description of the business type or industry of the organisation. This provides insight into the nature of the organisation's operations. |
| Street_AddressLine1 | String | The first line of the street address for the organisation's physical location. |
| Street_AddressLine2 | String | The second line of the street address for the organisation's physical location. |
| Street_AddressLine3 | String | The third line of the street address for the organisation's physical location. |
| Street_AddressLine4 | String | The fourth line of the street address for the organisation's physical location. |
| Street_City | String | The city in which the organisation is located. |
| Street_PostalCode | String | The postal code for the organisation's physical location. |
| Street_Country | String | The country in which the organisation is located, specified by its full name (for example, 'United States' or 'New Zealand'). |
| Street_Region | String | The region or state in which the organisation is located. |
| Street_AttentionTo | String | An attention-to line for the street address, used for specific recipients or departments. |
| POBox_AddressLine1 | String | The first line of the PO box address for the organisation. |
| POBox_AddressLine2 | String | The second line of the PO box address for the organisation. |
| POBox_AddressLine3 | String | The third line of the PO box address for the organisation. |
| POBox_AddressLine4 | String | The fourth line of the PO box address for the organisation. |
| POBox_City | String | The city for the PO box address. |
| POBox_PostalCode | String | The postal code for the PO box address. |
| POBox_Country | String | The country for the PO box address. |
| POBox_Region | String | The region or state for the PO box address. |
| POBox_AttentionTo | String | An attention-to line for the PO box address, used for specific recipients or departments. |
| DDI_PhoneNumber | String | The direct dial-in (DDI) phone number of the organisation, without area or country code. |
| DDI_PhoneAreaCode | String | The area code for the organisation's DDI phone number. |
| DDI_PhoneCountryCode | String | The country code for the organisation's DDI phone number. |
| Default_PhoneNumber | String | The default phone number for the organisation, without area or country code. |
| Default_PhoneAreaCode | String | The area code for the organisation's default phone number. |
| Default_PhoneCountryCode | String | The country code for the organisation's default phone number. |
| Fax_PhoneNumber | String | The fax phone number for the organisation, without area or country code. |
| Fax_PhoneAreaCode | String | The area code for the organisation's fax phone number. |
| Fax_PhoneCountryCode | String | The country code for the organisation's fax phone number. |
| Mobile_PhoneNumber | String | The mobile phone number for the organisation, without area or country code. |
| Mobile_PhoneAreaCode | String | The area code for the organisation's mobile phone number. |
| Mobile_PhoneCountryCode | String | The country code for the organisation's mobile phone number. |
| Facebook_URL | String | The URL to the organisation's Facebook page, providing direct access to its social media profile. |
| Twitter_URL | String | The URL to the organisation's Twitter page, providing direct access to its social media profile. |
| GooglePlus_URL | String | The URL to the organisation's Google Plus page, providing direct access to its social media profile. |
| LinkedIn_URL | String | The URL to the organisation's LinkedIn page, providing direct access to its professional networking profile. |
| Website_URL | String | The URL to the organisation's official website, providing direct access to more information about the organisation. |
| PaymentTerms_Bills_Day | String | The default number of days for payment terms on bills. This value determines how many days after the invoice date the payment is due. |
| PaymentTerms_Bills_Type | String | The default payment terms for bills. The type specifies whether the payment terms are based on a certain number of days, weeks, or other units. |
| PaymentTerms_Sales_Day | String | The default number of days for payment terms on sales invoices. This value determines how many days after the invoice date the payment is due. |
| PaymentTerms_Sales_Type | String | The default payment terms for sales invoices. The type specifies whether the payment terms are based on a certain number of days, weeks, or other units. |
| TenantId | String | The unique identifier of the tenant. This ensures that queries are scoped correctly, particularly in multi-tenant environments where data must be isolated for different organisations. |
Used to query the actions performed on a Xero organization. This includes tax filings, internal reports, and administrative changes.
| Name | Type | Description |
| Name [KEY] | String | The name of the permission associated with the app. This field identifies the specific action or capability being granted to the app (for example, 'Read', 'Write', 'Delete'). |
| Status | Bool | Indicates whether the action is permitted for the app. A value of 'true' means the app is allowed to perform the action, while 'false' means the action is not permitted. |
| TenantId | String | The unique identifier of the tenant. This ensures the query retrieves data specific to a particular tenant in multi-tenant environments, ensuring data isolation and proper access control. |
Used to query the allocation of overpayments within Xero. This helps track excess payments made by customers and how they are applied to outstanding invoices.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the allocation, combining the allocation index and the Xero-generated identifier for the overpayment. This ensures the allocation can be distinctly tracked. |
| OverpaymentId | String | The unique identifier for the overpayment. This links the allocation to a specific overpayment transaction in Xero. |
| Allocation_AppliedAmount | Decimal | The amount of the overpayment to be applied to a specific invoice. This field shows how much of the overpayment is being allocated toward settling the invoice balance. |
| Allocation_Date | Date | The date when the allocation was made. This indicates when the overpayment was applied to the invoice, helping track payment history. |
| Allocation_InvoiceId | String | The identifier of the invoice to which the overpayment is applied. This links the allocation to the specific invoice that is being settled. |
| Allocation_InvoiceNumber | String | The invoice number associated with the allocation. This field provides a reference to the invoice being credited with the overpayment. |
| TenantId | String | The unique identifier for the tenant. This ensures the query retrieves data specific to a particular tenant, especially in multi-tenant environments, ensuring proper data isolation. |
Used to query overpayments made within a Xero organization. This helps manage and apply payments that exceed the amount owed.
| Name | Type | Description |
| OverpaymentId [KEY] | String | The unique identifier for the overpayment transaction in Xero. This ID is used to link the overpayment to related transactions and for tracking within the system. |
| Date | Date | The date when the overpayment was made. This field tracks the actual payment date and is essential for financial record-keeping. |
| Type | String | The type of the overpayment transaction. Valid values include 'RECEIVE-OVERPAYMENT' (payments received in excess) and 'SPEND-OVERPAYMENT' (overpayments made during a purchase). |
| RemainingCredit | Decimal | The remaining credit balance on the overpayment. This field helps track how much of the overpayment is still available to apply to other invoices or transactions. |
| Contact_ContactId | String | The identifier for the contact associated with the overpayment. This links the overpayment to the specific customer or supplier involved in the transaction. |
| Contact_Name | String | The name of the contact associated with the overpayment. This provides the necessary reference to identify the party involved in the overpayment. |
| Status | String | The current status of the overpayment. Valid status values include 'AUTHORISED', 'PAID', and 'VOIDED', reflecting whether the overpayment has been approved, paid, or canceled. |
| SubTotal | Decimal | The subtotal for the overpayment, excluding taxes. This represents the value of the overpayment before taxes are applied. |
| TotalTax | Decimal | The total tax amount on the overpayment. This is calculated based on the applicable tax rates and included in the overall total of the overpayment. |
| Total | Decimal | The total amount of the overpayment, including tax. This is the sum of 'SubTotal' and 'TotalTax', representing the full value of the overpayment. |
| LineItem_LineItemId | String | The unique Xero identifier for a line item within the overpayment. This links the overpayment to specific line items for detailed tracking. |
| LineItem_Description | String | The description of the line item for the overpayment. This field provides details about the item or service being paid for, helping users understand the overpayment breakdown. |
| LineItem_Quantity | Double | The quantity of the associated item in the line item. This field specifies how much of the item is being paid for in the overpayment transaction. |
| LineItem_UnitAmount | Decimal | The unit price of the associated item in the line item. This value helps determine the total cost for the item, which is used to calculate the overpayment amount. |
| LineItem_ItemCode | String | The code that identifies the associated item in the line item. This is used to reference inventory or services that the overpayment applies to. |
| LineItem_AccountCode | String | The account code used for the line item. The account must be active for the organisation and is necessary for the invoice approval process. |
| LineItem_TaxType | String | The tax type applied to the line item. This field allows overriding the default tax code for the selected account, enabling more accurate tax reporting. |
| LineItem_TaxAmount | Decimal | The calculated tax amount for the line item. This is derived based on the tax type and is included in the total tax amount of the overpayment. |
| LineItem_LineAmount | Decimal | The total amount for the line item, including any quantity multiplied by the unit price with applicable discounts or adjustments. |
| LineItem_TrackingCategory1_CategoryId | String | The ID of the first tracking category associated with the line item. Tracking categories help with additional reporting and categorization of expenses. |
| LineItem_TrackingCategory1_CategoryName | String | The name of the first tracking category. This further categorizes the line item for reporting purposes. |
| LineItem_TrackingCategory1_OptionId | String | The ID of the option within the first tracking category. This allows for further granularity in tracking and reporting. |
| LineItem_TrackingCategory1_OptionName | String | The name of the option selected for the first tracking category. This helps specify the exact category option the line item is associated with. |
| LineItem_TrackingCategory1_Option_Stat | String | The status of the option within the first tracking category. It indicates whether the option is active or inactive for reporting. |
| LineItem_TrackingCategory2_CategoryId | String | The ID of the second tracking category. This allows a second level of categorization for the line item. |
| LineItem_TrackingCategory2_CategoryName | String | The name of the second tracking category. This enables more detailed reporting and categorization of expenses. |
| LineItem_TrackingCategory2_OptionId | String | The ID of the option within the second tracking category. This helps further refine the classification of the line item. |
| LineItem_TrackingCategory2_OptionName | String | The name of the option selected for the second tracking category. This further defines the line item's categorization. |
| LineItem_TrackingCategory2_Option_Stat | String | The status of the option within the second tracking category. It reflects whether the option is currently active or inactive. |
| LineItem_DiscountRate | Double | The percentage discount applied to the line item. This is only applicable to 'ACCREC' (sales) invoices, and it reduces the total amount due. |
| LineAmountTypes | String | Specifies the line amount type for the overpayment. The valid values are 'Exclusive' (tax is excluded), 'Inclusive' (tax is included), and 'NoTax' (no tax is applied). |
| CurrencyCode | String | The ISO 4217 currency code for the overpayment. This identifies the currency used for the transaction (for example, 'USD' or 'EUR'). |
| CurrencyRate | String | The currency exchange rate for a multicurrency overpayment. If not specified, the XE.com daily rate is used as the default. |
| UpdatedDateUTC | Datetime | The timestamp when the overpayment was last updated. This ensures that the data is current and reflects the latest changes. |
| Allocation1_AppliedAmount | Decimal | The amount of the overpayment applied to a specific invoice. This is part of the allocation process, where the overpayment is applied to outstanding invoices. |
| Allocation1_Date | Date | The date when the overpayment was applied to the invoice. This helps track the timing of the allocation. |
| Allocation1_InvoiceId | String | The unique identifier of the invoice to which the overpayment has been applied. This links the overpayment to a specific invoice. |
| Allocation1_InvoiceNumber | String | The invoice number associated with the allocation. This provides a reference to the invoice receiving the overpayment. |
| Allocation2_AppliedAmount | Decimal | The amount of the overpayment applied to another invoice. This is part of a second allocation, if applicable. |
| Allocation2_Date | Date | The date the second allocation was made. |
| Allocation2_InvoiceId | String | The identifier of the second invoice to which the overpayment has been applied. |
| Allocation2_InvoiceNumber | String | The invoice number for the second invoice receiving the overpayment. |
| PaymentIds | String | A comma-delimited list of payment IDs associated with the overpayment. This tracks the payments that are linked to the overpayment. |
| HasAttachments | Boolean | Indicates whether the overpayment has any attachments, such as receipts or supporting documents. This field helps identify overpayments with additional documentation. |
| TenantId | String | The unique identifier of the tenant. This ensures the query retrieves data specific to a particular tenant in multi-tenant environments. |
Used to query prepayment allocations. Prepayments are amounts paid in advance but not yet invoiced, and this view helps manage their application.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier for the allocation, combining the allocation index and the Xero-generated identifier for the prepayment. This helps track the specific allocation transaction. |
| PrepaymentId | String | The unique identifier for the prepayment transaction. This links the allocation to the specific prepayment made by the customer or supplier. |
| Allocation_AppliedAmount | Decimal | The amount from the prepayment being applied to a specific invoice. This shows how much of the prepayment is being used to settle the invoice balance. |
| Allocation_Date | Date | The date when the allocation was made. This field records when the prepayment was applied to the invoice, helping to track payment history. |
| Allocation_InvoiceId | String | The identifier of the invoice to which the prepayment has been applied. This links the allocation to the specific invoice that is being paid. |
| Allocation_InvoiceNumber | String | The invoice number associated with the allocation. This field provides a reference to the invoice receiving the prepayment. |
| TenantId | String | The unique identifier for the tenant. This ensures the query retrieves data specific to a particular tenant in a multi-tenant environment, maintaining data isolation and access control. |
Used to query prepayment records. Prepayments refer to money paid before goods or services are received.
| Name | Type | Description |
| PrepaymentId [KEY] | String | The unique identifier for the prepayment transaction. This ID links the prepayment to related transactions and helps in tracking it within the system. |
| Date | Date | The date when the prepayment was made. This is essential for recording the transaction date and helps with financial record-keeping. |
| Reference | String | An optional reference or description for the prepayment. This can be used to provide additional context or notes related to the prepayment transaction. |
| Type | String | The type of the prepayment. Valid values include 'RECEIVE-PREPAYMENT' (payment received in advance) and 'SPEND-PREPAYMENT' (advance payment made for a purchase). |
| RemainingCredit | Decimal | The remaining credit balance on the prepayment. This value shows how much of the prepayment is still available to be applied to future invoices. |
| Contact_ContactId | String | The identifier for the contact associated with the prepayment. This links the prepayment to a specific customer or supplier. |
| Contact_Name | String | The name of the contact associated with the prepayment. This helps identify the individual or organization involved in the transaction. |
| Status | String | The status of the prepayment. Valid values are 'AUTHORISED', 'PAID', and 'VOIDED', indicating the current state of the prepayment in the system. |
| SubTotal | Decimal | The subtotal for the prepayment, excluding taxes. This represents the base amount of the prepayment before taxes are applied. |
| TotalTax | Decimal | The total tax amount for the prepayment. This is calculated based on the applicable tax rates and is added to the subtotal to get the total value of the prepayment. |
| Total | Decimal | The total for the prepayment, including tax. This is the sum of the 'SubTotal' and 'TotalTax', representing the full amount of the prepayment. |
| LineItem_LineItemId | String | The unique identifier for the line item in the prepayment. This links the prepayment to specific line items within the transaction. |
| LineItem_Description | String | A description of the line item in the prepayment. This field must contain at least one character and is required for creating an approved invoice. |
| LineItem_Quantity | Double | The quantity of the item in the line item. This field is required for invoice approval and must be a zero or positive value. |
| LineItem_UnitAmount | Decimal | The unit price of the item in the line item. This value is required for invoice approval. |
| LineItem_ItemCode | String | The code that identifies the associated item. This links the prepayment to specific inventory or services. |
| LineItem_AccountCode | String | The account code used for the prepayment. The account must be active in the system and is required for invoice approval. |
| LineItem_TaxType | String | The tax type applied to the line item. This allows overriding the default tax code for the associated account, if necessary. |
| LineItem_TaxAmount | Decimal | The tax amount calculated for the line item. This is based on the tax type and is included in the total tax of the prepayment. |
| LineItem_LineAmount | Decimal | The total amount for the line item, calculated by multiplying the quantity by the unit amount and applying any discounts. |
| LineItem_TrackingCategory1_CategoryId | String | The identifier for the first tracking category associated with the line item. Tracking categories allow for further categorization of expenses. |
| LineItem_TrackingCategory1_CategoryName | String | The name of the first tracking category. This helps categorize the line item for reporting purposes. |
| LineItem_TrackingCategory1_OptionId | String | The identifier for the first tracking category option. This adds more granularity to the categorization of the line item. |
| LineItem_TrackingCategory1_OptionName | String | The name of the first tracking category option. This defines the specific option selected for the tracking category. |
| LineItem_TrackingCategory1_Option_Stat | String | The status of the first tracking category option. This reflects whether the option is active or inactive for reporting purposes. |
| LineItem_TrackingCategory2_CategoryId | String | The identifier for the second tracking category associated with the line item. |
| LineItem_TrackingCategory2_CategoryName | String | The name of the second tracking category for additional categorization of the line item. |
| LineItem_TrackingCategory2_OptionId | String | The identifier for the second tracking category option. This allows further classification of the line item. |
| LineItem_TrackingCategory2_OptionName | String | The name of the second tracking category option. This defines the specific option selected for the second tracking category. |
| LineItem_TrackingCategory2_Option_Stat | String | The status of the second tracking category option. This reflects whether the second tracking category option is active or inactive. |
| LineItem_DiscountRate | Double | The percentage discount applied to the line item. This is applicable to 'ACCREC' (sales) invoices and reduces the total amount due. |
| LineAmountTypes | String | Specifies the type of line amount for the prepayment. Valid values include 'Exclusive' (tax excluded), 'Inclusive' (tax included), and 'NoTax' (no tax applied). |
| CurrencyCode | String | The ISO 4217 currency code for the prepayment. This indicates the currency used in the transaction (for example, 'USD' or 'EUR'). |
| CurrencyRate | String | The exchange rate used for a multicurrency prepayment. If no rate is provided, the default XE.com day rate is used. |
| UpdatedDateUTC | Datetime | The timestamp of when the prepayment was last updated. This ensures that the data reflects the most current information. |
| Allocation1_AppliedAmount | Decimal | The amount of the prepayment applied to a given invoice. This is part of the allocation process, where the prepayment is used to reduce the invoice balance. |
| Allocation1_Date | Date | The date when the first allocation of the prepayment was made. This helps track when the prepayment was applied to the invoice. |
| Allocation1_InvoiceId | String | The identifier for the invoice to which the first allocation of the prepayment was applied. |
| Allocation1_InvoiceNumber | String | The invoice number for the first invoice receiving the prepayment allocation. |
| Allocation2_AppliedAmount | Decimal | The amount of the prepayment applied to a second invoice, if applicable. |
| Allocation2_Date | Date | The date when the second allocation of the prepayment was made. |
| Allocation2_InvoiceId | String | The identifier for the second invoice to which the prepayment was applied. |
| Allocation2_InvoiceNumber | String | The invoice number for the second invoice receiving the prepayment allocation. |
| PaymentIds | String | A comma-separated list of payment IDs associated with the prepayment. This tracks the payments that are linked to the prepayment. |
| HasAttachments | Boolean | Indicates whether the prepayment has any attachments, such as receipts or supporting documents. |
| TenantId | String | The unique identifier of the tenant. This ensures the query retrieves data specific to a particular tenant in a multi-tenant environment. |
Used to query a Profit and Loss report for a specified date range, providing insights into the organization's income and expenses over the period. It is used to analyze financial performance and profitability.
There are a few different ways the range of dates can be specified when using this report:
1. When no parameters are specified, the report spans the current month:
SELECT * FROM ProfitAndLoss
2. When just FromDate is specified, the report spans from FromDate to the current date:
SELECT * FROM ProfitAndLoss WHERE FromDate = '2018-01-01'
Note: FromDate must be within a year of the current date.
3. When FromDate and ToDate are specified, the report is run from FromDate to ToDate:
SELECT * FROM ProfitAndLoss WHERE FromDate = '2018-01-01' AND ToDate = '2018-04-01'
Note: FromDate must be within a year of ToDate.
4. When Periods and Timeframe are specified, the report spans from the current date to the start of the specified Timeframe:
SELECT * FROM ProfitAndLoss WHERE Periods = 2 AND Timeframe = 'MONTH'
Note: When specifying the 'Month' timeframe, the Xero API may generate a report for the last 30 days from the start of the specified month, even for months with 31 days. As a workaround, specify a 31-day month in the ToDate column as an additional query criteria.
SELECT * FROM ProfitAndLoss WHERE Periods = 11 AND Timeframe = 'MONTH' AND FromDate= '2023-10-01' AND ToDate= '2023-10-31'
5. When Periods, Timeframe and ToDate are specified, the report spans from ToDate to the start of the specified Timeframe:
SELECT * FROM ProfitAndLoss WHERE Periods = 2 AND Timeframe = 'MONTH' AND ToDate = '2018-04-01'
Note: The report start date is set as the first of the current month. ToDate must be set as a later date, within 365 days of the first of the current month.
| Name | Type | Description |
| ID [KEY] | Integer | The row number that uniquely identifies each entry in the ProfitAndLossStandard report. This is used for indexing purposes. |
| Label1 | String | The label for the first column in the ProfitAndLossStandard report, typically representing the category or account name. |
| Label2 | String | The value for the first column in the ProfitAndLossStandard report, showing the financial data associated with the corresponding label. |
| Label3 | String | The label for the third column in the ProfitAndLossStandard report, used to categorize another set of financial data. |
| Label4 | String | The value for the third column in the ProfitAndLossStandard report, representing financial data associated with the Label3 category. |
| Label5 | String | The label for the fifth column in the ProfitAndLossStandard report, typically used for another financial category. |
| Label6 | String | The value for the fifth column in the ProfitAndLossStandard report, representing the financial data for Label5. |
| Label7 | String | The label for the seventh column in the ProfitAndLossStandard report. |
| Label8 | String | The value for the seventh column, showing financial data for Label7. |
| Label9 | String | The label for the ninth column in the ProfitAndLossStandard report. |
| Label10 | String | The value for the ninth column, displaying financial data for Label9. |
| Label11 | String | The label for the eleventh column, used to categorize another financial set. |
| Label12 | String | The value for the eleventh column, indicating the financial data associated with Label11. |
| Label13 | String | The value column for the thirteenth label in the ProfitAndLossStandard report, indicating the financial information. |
| AccountId | String | The unique identifier for the account associated with each row in the ProfitAndLossStandard report, helping link the data to specific financial accounts. |
| TenantId | String | The identifier of the tenant to query, used for multi-tenant environments to ensure the correct data is returned for the tenant of interest. |
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| FromDate | Datetime | The start date for filtering the Profit and Loss report. This parameter ensures that only data from this date onwards is included in the report. |
| ToDate | Datetime | The end date for filtering the Profit and Loss report. This defines the date up to which the report data is included. |
| Periods | Int | The number of periods (months, quarters, or years) to look back from the 'ToDate'. This allows for comparing data across multiple periods. |
| Timeframe | String | Defines the size of each period in the Profit and Loss report. Valid values are 'MONTH', 'QUARTER', or 'YEAR', determining how data is grouped. |
| TrackingCategoryID | String | The ID of the tracking category used in the Profit and Loss report. Specifying this parameter will show figures for each option within the category as separate columns. |
| TrackingOptionID | String | The ID for a specific option within a tracking category. When combined with 'TrackingCategoryID', this will return only one column for that option. |
| TrackingCategoryID2 | String | The ID of a second tracking category. If specified, the report will show figures for combinations of options from both tracking categories as separate columns. |
| TrackingOptionID2 | String | The ID of a specific option within the second tracking category. This will return a single column combining this option with options from the first category. |
| PaymentsOnly | Boolean | Set to 'true' to restrict the report to cash transactions only, excluding credit-based transactions. |
| StandardLayout | Boolean | Set to 'true' to apply the standard layout to the report, overriding any custom layouts that may be configured. |
Allows you to query templates for repeating invoices in Xero. Repeating invoices are automatically generated for regular billing cycles such as monthly or yearly, reducing the need for manual invoicing.
The RepeatingInvoice view allows you to SELECT the line items in repeating invoices for a Xero organization. The Id column is generated by the Cloud; this value combines the index of the line item with the unique, Xero-generated RepeatingInvoiceId.
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.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier combining the line item index and the invoice ID to ensure line-level uniqueness. |
| RepeatingInvoiceId | String | The unique identifier of the repeating invoice, assigned by Xero. |
| Type | String | The invoice type. Valid values: ACCPAY (bills) or ACCREC (sales invoices). |
| ContactId | String | The unique identifier of the contact associated with the invoice. Required when creating a new invoice. |
| ContactName | String | The name of the contact associated with the invoice. Required when creating a new invoice. |
| Schedule_Period | Integer | The frequency interval for the schedule, expressed as an integer (for example, 1 for every 1 week). |
| Schedule_Unit | String | The unit of time for the schedule frequency. Valid values: WEEKLY or MONTHLY. |
| Schedule_DueDate | Integer | An integer specifying the due date timing, used in combination with the DueDateType (for example, 20). |
| Schedule_DueDateType | String | Specifies how the due date is calculated. Valid values: DAYSAFTERBILLDATE, DAYSAFTERBILLMONTH, OFCURRENTMONTH, OFFOLLOWINGMONTH. |
| Schedule_StartDate | Date | The start date for the repeating invoice schedule. This marks the issue date of the first invoice. |
| Schedule_NextScheduledDate | Date | The next date on which the invoice in the repeating schedule will be generated. |
| Schedule_EndDate | Date | The end date for the repeating schedule, if specified. Only returned if the template includes an end date. |
| LineItem_LineItemId | String | The unique identifier for a line item, assigned by Xero. Required for updates; otherwise, line items are replaced. |
| LineItem_Description | String | A textual description of the line item. Required and must contain at least one character. |
| LineItem_Quantity | Double | The number of units for the line item. Required for approval and must be zero or a positive value. |
| LineItem_UnitAmount | Decimal | The price per unit for the line item. Required for approval. |
| LineItem_ItemCode | String | The item code that identifies the associated inventory or product item. |
| LineItem_AccountCode | String | The account code linked to the line item. Must be active in the organization. Required for invoice approval. |
| LineItem_TaxType | String | Overrides the default tax code of the selected account. Specifies the applicable tax type for the line item. |
| LineItem_TaxAmount | Decimal | The tax amount for the line item, automatically calculated based on the tax rate. |
| LineItem_LineAmount | Decimal | The total amount for the line item, calculated as quantity × unit amount, minus any discounts. |
| LineItem_TrackingCategory1_CategoryId | String | The ID of the first tracking category associated with the line item. |
| LineItem_TrackingCategory1_CategoryName | String | The name of the first tracking category associated with the line item. |
| LineItem_TrackingCategory1_OptionId | String | The ID of the selected option within the first tracking category. |
| LineItem_TrackingCategory1_OptionName | String | The name of the selected option within the first tracking category. |
| LineItem_TrackingCategory1_Option_Stat | String | The status of the first tracking category option (for example, ACTIVE or ARCHIVED). |
| LineItem_TrackingCategory2_CategoryId | String | The ID of the second tracking category associated with the line item. |
| LineItem_TrackingCategory2_CategoryName | String | The name of the second tracking category associated with the line item. |
| LineItem_TrackingCategory2_OptionId | String | The ID of the selected option within the second tracking category. |
| LineItem_TrackingCategory2_OptionName | String | The name of the selected option within the second tracking category. |
| LineItem_TrackingCategory2_Option_Stat | String | The status of the second tracking category option (for example, ACTIVE or ARCHIVED). |
| LineItem_DiscountRate | Double | The discount percentage applied to the line item. Only applicable to ACCREC-type (sales) invoices. |
| LineAmountTypes | String | Specifies how tax is treated in line item amounts. Valid values: Exclusive, Inclusive, NoTax. |
| Reference | String | An optional reference number for ACCREC-type (sales) invoices. |
| BrandingThemeId | String | The ID of the branding theme applied to the invoice. |
| CurrencyCode | String | The currency code used for the invoice, in ISO 4217 format (for example, USD or NZD). |
| Status | String | The current status of the invoice. Valid values: DRAFT, SUBMITTED, AUTHORISED. |
| SubTotal | Decimal | The total of all line items before tax. |
| TotalTax | Decimal | The total amount of tax applied to the invoice. |
| Total | Decimal | The total invoice amount, including tax (SubTotal + TotalTax). |
| HasAttachments | Boolean | Indicates whether the invoice includes any file attachments (true or false). |
| TenantId | String | The ID of the tenant to query, used to specify a tenant different from the connection tenant. |
Allows querying the list of organizations connected to your Xero account. It provides basic information about each tenant organization, such as its name and ID.
| Name | Type | Description |
| TenantId [KEY] | String | A unique identifier assigned to the tenant, representing a specific organization or practice. |
| Name | String | The name of the organization or practice associated with the tenant. |
| Type | String | Indicates whether the tenant is an organization or a practice, defining the nature of the entity. |
| IsActive | Boolean | A boolean value that indicates whether the connection is currently active and using this tenant. |
Enables querying tracking categories, which are used to segment financial transactions for better analysis and reporting. For example, you can track sales by region or department.
The TrackingCategories view allows you to SELECT tracking categories for a Xero organization. The Id column is generated by the Cloud; it combines the index of the line item with the unique, Xero-generated TrackingCategoryId.
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.
| Name | Type | Description |
| Id [KEY] | String | A unique identifier combining the tracking option index and the Xero-generated ID of the tracking category. |
| TrackingCategoryId | String | The unique Xero identifier for the tracking category, which defines the grouping of tracking options (for example, Department or Region). |
| Name | String | The name of the tracking category, such as Department or Region, used for organizing transactions. |
| Status | String | The status of the tracking category, which is always set to ACTIVE, indicating it's currently in use. |
| TrackingOptionId | String | The unique Xero identifier for the tracking option, representing a specific selection within the tracking category. |
| OptionName | String | The name of the tracking option, such as 'North' or 'South,' representing a specific value within the category. |
| TenantId | String | The ID of the tenant to query instead of the connection tenant, used when querying data for a different tenant. |
Provides a trial balance for the Xero organization, showing the debits and credits for all accounts in the general ledger. It's essential for checking the accuracy of financial statements.
| Name | Type | Description |
| ID [KEY] | Integer | A unique identifier for the row, typically used for indexing. |
| Account | String | The name of the account, representing a financial category (for example, Sales or Expenses). |
| Debit | Decimal | The debit balance for the current month up to the specified date, showing increases to assets or expenses. |
| Credit | Decimal | The credit balance for the current month up to the specified date, showing increases to liabilities or income. |
| YTDDebit | Decimal | The Year-to-Date (YTD) debit amount, representing the cumulative debit balance from the start of the fiscal year up to the current date. |
| YTDCredit | Decimal | The Year-to-Date (YTD) credit amount, representing the cumulative credit balance from the start of the fiscal year up to the current date. |
| AccountId | String | A unique identifier for the account, used to reference the account in financial transactions. |
| TenantId | String | The ID of the tenant to query, which allows for data retrieval from a specific organization rather than the default connection tenant. |
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| Date | Datetime | The 'as at' date for the trial balance, specifying the cutoff date for the financial data being reported. |
| PaymentsOnly | Boolean | Set this to true to filter the report to include only cash-based transactions, excluding non-cash items like accruals. |
Allows querying the list of users in a Xero organization. It includes user details like name, role, and access permissions, which are crucial for managing user access to financial data.
The Users table allows you to SELECT users for a Xero organization.
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.
| Name | Type | Description |
| UserId [KEY] | String | The unique identifier for the user within Xero. |
| FirstName | String | The user's first name. |
| LastName | String | The user's last name. |
| EmailAddress | String | The user's email address, used for communication and login. |
| UpdatedDateUTC | Datetime | Timestamp indicating when the user record was last updated in UTC format. |
| IsSubscriber | Boolean | Indicates whether the user is the primary subscriber of the Xero organisation. |
| OrganisationRole | String | The role of the user within the organisation. Possible values include: 'READONLY', 'INVOICEONLY', 'STANDARD', 'FINANCIALADVISER', 'MANAGEDCLIENT', and 'CASHBOOKCLIENT'. |
| TenantId | String | The ID of the tenant to query instead of the default connection tenant, if different. |
Stored procedures are function-like interfaces that extend the functionality of the Cloud beyond simple SELECT/INSERT/UPDATE/DELETE operations with Xero.
Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from Xero, along with an indication of whether the procedure succeeded or failed.
| Name | Description |
| AllocatetoInvoice | Allocates a document (for example, credit note or payment) against an invoice. This is useful for ensuring that payments or credit notes are correctly applied to outstanding invoices. |
| CreateReportSchema | Allows for saving a dynamic Profit and Loss report as a custom schema. This is useful for generating recurring reports that meet specific financial analysis needs. |
| GetLimitInfo | Retrieves API call limit information for a Xero tenant. It helps you monitor and manage your API usage to ensure compliance with rate limits. |
| ListAttachments | Retrieves a list of attachments that have been uploaded to documents in Xero, allowing you to track and access supporting documents linked to financial records. |
| RevokeTenant | Disconnects a tenant from the application. Once revoked, the user must reauthorize the connection the next time they interact with the application. |
| SendInvoiceEmail | Sends an email to the contacts listed on a sales invoice, which can include the invoice details and any additional notes or payment instructions. |
Allocates a document (for example, credit note or payment) against an invoice. This is useful for ensuring that payments or credit notes are correctly applied to outstanding invoices.
| Name | Type | Required | Description |
| Type | String | True | Specifies the type of document being allocated. This could refer to a particular classification of document, such as an invoice or credit note, used to determine how the allocation is processed.
The allowed values are CreditNotes, Overpayments, Prepayments. |
| DocumentId | String | True | The unique identifier for the document that is being allocated. This ID helps link the document to its relevant financial transaction or record. |
| InvoiceId | String | True | The unique identifier for the invoice that this document is being allocated against. This ties the document allocation to a specific invoice. |
| AppliedAmount | String | True | The amount of money being allocated to the invoice. This is the value that will be applied to reduce the outstanding balance on the specified invoice. |
| TenantId | String | False | The unique identifier for the tenant. This allows the system to query data specific to a tenant other than the default connection tenant, useful in multi-tenant environments. |
| Date | String | False | The date when the overpayment is applied. This marks the time at which the funds are officially allocated, which may be important for accounting and reporting purposes. |
| Name | Type | Description |
| Success | String | A boolean value indicating the outcome of the operation. 'True' means the allocation was successfully processed, while 'false' indicates that an error occurred during the process. |
Allows for saving a dynamic Profit and Loss report as a custom schema. This is useful for generating recurring reports that meet specific financial analysis needs.
The generated schema file outlines the metadata for the report, such as columns and column data types. You can edit the file to adjust data types, rename columns, and include or exclude columns.
EXECUTE [CreateReportSchema]
[ReportName] = "TestReportTest2",
[CustomFieldIdsPrimitive] = "1459925,1459928",
[CustomFieldIdsDropdown] = "1469785",
[CustomDimensionKeyIds] = "13539564",
[BaseReportName] = "TestReportTest1",
[FileName] = "...\\TestReportTest2.rsd"
| Name | Type | Required | Description |
| ReportName | String | True | The name to be assigned to the generated report. If 'FileStream' and the 'Location' connection property are not set, the associated file will be saved in the file path specified in the 'Location' property. |
| Periods | Int | False | The number of periods to look back from the 'ToDate'. This defines the period range for the report, allowing users to focus on a specific number of historical periods for comparison. |
| Timeframe | String | False | Specifies the size of each period for the report. Valid options include 'MONTH', 'QUARTER', or 'YEAR', determining whether each period in the report represents a month, a quarter, or a full year. |
| TrackingCategoryID | String | False | The ID of the tracking category. If specified, the Profit and Loss Report displays figures for each option within the category as separate columns, allowing detailed tracking of financial performance by category. |
| TrackingCategoryID2 | String | False | The ID of a second tracking category. If specified along with 'TrackingCategoryID', the 'Profit and Loss Report' will show figures for each combination of options from the two categories as separate columns, providing a detailed multi-dimensional view of financial data. |
| TenantId | String | False | The unique identifier for the tenant. This allows queries to retrieve data specific to a particular tenant, rather than using the default connection tenant. This is useful in multi-tenant environments where data for different tenants is handled separately. |
| Name | Type | Description |
| Success | String | A boolean value indicating whether the operation was successful. 'True' means the report was generated and processed correctly, while 'false' indicates that an error occurred. |
| FileData | String | Contains the Base64-encoded content of the generated file, if 'DownloadPath' and 'FileStream' are not provided. This allows the file to be retrieved and stored externally in Base64-encoded format. |
Retrieves API call limit information for a Xero tenant. It helps you monitor and manage your API usage to ensure compliance with rate limits.
This procedure reports information that the Cloud caches after each API request. If no requests have been made to a tenant on a connection than this procedure will report 0 rows. Otherwise, the LastModified field reports the last time the information in the row was updated.
If the last modified time is too long ago for your application to use, then this table may be refreshed by executing a query.
The query must read at least one row to ensure that an API request is triggered:
SELECT * FROM Organisation LIMIT 1
| Name | Type | Description |
| TenantId | String | The unique identifier of the tenant that the API usage limits apply to. This field contains a row for each tenant queried during the connection, though typically there will only be one row if a single tenant is queried. |
| AppRemaining | Integer | The number of remaining API calls available for the current OAuth app in the current minute, with a maximum limit of 10,000 calls. This limit is shared across all tenants accessed by the app, indicating the app's overall usage capacity. |
| MinuteRemaining | Integer | The number of remaining API calls available for the current OAuth app in the current minute, with a maximum limit of 60 calls. This limit is specific to the current tenant being queried, tracking the number of calls available for that particular tenant in the current minute. |
| DayRemaining | Integer | The number of remaining API calls available for the current OAuth app today, with a maximum limit of 5,000 calls. This limit is specific to the current tenant being queried and tracks the total number of calls available for that tenant throughout the day. |
| RetryAfter | Integer | The recommended time to wait before making another API call, provided when one of the above limits (for example, 'MinuteRemaining', 'DayRemaining') reaches zero during the most recent API call to the tenant. This is used to avoid hitting rate limits. |
| LastModified | Datetime | The timestamp of when the API usage limits information was last updated. This value is updated when performing API calls and may not reflect real-time data, as the values are only refreshed with each API interaction. |
Retrieves a list of attachments that have been uploaded to documents in Xero, allowing you to track and access supporting documents linked to financial records.
| Name | Type | Required | Description |
| Table | String | True | The name of the table containing the document from which a list of attachments will be retrieved. This identifies the database table that holds the document data and its associated attachments.
The allowed values are Invoices, Receipts, CreditNotes, BankTransactions, BankTransfers, Contacts, Accounts, ManualJournals. |
| ObjectId | String | False | The unique identifier of the document for which the list of attachments will be retrieved. This links the attachments to a specific document in the database, ensuring that only relevant attachments are returned. |
| TenantId | String | False | The unique identifier of the tenant. This ensures the query is scoped to the correct tenant in multi-tenant environments, ensuring proper isolation of data and retrieving attachments for the right organization. |
| Name | Type | Description |
| AttachmentId | String | The unique identifier for each attachment. This value allows each attachment to be individually referenced and accessed from the document. |
| FileName | String | The name of the attachment file. This field provides the name of the file for each attachment, which is useful for identifying and managing the attached documents. |
| URL | String | The URL where the attachment is located. This field provides a direct link to the attachment, allowing users to access or download the file. |
| MimeType | String | The Internet media type (MIME type) of the attachment. This field specifies the format of the attached file (for example, 'application/pdf', 'image/jpeg'), helping systems and users understand how to handle the file. |
| ContentLength | String | The size of the attachment in bytes. This field indicates the size of the file, providing information that can be used for validating file size limits or managing storage. |
Disconnects a tenant from the application. Once revoked, the user must reauthorize the connection the next time they interact with the application.
| Name | Type | Required | Description |
| TenantId | String | False | The unique identifier for the tenant whose connection is to be revoked, as provided in the Tenants view. |
| Name | Type | Description |
| Success | String | A boolean value indicating whether the connection was successfully revoked. Options are 'true' if the revocation was successful, and 'false' if it failed. |
Sends an email to the contacts listed on a sales invoice, which can include the invoice details and any additional notes or payment instructions.
| Name | Type | Required | Description |
| InvoiceId | String | True | The unique identifier (InvoiceId) of the invoice that is to be mailed. |
| TenantId | String | False | The ID of the tenant to query instead of the connection tenant. |
| Name | Type | Description |
| Success | String | A boolean value indicating whether the mail operation was successful. Options are 'true' if the operation was successful, or 'false' if it was unsuccessful. |
The Tables section, which details standard SQL tables, and the Views section, which lists read-only SQL tables, contain samples of what you might have access to in your Xero account.
Common tables include:
| Table | Description |
| Employees | Allows you to query, insert, and update employee records. Employees are individuals working for the organization, and their data includes payroll, tax, and employment information. |
| PayRuns | Used to query, insert, and update pay runs. A pay run represents the payroll process for a specific pay period and includes all employee payments, deductions, and taxes. |
| PaySlips | Allows querying payslips for a Xero organization. Payslips provide detailed breakdowns of employee pay, deductions, taxes, and other compensations for a specific pay period. |
| LeaveApplications | Manages leave applications submitted by employees. It allows for querying, inserting, and updating leave requests for various types of employee leave. |
| LeaveBalances | Queries the leave balance for an employee, showing how much leave they have accrued and used, as well as how much leave is available for future use. |
| Timesheets | Used to query, insert, and update timesheets for a Xero organization. Timesheets record the hours worked by employees, which are used to calculate pay for hourly workers. |
| PayrollCalendars | Stores and manages payroll calendars. It tracks the pay periods (for example, weekly, bi-weekly, or monthly) for the organization, helping to determine payroll schedules. |
| PayItemsEarnings | Used to query, insert, and update earnings that are part of the employee's pay items, such as regular wages, bonuses, and other forms of compensation. |
| PayItemsDeductions | Used to query, insert, and update deductions that are part of the employee's pay items, such as tax, union fees, or other voluntary deductions. |
| PayItemsLeave | Allows you to manage leave-related pay items. It is used to query, insert, and update leave accruals, including annual leave and sick leave. |
| PayItemsReimbursements | Manages reimbursement-related pay items. It allows you to track and manage employee expense reimbursements within the payroll system. |
| PaySlipEarnings | Manages payslip earnings line items. It includes details about an employee's earnings, such as salary, wages, bonuses, and commissions. |
| PaySlipDeductions | Manages payslip deduction line items for employees. It tracks the various deductions applied to an employee's pay, such as tax or superannuation. |
| PaySlipTaxes | Tracks tax-related line items in payslips. It includes information on the tax deductions applied to an employee's pay, such as income tax and other levies. |
| PaySlipSuperannuations | Manages payslip superannuation line items. Superannuation refers to the employer's contribution to an employee's retirement fund. |
| PaySlipReimbursements | Used to query, insert, and update manual journals. Manual journals are used to record financial transactions that don't follow standard processes. |
| PaySlipLeaveAccrual | Tracks leave accruals on the payslip. It helps manage and report on the amount of leave an employee has accrued over time. |
| PaySlipLeaveEarnings | Queries the leave earnings line items for a payslip. Leave earnings refer to the pay associated with leave taken by the employee, such as annual leave or sick leave. |
| SuperFunds | Used to manage payroll super funds for employees. It tracks the superannuation funds to which employees are contributing for their retirement savings. |
| EmployeeBankAccounts | Queries the bank accounts associated with an employee. It is used to track the employee's payment details and manage their salary or reimbursement payments. |
API limitations and requirements are documented in each table.
Stored Procedures are actions that are invoked via SQL queries. They perform tasks beyond standard create, read, update, delete (CRUD) operations, including managing OAuth tokens.
The Cloud models the data in Xero as a list of tables in a relational database that can be queried using standard SQL statements.
| Name | Description |
| Employees | Allows you to query, insert, and update employee records. Employees are individuals working for the organization, and their data includes payroll, tax, and employment information. |
| LeaveApplications | Manages leave applications submitted by employees. It allows for querying, inserting, and updating leave requests for various types of employee leave. |
| PayItemsDeductions | Used to query, insert, and update deductions that are part of the employee's pay items, such as tax, union fees, or other voluntary deductions. |
| PayItemsEarnings | Used to query, insert, and update earnings that are part of the employee's pay items, such as regular wages, bonuses, and other forms of compensation. |
| PayItemsLeave | Allows you to manage leave-related pay items. It is used to query, insert, and update leave accruals, including annual leave and sick leave. |
| PayItemsReimbursements | Manages reimbursement-related pay items. It allows you to track and manage employee expense reimbursements within the payroll system. |
| PayrollCalendars | Stores and manages payroll calendars. It tracks the pay periods (for example, weekly, bi-weekly, or monthly) for the organization, helping to determine payroll schedules. |
| PayRuns | Used to query, insert, and update pay runs. A pay run represents the payroll process for a specific pay period and includes all employee payments, deductions, and taxes. |
| PaySlipDeductions | Manages payslip deduction line items for employees. It tracks the various deductions applied to an employee's pay, such as tax or superannuation. |
| PaySlipEarnings | Manages payslip earnings line items. It includes details about an employee's earnings, such as salary, wages, bonuses, and commissions. |
| PaySlipLeaveAccrual | Tracks leave accruals on the payslip. It helps manage and report on the amount of leave an employee has accrued over time. |
| PaySlipReimbursements | Manages payslip reimbursement line items. It tracks reimbursements made to employees for out-of-pocket expenses. |
| PaySlipSuperannuations | Manages payslip superannuation line items. Superannuation refers to the employer's contribution to an employee's retirement fund. |
| PaySlipTaxes | Tracks tax-related line items in payslips. It includes information on the tax deductions applied to an employee's pay, such as income tax and other levies. |
| PaySlipTimesheetEarnings | Manages payslip timesheet earnings line items. It tracks earnings that are calculated based on time worked, such as hourly wages or overtime. |
| SuperFunds | Used to manage payroll super funds for employees. It tracks the superannuation funds to which employees are contributing for their retirement savings. |
| Timesheets | Used to query, insert, and update timesheets for a Xero organization. Timesheets record the hours worked by employees, which are used to calculate pay for hourly workers. |
Allows you to query, insert, and update employee records. Employees are individuals working for the organization, and their data includes payroll, tax, and employment information.
The Employees table allows you to SELECT and INSERT Payroll employees for a Xero organization.
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new Employee, the FirstName, LastName, Status, Title, DateOfBirth, JobTitle, HomeAddress_AddressLine1, HomeAddress_City, HomeAddress_Region, HomeAddress_PostalCode, and HomeAddress_Country are required.
INSERT INTO Employees (FirstName, LastName, Status, Title, DateOfBirth, JobTitle, HomeAddress_AddressLine1, HomeAddress_City, HomeAddress_Region, HomeAddress_PostalCode, HomeAddress_Country) VALUES ('John', 'Doe', 'ACTIVE', 'Mr', '1986-01-01', 'Engineer', '123 Hollywood Dr', 'Sydney', 'ACT', '3000', 'Australia')
Employees can also be added in bulk by specifying multiple records in the VALUES clause.
INSERT INTO Employees (FirstName, LastName, Status, Title, DateOfBirth, JobTitle, HomeAddress_AddressLine1, HomeAddress_City, HomeAddress_Region, HomeAddress_PostalCode, HomeAddress_Country)
VALUES
('John', 'Doe', 'ACTIVE', 'Mr', '1986-01-01', 'Engineer', '123 Hollywood Dr', 'Sydney', 'ACT', '3000', 'Australia'),
('Jane', 'Doe', 'ACTIVE', 'Mr', '1986-01-01', 'Engineer', '123 Hollywood Dr', 'Sydney', 'ACT', '3000', 'Australia')
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
The Xero API has limited support for deleting any object. In order to delete objects, you must update their Status to an appropriate value.
Applicable values for this field may be state-dependent. For example, invoices can only have their status set to DELETED when the invoice status is currently DRAFT or SUBMITTED.
| Name | Type | ReadOnly | Filterable | Description |
| EmployeeID [KEY] | String | True |
The unique identifier of the employee. This field is assigned by Xero. | |
| Status | String | False |
The status of the employee. Valid values are 'ACTIVE' and 'TERMINATED'. | |
| Title | String | False |
The title of the employee. | |
| FirstName | String | False |
The first name of the employee. | |
| MiddleNames | String | False |
The middle names of the employee. | |
| LastName | String | False |
The last name of the employee. | |
| DateOfBirth | Date | False |
The employee's birthday. | |
| JobTitle | String | False |
The job title of the employee. | |
| Gender | String | False |
The gender of the employee. | |
| Phone | String | False |
The employee's home phone number. | |
| Mobile | String | False |
The employee's mobile phone number. | |
| String | False |
The employee's email address. | ||
| StartDate | Date | False |
The employee's hire date. | |
| TerminationDate | Date | False |
The employee's termination date. | |
| TerminationReason | String | False |
The reason for the employee's termination, as a one-letter code. | |
| OrdinaryEarningsRateID | String | False |
A reference to the employee's pay schedule. | |
| PayrollCalendarID | String | False |
A reference to the employee's pay schedule. | |
| IsAuthorisedToApproveLeave | Boolean | False |
Indicates whether the employee is authorized to approve time off. | |
| IsAuthorisedToApproveTimesheets | Boolean | False |
Indicates whether the employee is authorized to approve timesheets. | |
| EmployeeGroupName | String | False |
The name of the tracking category the employee belongs to, if one is assigned. | |
| UpdatedDateUTC | Datetime | True |
Timestamp of the last change to the employee record. | |
| HomeAddress_AddressLine1 | String | False |
Address Line 1 for employee home address. | |
| HomeAddress_AddressLine2 | String | False |
Address Line 2 for employee home address. | |
| HomeAddress_City | String | False |
Suburb for employee home address. | |
| HomeAddress_Region | String | False |
State abbreviation for employee home address. | |
| HomeAddress_PostalCode | String | False |
Postal code for employee home address. | |
| HomeAddress_Country | String | False |
Country of the employee's home address. | |
| TaxDeclaration_EmploymentBasis | String | False |
The employment basis for tax purposes. Options include 'FULLTIME', 'PARTTIME', 'CASUAL', 'LABOURHIRE', or 'SUPERINCOMESTREAM'. | |
| TaxDeclaration_TFNExemptionType | String | False |
If the employee has no Tax File Number (TFN), use one of the following options: 'NOTQUOTED', 'PENDING', 'PENSIONER', or 'UNDER18'. | |
| TaxDeclaration_TaxFileNumber | String | False |
The last three digits of the employee's TFN. | |
| TaxDeclaration_AustralianResidentForTaxPurposes | Boolean | False |
Indicates whether the employee is an Australian resident for tax purposes. | |
| TaxDeclaration_ResidencyStatus | String | False |
The residency status of the employee. Options include 'AUSTRALIANRESIDENT', 'FOREIGNRESIDENT', or 'WORKINGHOLIDAYMAKER'. | |
| TaxDeclaration_TaxFreeThresholdClaimed | Boolean | False |
Indicates whether the employee claims to make below the tax-free threshold. | |
| TaxDeclaration_TaxOffsetEstimatedAmount | Decimal | False |
Any other tax offsets the employee has claimed. | |
| TaxDeclaration_HasHELPDebt | Boolean | False |
Indicates whether the employee has Higher Education Loan Program (HELP) debt. | |
| TaxDeclaration_HasSFSSDebt | Boolean | False |
Indicates whether the employee has financial supplement debt. | |
| TaxDeclaration_HasTradeSupportLoanDebt | Boolean | False |
Indicates whether the employee has a trade support loan. | |
| TaxDeclaration_UpwardVariationTaxWithholdingAmount | Decimal | False |
The extra withholding the employee has requested, in percent. | |
| TaxDeclaration_EligibleToReceiveLeaveLoading | Boolean | False |
If the employee is eligible to receive extra earnings when they take leave. | |
| TaxDeclaration_ApprovedWithholdingVariationPercentage | Decimal | False |
The extra withholding the employee has been granted, in percent. | |
| BankAccounts | String | True |
The bank accounts for the employee in XML format. | |
| PayTemplate | String | True |
The pay template for the employee in XML format. | |
| OpeningBalances | String | True |
The opening balances for the employee in XML format. | |
| LeaveBalances | String | True |
The leave balances for the employee in XML format. | |
| SuperMemberships | String | True |
The super memberships for the employee in XML format. | |
| TenantId | String | False |
The ID of the tenant to query instead of the connection tenant. |
Manages leave applications submitted by employees. It allows for querying, inserting, and updating leave requests for various types of employee leave.
The Timesheets table allows you to SELECT and INSERT leave applications for a Xero organization. The Id column is generated by the Cloud; the value of this field combines the index of the line item with the unique, Xero-generated LeaveApplicationID.
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new leave application, the EmployeeID, LeaveTypeID, Title, StartDate and EndDate are required. In addition leave periods may also be provided.
In addition to inserting a single row, line item tables offer two additional ways to insert into a table.
INSERT INTO LeaveApplications (EmployeeID, LeaveTypeID, Title, StartDate, EndDate, LeavePeriodAggregate) VALUES (
'XXXXX-XXXXX-XXXXX-XXXXX',
'YYYYY-YYYYY-YYYYY-YYYYY',
'Visit relatives',
'2021-01-01',
'2021-01-07',
'<LeavePeriod>
<NumberOfUnits>8</NumberOfUnits>
</LeavePeriod>
<LeavePeriod>
<NumberOfUnits>32</NumberOfUnits>
</LeavePeriod>'
)INSERT INTO LeaveApplications (LeaveApplicationID, LeavePeriods_LeavePeriod_NumberOfUnits) VALUES ('XXXXX-XXXXX-XXXXX-XXXXX', 'YYYYY-YYYYY-YYYYY-YYYYY', 32)Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
The Xero API has limited support for deleting any object. In order to delete objects, you must update their Status to an appropriate value.
Applicable values for this field may be state-dependent. For example, invoices can only have their status set to DELETED when the invoice status is currently DRAFT or SUBMITTED.
| Name | Type | ReadOnly | Filterable | Description |
| Id [KEY] | String | True |
A unique combination of the leave period line-item index and the Xero-generated identifier for the leave application. | |
| LeaveApplicationID | String | True |
The unique identifier assigned to the leave application by Xero, linking multiple leave periods to a single application. | |
| EmployeeID | String | False |
The unique Xero identifier for the employee requesting the leave. | |
| LeaveTypeID | String | False |
The unique Xero identifier for the type of leave, such as sick leave or annual leave. | |
| Title | String | False |
The brief title or label for the leave period, for example, 'Vacation' or 'Sick Leave'. | |
| StartDate | String | False |
The start date of the leave, formatted as YYYY-MM-DD. | |
| EndDate | String | False |
The end date of the leave, formatted as YYYY-MM-DD. | |
| Description | String | False |
A free-text description explaining the reason for taking the leave (for example, 'Family Emergency' or 'Annual Leave'). | |
| LeavePeriodAggregate | String | False |
Used to define leave period rows in XML format. Should only be provided when inserting new records. | |
| LeavePeriods_LeavePeriod_PayPeriodStartDate | String | False |
The start date of the pay period from which the leave is being drawn. | |
| LeavePeriods_LeavePeriod_PayPeriodEndDate | String | False |
The end date of the pay period from which the leave is being drawn. | |
| LeavePeriods_LeavePeriod_LeavePeriodStatus | String | False |
The current status of the leave period, either 'SCHEDULED' (pending) or 'PROCESSED' (completed). | |
| LeavePeriods_LeavePeriod_NumberOfUnits | String | False |
The number of leave units (for example, days or hours) consumed during the specified pay period. | |
| TenantId | String | False |
The unique ID of the tenant (organization) to query instead of the connection tenant. |
Used to query, insert, and update deductions that are part of the employee's pay items, such as tax, union fees, or other voluntary deductions.
| Name | Type | ReadOnly | Filterable | Description |
| DeductionTypeID [KEY] | String | True |
The unique identifier assigned to the deduction type PayItem by Xero. This ID helps to uniquely reference and distinguish between different types of pay deductions, such as tax deductions or union dues. | |
| Name | String | False |
The name of the deduction type, such as 'Health Insurance' or 'Union Dues'. This field helps identify the specific deduction applied to the employee's payroll. | |
| DeductionCategory | String | False |
The category of the deduction, which helps to group similar deductions together for reporting purposes. Categories could include 'Tax', 'Benefits', or 'Superannuation'. | |
| AccountCode | String | False |
A customer-defined alphanumeric code that identifies the accounting account to which the deduction is allocated. This ensures proper accounting treatment of deductions for financial reporting. | |
| ReducesTax | String | False |
Indicates whether the deduction reduces the employee's taxable income for tax purposes. This is particularly important for pre-tax deductions like retirement contributions or health insurance premiums. | |
| ReducesSuper | String | False |
Indicates whether the deduction impacts the employee's superannuation guarantee contribution liability. For example, some deductions may reduce the amount the employer contributes to the employee's superannuation. | |
| UpdatedDateUTC | Datetime | True |
The timestamp of the last modification to the deduction type PayItem record. This helps track changes made to the deduction details over time. | |
| TenantId | String | False |
The unique identifier of the tenant (organization) to query instead of the connection tenant. This ensures that the deduction data is retrieved from the correct organization within Xero, especially useful for companies managing multiple entities. |
Used to query, insert, and update earnings that are part of the employee's pay items, such as regular wages, bonuses, and other forms of compensation.
| Name | Type | ReadOnly | Filterable | Description |
| EarningsRateID [KEY] | String | True |
The unique identifier assigned by Xero to the earnings rate PayItem. This ID ensures that each earnings rate is distinct and can be easily referenced in payroll calculations. | |
| Name | String | False |
The name of the earnings rate, such as 'Hourly Rate' or 'Salary'. This field helps identify the type of earnings rate applied to an employee's pay. | |
| DisplayName | String | False |
The display name of the earnings rate that will appear on the employee's payslips. This field allows you to provide a more human-readable name for the earnings rate that is shown to the employee. | |
| AccountCode | String | False |
A customer-defined alphanumeric account code that links the earnings rate to a specific financial account in the accounting system. This ensures the proper accounting treatment of earnings. | |
| TypeOfUnits | String | False |
The unit type used to measure earnings, such as 'hours', 'days', or 'units'. This determines how the earnings rate is recorded and calculated based on time worked or output produced. | |
| IsExemptFromTax | String | False |
Indicates whether the earnings are exempt from PAYG (Pay As You Go) withholding tax. This should only be set for earnings that are explicitly exempt from tax according to tax laws. | |
| IsExemptFromSuper | String | False |
Specifies whether the earnings are exempt from Superannuation Guarantee Contributions (SGC). Some types of income may be exempt from superannuation contributions under certain conditions. | |
| IsReportableAsW1 | Bool | False |
Specifies whether the earnings are subject to W1 (Withholding Tax Type 1) withholding. This is relevant for certain tax reporting purposes. | |
| EarningsType | String | False |
The type of earnings represented by the earnings rate. Possible values include 'FIXED' (fixed amount), 'ORDINARYTIMEEARNINGS' (normal work hours), 'OVERATIMEEARNINGS' (overtime), 'ALLOWANCE' (additional payment), and 'LUMPSUMD' (lump sum payment). | |
| AllowanceType | String | False |
Describes what the allowance is paid for when the EarningsType is 'ALLOWANCE'. Examples include 'Meal Allowance' or 'Travel Allowance'. | |
| AllowanceCategory | String | False |
Specifies the category of the allowance when the AllowanceType is 'OTHER'. This allows for customization and categorization of allowances based on business needs. | |
| RateType | String | False |
The rate type for the earnings. Valid options include 'FIXEDAMOUNT' (fixed amount per pay period), 'MULTIPLE' (multiple times the base rate), and 'RATEPERUNIT' (rate per unit of time or work). | |
| RatePerUnit | String | False |
The rate per unit of time or work. This field is used only when RateType is 'RATEPERUNIT', and it specifies the amount earned for each unit worked. | |
| Multiplier | Double | False |
The multiplier used to calculate the earnings based on the employee's ordinary earnings type. This is only applicable when RateType is 'MULTIPLE' and is used to adjust the earnings rate. | |
| AccrueLeave | String | False |
Indicates whether leave should be accrued for this earnings rate. This is relevant when employees earn leave based on their work hours or salary, and applies only when RateType is 'MULTIPLE'. | |
| Amount | String | False |
The fixed amount paid for earnings with a FIXEDAMOUNT RateType. This represents the total amount to be paid for the earnings rate regardless of other factors. | |
| CurrentRecord | Bool | False |
Indicates whether this earnings rate is still active and available for use. If the value is set to 'false', the earnings rate may have been discontinued and should no longer be applied to new payroll records. | |
| UpdatedDateUTC | Datetime | True |
The timestamp indicating when the earnings rate record was last modified. This helps track changes and ensures that the most up-to-date rate is being applied. | |
| TenantId | String | False |
The unique identifier of the tenant (organization) to query instead of the connection tenant. This ensures the data is retrieved from the correct organization within Xero, especially useful for managing multiple tenants or companies. |
Allows you to manage leave-related pay items. It is used to query, insert, and update leave accruals, including annual leave and sick leave.
| Name | Type | ReadOnly | Filterable | Description |
| LeaveTypeID [KEY] | String | True |
The unique identifier assigned by Xero to the leave type PayItem. This ensures that each leave type is distinct and can be easily referenced for payroll and leave management purposes. | |
| Name | String | False |
The name of the leave type, such as 'Annual Leave' or 'Sick Leave'. This field helps identify the type of leave being applied to an employee's record. | |
| TypeOfUnits | String | False |
The unit type used to measure and track leave entitlements, such as 'hours', 'days', or 'weeks'. This determines how leave balances are calculated and recorded for the employee. | |
| IsPaidLeave | String | False |
Indicates whether the leave type is paid or unpaid. When set to 'paid', the employee will receive their regular pay while on leave. This is typically applied to annual leave or sick leave. | |
| ShowOnPaySlip | String | False |
Set this field to 'true' if you want the balance of this leave type to appear on the employee's payslips. This is useful for employees to see how much paid or unpaid leave they have remaining. | |
| NormalEntitlement | String | False |
The standard number of leave units the employee is entitled to each year for this leave type. For example, '20 days' of annual leave or '10 days' of sick leave per year. | |
| LeaveLoadingRate | String | False |
Enter the additional percentage (typically 17.5%) that is paid on top of the employee's regular earnings when they take leave. This is commonly applied in countries like Australia for certain leave types. | |
| UpdatedDateUTC | Datetime | False |
The timestamp indicating the last time this leave type record was updated. This helps keep track of changes and ensures that the most up-to-date leave policies are being applied. | |
| TenantId | String | False |
The unique identifier of the tenant (organization) to query instead of the connection tenant. This ensures that the data is retrieved from the correct organization within Xero, especially for organizations managing multiple companies. |
Manages reimbursement-related pay items. It allows you to track and manage employee expense reimbursements within the payroll system.
| Name | Type | ReadOnly | Filterable | Description |
| ReimbursementTypeID [KEY] | String | True |
The unique identifier for the reimbursement type PayItem. This ID is automatically assigned by Xero to ensure each reimbursement type is distinct and can be tracked separately. | |
| Name | String | False |
The name of the reimbursement type, such as 'Travel Expenses' or 'Office Supplies'. This helps categorize and identify the specific type of reimbursement being applied to the employee. | |
| AccountCode | String | False |
A customer-defined alphanumeric code that is used to map the reimbursement type to a specific account in the organization's chart of accounts. This code helps in managing financial reporting and ensuring the reimbursement is tracked correctly in the general ledger. | |
| UpdatedDateUTC | Datetime | True |
The timestamp indicating when the reimbursement type record was last updated. This helps track changes to the reimbursement types over time, ensuring that the most recent details are being applied to employee records. | |
| TenantId | String | False |
The unique identifier of the tenant (organization) to query instead of the connection tenant. This ensures that the data is retrieved from the correct organization within Xero, especially in scenarios where multiple organizations are managed under different accounts. |
Stores and manages payroll calendars. It tracks the pay periods (for example, weekly, bi-weekly, or monthly) for the organization, helping to determine payroll schedules.
| Name | Type | ReadOnly | Filterable | Description |
| PayrollCalendarID [KEY] | String | True |
The unique identifier assigned by Xero to the payroll calendar. This ID is used to uniquely identify the pay schedule, allowing for accurate tracking and management of payroll periods within Xero. | |
| Name | String | False |
The name of the payroll calendar, which helps identify the specific pay schedule used by an organization, such as 'Bi-weekly Payroll' or 'Monthly Payroll'. This name is useful for distinguishing between multiple payroll calendars in organizations with varying pay cycles. | |
| CalendarType | String | False |
The type of payroll calendar, such as 'Weekly', 'Bi-weekly', or 'Monthly'. This field defines how frequently employees are paid within the calendar period and helps automate payroll calculations. | |
| StartDate | String | False |
The start date of the upcoming pay period, indicating when the payroll cycle begins. This helps in determining the period for which employees will be compensated and ensures accurate payroll processing. | |
| PaymentDate | String | False |
The date on which employees will be paid for the upcoming pay period. This is the actual payment date, which is critical for payroll operations, ensuring employees receive their pay on time. | |
| TenantId | String | False |
The unique identifier of the tenant (organization) to query instead of the connection tenant. This ensures that the payroll calendar is retrieved from the correct organization in Xero, especially when managing multiple organizations under a single account. |
Used to query, insert, and update pay runs. A pay run represents the payroll process for a specific pay period and includes all employee payments, deductions, and taxes.
| Name | Type | ReadOnly | Filterable | Description |
| PayRunID [KEY] | String | True |
The unique identifier assigned by Xero to the payrun. This field helps in uniquely tracking and managing individual payruns within the payroll system. | |
| PayrollCalendarID | String | False |
The identifier for the payroll calendar associated with the payrun. This links the payrun to a specific payroll calendar, determining the pay schedule (for example, weekly, bi-weekly, or monthly). | |
| PayRunPeriodStartDate | String | False |
The start date of the period for which the payrun is being processed. This date marks the beginning of the pay cycle and is critical for calculating earnings and deductions. | |
| PayRunPeriodEndDate | String | False |
The end date of the period for the payrun. This date marks the conclusion of the pay cycle, helping to finalize the earnings and deductions for that period. | |
| PayRunStatus | String | False |
The current status of the payrun. Valid values include 'ACTIVE' (indicating the payrun is still being processed) and 'DELETED' (indicating that the payrun has been canceled). | |
| PaymentDate | String | False |
The date on which the payment will be made to the employees for this payrun. This is the actual date employees will receive their pay. | |
| PayslipMessage | String | False |
A customizable message that can be included on the payslip for this payrun. This field allows for communication to employees regarding their payrun. | |
| Wages | Decimal | False |
The total wages calculated for the payrun. This value includes all earnings before any deductions, taxes, or adjustments are applied. | |
| Deductions | Decimal | False |
The total amount deducted from employee wages for the payrun. This may include taxes, superannuation contributions, and other deductions. | |
| Tax | Decimal | False |
The total amount of tax withheld for the payrun. This is typically based on the employee's tax rate, allowances, and other tax considerations. | |
| Super | Decimal | False |
The total superannuation contributions made on behalf of employees for the payrun. This is typically a percentage of the employee's wages. | |
| Reimbursement | Decimal | False |
The total amount of reimbursements issued to employees in the payrun. This could include amounts reimbursed for business expenses or other agreed-upon reimbursements. | |
| NetPay | Decimal | False |
The final amount paid to the employee after all deductions, taxes, and adjustments. This is the amount the employee will actually receive. | |
| UpdatedDateUTC | Datetime | True |
The timestamp indicating the last change made to the payrun record. This helps track when the payrun details were last updated or modified. | |
| Payslip | String | False |
The payslip for this payrun in XML format. The payslip contains detailed information about the employee's earnings, deductions, and net pay. | |
| TenantId | String | False |
The unique identifier of the tenant (organization) associated with the payrun. This ensures that the payrun is linked to the correct organization when managing multiple tenants. |
Manages payslip deduction line items for employees. It tracks the various deductions applied to an employee's pay, such as tax or superannuation.
This table supports the following operators server-side: =,IN
To insert a single row, set the required fields. The Cloud adds a new deduction line to the payslip.
INSERT INTO PaySlipDeductions (PayslipID, DeductionLine_DeductionTypeId, DeductionLine_CalculationType, DeductionLine_Amount) VALUES ('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 'b78b5ddd-6a20-4992-8e77-1243a122265d', 'FIXEDAMOUNT', 50)
INSERT INTO PaySlipDeductions (PayslipID, DeductionLine_DeductionTypeId, DeductionLine_CalculationType, DeductionLine_Amount)
VALUES
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 'b78b5ddd-6a20-4992-8e77-1243a122265d', 'FIXEDAMOUNT', 50),
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 'b78b5ddd-6a20-4992-8e77-1243a122265d', 'FIXEDAMOUNT', 75)
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
UPDATE PaySlipDeductions SET DeductionLine_Amount=5 WHERE Id='2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
Supply the Id to delete payslip deduction lines.
DELETE FROM PaySlipDeductions WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
| Name | Type | ReadOnly | Filterable | Description |
| Id [KEY] | String | True |
A unique identifier for the earnings line item, combined with the Xero-generated ID of the associated payslip. This helps in tracking and referencing each specific line of earnings in the payslip. | |
| PayslipID | String | False |
The unique identifier assigned by Xero to the payslip. This field helps to uniquely track and manage individual payslips within the system. | |
| EmployeeID | String | True |
The unique identifier assigned to the employee for this particular payslip. This ties the payslip to the specific employee it pertains to. | |
| DeductionLine_DeductionTypeId | String | False |
The unique identifier for the deduction type applied to this line item. This helps categorize the deduction (for example, tax or insurance) based on the predefined deduction type in Xero. | |
| DeductionLine_CalculationType | String | False |
The method by which the deduction is applied to the employee's earnings. It can be one of the following: 'PRETAX' (applied before taxes), 'POSTTAX' (applied after taxes), or 'FIXEDAMOUNT' (a set, non-variable amount). | |
| DeductionLine_Amount | Decimal | False |
The total monetary amount of the deduction applied to the employee's earnings for this particular line. This is the dollar value of the deduction. | |
| DeductionLine_Percentage | Double | False |
The percentage of the employee's income that is deducted for this line. This is typically used for deductions that apply as a percentage of wages, such as a tax rate or contribution percentage. | |
| TenantId | String | False |
The unique identifier of the tenant (organization) in Xero. This ensures the payslip and its details are correctly linked to the correct tenant (or organization) in the system. |
Manages payslip earnings line items. It includes details about an employee's earnings, such as salary, wages, bonuses, and commissions.
This table supports the following operators server-side: =,IN
To insert a single row, set the required fields. The Cloud adds a new earnings line to the payslip.
INSERT INTO PaySlipEarnings (PaySlipID, EarningsLine_EarningsRateId, EarningsLine_RatePerUnit, EarningsLine_NumberOfUnits) VALUES ('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 'fc394b8d-ff2e-4f10-992b-2a41390ad2c4', 4, 20)
INSERT INTO PaySlipEarnings (PaySlipID, EarningsLine_EarningsRateId, EarningsLine_RatePerUnit, EarningsLine_NumberOfUnits)
VALUES
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 'fc394b8d-ff2e-4f10-992b-2a41390ad2c4', 4, 20),
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 'fc394b8d-ff2e-4f10-992b-2a41390ad2c4', 5, 30)
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
UPDATE PaySlipEarnings SET EarningsLine_RatePerUnit = 5 WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
Supply the Id to delete payslip earnings lines.
DELETE FROM PaySlipEarnings WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
| Name | Type | ReadOnly | Filterable | Description |
| Id [KEY] | String | True |
A unique identifier for the earnings line item, which is a combination of the line item and the unique Xero identifier of the associated payslip. This allows each specific earnings entry to be tracked and referenced within the payroll system. | |
| PayslipID | String | False |
The unique identifier for the payslip assigned by Xero. This identifier allows the payrun and its associated earnings and deductions to be linked to the specific payslip. | |
| EmployeeID | String | True |
The unique identifier for the employee whose earnings are detailed in the payslip. This ID helps to associate the payslip's earnings with the correct employee in the payroll system. | |
| EarningsLine_EarningsRateId | String | False |
The unique identifier of the earnings rate applied to this line item. The earnings rate defines the pay scale or the conditions under which an employee's wages are calculated (such as hourly or salary). | |
| EarningsLine_RatePerUnit | Decimal | False |
The wage rate applied per time unit (such as per hour or per day). This value defines how much the employee earns for each unit of time worked, important for calculating total earnings in hourly-based pay systems. | |
| EarningsLine_NumberOfUnits | Double | False |
The number of time units worked in this particular line item. For hourly workers, this is the number of hours worked, and it's multiplied by the rate per unit to calculate the total earnings for this line. | |
| EarningsLine_FixedAmount | Decimal | False |
The total fixed earnings in this line item. This appears only when the earnings type is FIXED, meaning the employee is paid a set amount regardless of the number of hours or units worked. | |
| EarningsLine_LumpSumETaxYear | String | False |
The tax year that applies to these earnings. This field is used only when the earnings type is 'LUMPSUME', typically for one-off payments such as bonuses, which may be reported separately for tax purposes. | |
| TenantId | String | False |
The unique identifier for the tenant (or organization) in Xero. This ensures that the earnings data is linked to the correct organization and prevents data confusion when managing multiple organizations. |
Tracks leave accruals on the payslip. It helps manage and report on the amount of leave an employee has accrued over time.
This table supports the following operators server-side: =,IN
To insert a single row, set the required fields. The Cloud adds a new leave accrual line to the payslip.
INSERT INTO PaySlipLeaveAccrual (PaySlipID, LeaveAccrualLine_LeaveTypeId, LeaveAccrualLine_NumberOfUnits, LeaveAccrualLine_AutoCalculate) VALUES ('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', '73f37030-b1ed-45fe-b7a2-f704a3a28ad4', 8, false)
INSERT INTO PaySlipLeaveAccrual (PaySlipID, LeaveAccrualLine_LeaveTypeId, LeaveAccrualLine_NumberOfUnits, LeaveAccrualLine_AutoCalculate)
VALUES
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', '73f37030-b1ed-45fe-b7a2-f704a3a28ad4', 8, false),
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', '73f37030-b1ed-45fe-b7a2-f704a3a28ad4', 12, false)
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
UPDATE PaySlipLeaveAccrual SET LeaveAccrualLine_NumberOfUnits = 5 WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
Supply the Id to delete leave accrual lines.
DELETE FROM PaySlipLeaveAccrual WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680' PaySlipReimbursements
| Name | Type | ReadOnly | Filterable | Description |
| Id [KEY] | String | True |
A unique identifier for the earnings line item, which combines the specific line item and the Xero identifier of the associated payslip. This allows each leave accrual line to be uniquely identified and referenced in the payroll system. | |
| PayslipID | String | False |
The unique identifier for the payslip assigned by Xero. This links the leave accrual line to the specific payslip it belongs to, ensuring the payroll details are correctly associated with the employee's earnings and deductions. | |
| EmployeeID | String | True |
The unique identifier for the employee associated with this leave accrual. This links the leave accrual line to a specific employee's payslip and ensures accurate tracking of their leave entitlements. | |
| LeaveAccrualLine_LeaveTypeId | String | False |
The unique identifier of the leave type applied to the leave accrual line. This ensures that the type of leave being accrued (for example, annual leave or sick leave) is clearly tracked and correctly categorized. | |
| LeaveAccrualLine_NumberOfUnits | Double | False |
The number of leave units (for example, hours or days) being accrued for this leave type in this payslip. This value represents the amount of leave the employee is entitled to for the current period. | |
| LeaveAccrualLine_AutoCalculate | String | False |
Indicates whether the leave accrual should be automatically calculated based on predefined rules or entered manually. This helps automate the leave tracking process, reducing the need for manual data entry and potential errors. | |
| TenantId | String | False |
The unique identifier for the tenant (or organization) in Xero. This ensures that the leave accrual data is linked to the correct organization and helps maintain accurate records across multiple tenants. |
Manages payslip reimbursement line items. It tracks reimbursements made to employees for out-of-pocket expenses.
This table supports the following operators server-side: =,IN
To insert a single row, set the required fields. The Cloud adds a new reimbursement line to the payslip.
INSERT INTO PaySlipReimbursements (PaySlipID, ReimbursementLine_ReimbursementTypeId, ReimbursementLine_Amount) VALUES ('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', '3432120f-4d83-4bc2-8b5d-5a116838229e', 5)
INSERT INTO PaySlipReimbursements (PaySlipID, ReimbursementLine_ReimbursementTypeId, ReimbursementLine_Amount)
VALUES
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', '3432120f-4d83-4bc2-8b5d-5a116838229e', 5),
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', '3432120f-4d83-4bc2-8b5d-5a116838229e', 12)
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
UPDATE PaySlipReimbursements SET ReimbursementLine_Amount = 6 WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
Supply the Id to delete payslip reimbursement lines.
DELETE FROM PaySlipReimbursements WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
| Name | Type | ReadOnly | Filterable | Description |
| Id [KEY] | String | True |
A unique identifier for the reimbursement line item, combining the specific line item and the Xero identifier of the associated payslip. This ensures precise identification of the reimbursement in the payroll system. | |
| PayslipID | String | False |
The unique identifier of the payslip, as assigned by Xero. This links the reimbursement line item to a specific payslip and ensures that the reimbursement is accurately reflected in the employee's payroll record. | |
| EmployeeID | String | True |
The unique identifier of the employee associated with this reimbursement line. This links the reimbursement to the specific employee's payslip and payroll details. | |
| ReimbursementLine_ReimbursementTypeId | String | False |
The unique identifier for the type of reimbursement applied to this line item. This could include types such as travel expenses, meal allowances, or other employee reimbursements. | |
| ReimbursementLine_Description | String | False |
A brief description of the reimbursement, specifying what the reimbursement is for. This is important for tracking the nature of each reimbursement line in the payroll system. | |
| ReimbursementLine_ExpenseAccount | String | False |
The account from which the reimbursement is paid. This ensures that the financial transaction for the reimbursement is recorded in the correct expense account in the company's accounting system. | |
| ReimbursementLine_Amount | Decimal | False |
The amount of the reimbursement. This is the dollar value being reimbursed to the employee and should match the amount on the payslip for proper payroll and financial tracking. | |
| TenantId | String | False |
The unique identifier for the tenant (organization) in Xero. This ensures the reimbursement data is associated with the correct organization, enabling accurate payroll and financial reporting across multiple tenants or organizations. |
Manages payslip superannuation line items. Superannuation refers to the employer's contribution to an employee's retirement fund.
This table supports the following operators server-side: =,IN
To insert a single row, set the required fields. The Cloud adds a new superannuation line to the payslip.
INSERT INTO PaySlipSuperannuations (PayslipID, SuperannuationLine_SuperMembershipId, SuperannuationLine_ContributionType, SuperannuationLine_CalculationType, SuperannuationLine_Amount, SuperannuationLine_ExpenseAccountCode, SuperannuationLine_LiabilityAccountCode, SuperannuationLine_Percentage, SuperannuationLine_PaymentDateForThisPeriod) VALUES ('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', '045ef1ba-1399-4b49-b324-8c8b70d05607', 'SGC', 'PERCENTAGEOFEARNINGS', 9, '478', '826', 9.0, '2023-06-28')
INSERT INTO PaySlipSuperannuations (PayslipID, SuperannuationLine_SuperMembershipId, SuperannuationLine_ContributionType, SuperannuationLine_CalculationType, SuperannuationLine_Amount, SuperannuationLine_ExpenseAccountCode, SuperannuationLine_LiabilityAccountCode, SuperannuationLine_Percentage, SuperannuationLine_PaymentDateForThisPeriod)
VALUES
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', '045ef1ba-1399-4b49-b324-8c8b70d05607', 'SGC', 'PERCENTAGEOFEARNINGS', 9, '478', '826', 9.0, '2023-06-28'),
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', '045ef1ba-1399-4b49-b324-8c8b70d05607', 'SGC', 'PERCENTAGEOFEARNINGS', 12, '512', '904', 11.0, '2023-06-28')
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
UPDATE PaySlipSuperannuations SET SuperannuationLine_Percentage = 10 WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
Supply the Id to delete payslip superannuation lines.
DELETE FROM PaySlipSuperannuations WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
| Name | Type | ReadOnly | Filterable | Description |
| Id [KEY] | String | True |
The earnings line-item identifier that combines the specific payslip's unique Xero identifier with the earnings line details, helping to uniquely identify each line item within a payslip. | |
| PayslipID | String | False |
The unique identifier for a specific payslip, assigned by Xero. This identifier ensures each payslip is distinctly recognized and can be individually processed or queried in payroll systems. | |
| EmployeeID | String | True |
The unique identifier assigned to the employee associated with the payslip. This links the payslip to the employee, ensuring the payroll information is correctly attributed. | |
| SuperannuationLine_SuperMembershipId | String | False |
The unique identifier for the superannuation membership tied to this line item. It links the employee's superannuation details, including their super fund, to the respective payslip entry. | |
| SuperannuationLine_ContributionType | String | False |
The type of superannuation contribution for the employee, such as the mandatory super contribution or any additional contributions made by the employer. | |
| SuperannuationLine_CalculationType | String | False |
The method used to calculate the superannuation contribution, such as a percentage of the employee's earnings or a fixed amount based on predefined rules. | |
| SuperannuationLine_MinimumMonthlyEarnings | Decimal | False |
The minimum earnings threshold required for the employee to be eligible for superannuation contributions in a given month. This ensures that contributions are only made if the employee meets the earnings threshold. | |
| SuperannuationLine_ExpenseAccountCode | String | False |
The account code assigned to the superannuation expense. This code corresponds to the account in the chart of accounts where the superannuation contribution is recorded. | |
| SuperannuationLine_LiabilityAccountCode | String | False |
The account code assigned to the superannuation liability. This code corresponds to the liability account where the employer's superannuation obligations are tracked until paid. | |
| SuperannuationLine_PaymentDateForThisPeriod | Date | False |
The date on which the superannuation payment for the current period is due or was made. This ensures accurate tracking of payment dates for superannuation contributions. | |
| SuperannuationLine_Percentage | Double | False |
The percentage rate of the employee's salary that is contributed to their superannuation fund. This percentage is typically governed by government regulations or company policy. | |
| SuperannuationLine_Amount | Decimal | False |
The actual dollar amount of superannuation contributed to the employee's super fund for this specific period. This is calculated based on the percentage or fixed amount contribution type. | |
| TenantId | String | False |
The unique identifier for the tenant (organization) in Xero. This ensures the payslip's superannuation details are linked to the correct organization and payroll system. |
Tracks tax-related line items in payslips. It includes information on the tax deductions applied to an employee's pay, such as income tax and other levies.
This table supports the following operators server-side: =,IN
To insert a single row, set the required fields. The Cloud adds a new tax line to the payslip.
INSERT INTO PaySlipTaxes (PayslipID, TaxLine_Amount) VALUES ('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 5)
INSERT INTO PaySlipTaxes (PayslipID, TaxLine_Amount)
VALUES
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 5),
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 8)
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
UPDATE PaySlipTaxes SET TaxLine_Amount = 10 WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
Supply the Id to delete payslip tax lines.
DELETE FROM PaySlipTaxes WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
| Name | Type | ReadOnly | Filterable | Description |
| Id [KEY] | String | True |
The earnings line-item identifier that combines the specific payslip's unique Xero identifier with the tax line item details, uniquely identifying each tax line entry within a payslip. | |
| PayslipID | String | False |
The unique identifier for a specific payslip, assigned by Xero. This ensures that each payslip is individually identifiable and can be uniquely processed or queried in payroll systems. | |
| EmployeeID | String | True |
The unique identifier for the employee associated with the payslip, linking the tax line to the specific employee's pay records. | |
| TaxLine_TaxTypeName | String | False |
The name of the tax type associated with this line item, such as income tax, payroll tax, or other relevant taxes, which helps in classifying the type of tax applied. | |
| TaxLine_Description | String | False |
A description that provides details on the nature of the tax applied to this line item, helping to clarify the type or reason for the tax. | |
| TaxLine_Amount | Decimal | False |
The actual amount of tax applied to the employee's earnings for this line item, calculated based on the tax rate and relevant tax rules. | |
| TaxLine_LiabilityAccount | String | False |
The account code assigned to track the liability of the tax owed. This account is used to manage the amounts due for payment to tax authorities. | |
| TenantId | String | False |
The unique identifier for the tenant (organization) in Xero. This ensures the tax line item is linked to the correct organization's payroll system and tenant information. |
Manages payslip timesheet earnings line items. It tracks earnings that are calculated based on time worked, such as hourly wages or overtime.
This table supports the following operators server-side: =,IN
To insert a single row, set the required fields. The Cloud adds a new timesheet earnings line to the payslip.
INSERT INTO PaySlipTimesheetEarnings (PayslipID, TimesheetEarningsLine_EarningsRateId, TimesheetEarningsLine_RatePerUnit, TimesheetEarningsLine_NumberOfUnits) VALUES ('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 'c8602c7c-5f6f-433e-b7a7-bcbbd8386818', 32, 10)
INSERT INTO PaySlipTimesheetEarnings (PayslipID, TimesheetEarningsLine_EarningsRateId, TimesheetEarningsLine_RatePerUnit, TimesheetEarningsLine_NumberOfUnits)
VALUES
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 'c8602c7c-5f6f-433e-b7a7-bcbbd8386818', 32, 10),
('ea5aaaa7-c330-41d8-bfae-98ddc1f37680', 'c8602c7c-5f6f-433e-b7a7-bcbbd8386818', 36, 12)
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
UPDATE PaySlipTimesheetEarnings SET TimesheetEarningsLine_NumberOfUnits = 5 WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
Supply the Id to delete timesheet earnings lines.
DELETE FROM PaySlipTimesheetEarnings WHERE Id = '2|ea5aaaa7-c330-41d8-bfae-98ddc1f37680'
| Name | Type | ReadOnly | Filterable | Description |
| Id [KEY] | String | True |
The earnings line-item identifier that combines the unique Xero identifier of the payslip with the specific timesheet earnings line details. This ensures each timesheet earnings line can be uniquely referenced within the payslip. | |
| PayslipID | String | False |
The unique identifier of the payslip, assigned by Xero. This identifier is used to link each timesheet earnings line to a specific payslip for processing and record-keeping. | |
| EmployeeID | String | True |
The unique identifier of the employee associated with the payslip. This links the timesheet earnings line to a specific employee's pay details. | |
| TimesheetEarningsLine_EarningsRateId | String | False |
The unique identifier of the earnings rate associated with this line item. This specifies the rate at which the employee is compensated for the time worked, whether it's based on hourly, unit, or salary rate. | |
| TimesheetEarningsLine_RatePerUnit | Decimal | False |
The rate per unit of time worked (such as hourly wage) for this line item. This amount is used to calculate the earnings based on the number of time units worked. | |
| TimesheetEarningsLine_NumberOfUnits | Decimal | False |
The number of time units worked (such as hours worked) for this timesheet earnings line. This value, when multiplied by the rate per unit, determines the total earnings for this line item. | |
| TenantId | String | False |
The unique identifier of the tenant (organization) in Xero. This ensures the timesheet earnings line is correctly associated with the appropriate organization's payroll system and tenant information. |
Used to manage payroll super funds for employees. It tracks the superannuation funds to which employees are contributing for their retirement savings.
| Name | Type | ReadOnly | Filterable | Description |
| SuperFundID [KEY] | String | True |
The unique Xero-assigned identifier for the superannuation fund. | |
| Type | String | False |
The type of the superannuation fund. Possible values are 'REGULATED' for standard super funds or 'SMSF' for Self-Managed Super Funds. | |
| Name | String | False |
The name of the superannuation fund. | |
| ABN | String | False |
The Australian Business Number (ABN) associated with the superannuation fund. | |
| USI | String | False |
The Unique Superannuation Identifier (USI) for a regulated super fund, used for identifying the fund within the system. | |
| BSB | String | False |
The Bank State Branch (BSB) number, used for self-managed super funds, to identify the financial institution where the fund is held. | |
| AccountNumber | String | False |
The account number associated with a self-managed super fund (SMSF). | |
| AccountName | String | False |
The name of the account for a self-managed super fund. | |
| ElectronicServiceAddress | String | False |
The electronic service address for the self-managed super fund, used for communication and transactions. | |
| EmployerNumber | String | False |
A number assigned by some super funds to each employer for identification purposes. | |
| SPIN | String | False |
The Superannuation Product Identification Number (SPIN) for a regulated super fund. This is deprecated. | |
| UpdatedDateUTC | Datetime | False |
The date and time when this row was last updated in UTC format. | |
| TenantId | String | False |
The ID of the tenant (organization) to query, instead of the connection tenant. |
Used to query, insert, and update timesheets for a Xero organization. Timesheets record the hours worked by employees, which are used to calculate pay for hourly workers.
The Timesheets table allows you to SELECT, INSERT and UPDATE timesheet lines for a Xero organization. The Id column is generated by the Cloud; the value of this field combines the index of the line item with the unique, Xero-generated TimesheetID.
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.
To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new timesheet, the EmployeeID, StartDate and EndDate fields are required.
In addition to inserting a single row, line item tables offer two additional ways to insert into a table.
INSERT INTO Timesheets (EmployeeID, StartDate, EndDate, TimesheetLineAggregate) VALUES (
'XXXXX-XXXXX-XXXXX-XXXXX',
'2021-01-01',
'2021-01-07',
'<TimesheetLine>
<EarningsRateID>YYYYY-YYYYY-YYYYY-YYYYY</EarningsRateID>
<NumberOfUnits>
<NumberOfUnit>8</NumberOfUnit>
<NumberOfUnit>7</NumberOfUnit>
<NumberOfUnit>8</NumberOfUnit>
<NumberOfUnit>6</NumberOfUnit>
<NumberOfUnit>9</NumberOfUnit>
</TimesheetLine>
<TimesheetLine>
<EarningsRateID>ZZZZZ-ZZZZZ-ZZZZZ-ZZZZZ</EarningsRateID>
...
</TimesheetLine>'
)INSERT INTO Timesheets (TimesheetID, Line_EarningsRateID, Line_NumberOfUnits_NumberOfUnit1, Line_NumberOfUnits_NumberOfUnit2, ...) VALUES ('XXXXX-XXXXX-XXXXX-XXXXX', 'YYYYY-YYYYY-YYYYY-YYYYY', 8, 7, ...)Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
You can update any field that is not read-only.
Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.
The Xero API has limited support for deleting any object. In order to delete objects, you must update their Status to an appropriate value.
Applicable values for this field may be state-dependent. For example, invoices can only have their status set to DELETED when the invoice status is currently DRAFT or SUBMITTED.
| Name | Type | ReadOnly | Filterable | Description |
| Id [KEY] | String | True |
A unique identifier for the timesheet line-item, combined with the unique Xero identifier of the timesheet, used to reference each specific line within a timesheet. | |
| TimesheetID | String | True |
The unique identifier for the overall timesheet to which this line item belongs, assigned by Xero when the timesheet is created. | |
| EmployeeID | String | False |
The unique identifier of the employee associated with the timesheet line. This ID links the timesheet entry to a specific employee. | |
| StartDate | Date | False |
The start date for the timesheet period, indicating when the work period began. | |
| EndDate | Date | False |
The end date for the timesheet period, indicating when the work period concluded. | |
| Status | String | False |
The status of the timesheet, with valid values being 'DRAFT' (timesheet is not finalized), 'PROCESSED' (timesheet has been processed), and 'APPROVED' (timesheet is approved for payroll). | |
| Hours | Double | False |
The total number of hours worked by the employee for this timesheet line, indicating the amount of time recorded during the period. | |
| Line_EarningsRateId | String | False |
The unique Xero identifier for the earnings type associated with the timesheet line, which links the line to a specific earnings rate such as hourly or salary. | |
| Line_TrackingItemId | String | False |
The unique Xero identifier for a tracking category and option used in the timesheet, linking this timesheet entry to a specific tracking item (for example, department or project). | |
| Line_WorkLocationId | String | False |
The unique Xero identifier for the work location related to the timesheet line, which specifies where the work was performed. | |
| Line_NumberOfUnits_NumberOfUnit1 | String | False |
The number of units worked in the first unit of time for the timesheet line (for example, hours or shifts). | |
| Line_NumberOfUnits_NumberOfUnit2 | String | False |
The number of units worked in the second unit of time for the timesheet line (for example, hours or shifts). | |
| Line_NumberOfUnits_NumberOfUnit3 | String | False |
The number of units worked in the third unit of time for the timesheet line (for example, hours or shifts). | |
| Line_NumberOfUnits_NumberOfUnit4 | String | False |
The number of units worked in the fourth unit of time for the timesheet line (for example, hours or shifts). | |
| Line_NumberOfUnits_NumberOfUnit5 | String | False |
The number of units worked in the fifth unit of time for the timesheet line (for example, hours or shifts). | |
| Line_NumberOfUnits_NumberOfUnit6 | String | False |
The number of units worked in the sixth unit of time for the timesheet line (for example, hours or shifts). | |
| Line_NumberOfUnits_NumberOfUnit7 | String | False |
The number of units worked in the seventh unit of time for the timesheet line (for example, hours or shifts). | |
| Line_UpdatedDateUTC | Datetime | True |
The timestamp indicating when the timesheet line was last updated, useful for tracking modifications to the timesheet data. | |
| TimesheetLineAggregate | String | False |
A parameter used to define the timesheet line items as aggregated XML values, typically provided when inserting new records into the system. | |
| TenantId | String | False |
The unique identifier for the tenant to query instead of the connection tenant, used to specify the tenant in multi-tenant setups. |
Views are similar to tables in the way that data is represented; however, views are read-only.
Queries can be executed against a view as if it were a normal table.
| Name | Description |
| EmployeeBankAccounts | Queries the bank accounts associated with an employee. It is used to track the employee's payment details and manage their salary or reimbursement payments. |
| EmployeePayTemplateDeductions | Queries the deduction lines of the employee's pay template. It is used to manage and track various types of deductions, such as tax, superannuation, and garnishments. |
| EmployeePayTemplateEarnings | Queries the earnings lines of the employee's pay template. It helps track different types of earnings, such as regular wages, bonuses, and commissions. |
| EmployeePayTemplateLeave | Allows querying the leave lines in an employee's pay template. Leave lines track the employee's leave entitlements, such as annual, sick, and other leave types. |
| EmployeePayTemplateReimbursements | Queries the reimbursement lines in an employee's pay template. Reimbursements cover employee expenses that are paid back by the organization. |
| EmployeePayTemplateSupers | Queries the superannuation lines in an employee's pay template. Superannuation refers to the retirement savings the organization is required to contribute to on behalf of the employee. |
| LeaveBalances | Queries the leave balance for an employee, showing how much leave they have accrued and used, as well as how much leave is available for future use. |
| PaySlipLeaveEarnings | Queries the leave earnings line items for a payslip. Leave earnings refer to the pay associated with leave taken by the employee, such as annual leave or sick leave. |
| PaySlips | Allows querying payslips for a Xero organization. Payslips provide detailed breakdowns of employee pay, deductions, taxes, and other compensations for a specific pay period. |
| Tenants | Queries the list of organizations connected to your Xero account. Tenants represent different Xero organizations that the user has access to, each having its own data and configuration. |
Queries the bank accounts associated with an employee. It is used to track the employee's payment details and manage their salary or reimbursement payments.
| Name | Type | Filterable | Description |
| EmployeeID | String | The unique identifier for the employee. This field is automatically assigned by Xero. | |
| StatementText | String | The text that will appear on the employee's bank statement, providing details about the payment. | |
| AccountName | String | The name of the employee's bank account. | |
| BSB | String | Bank State Branch (BSB) number for the employee's bank account, required for Australian accounts. | |
| AccountNumber | String | The account number of the employee's bank account. | |
| Remainder | Boolean | Indicates whether the remaining part of the employee's salary should be transferred to this account. If true, this account will receive the remainder of the salary after other allocations. | |
| Amount | Decimal | A fixed amount of the employee's salary to be transferred to this account. This value must be less than or equal to the total salary amount. | |
| TenantId | String | The unique identifier for the tenant. This allows the query to target a specific tenant, overriding the connection's default tenant. |
Queries the deduction lines of the employee's pay template. It is used to manage and track various types of deductions, such as tax, superannuation, and garnishments.
| Name | Type | Filterable | Description |
| EmployeeID | String | The unique identifier for the employee. This field is automatically assigned by Xero. | |
| DeductionTypeID | String | The unique identifier for the deduction rate applied to this specific line item. It links to a predefined deduction type. | |
| CalculationType | String | Specifies the method of calculation for the deduction. Possible values are 'FIXEDAMOUNT' (a set amount), 'PRETAX' (deduction before tax), or 'POSTTAX' (deduction after tax). | |
| Percentage | Decimal | The percentage rate for the deduction, used when 'PRETAX' or 'POSTTAX' calculation types are applied. | |
| Amount | Decimal | The fixed deduction amount, used when the 'FIXEDAMOUNT' calculation type is applied. This is a specific monetary value. | |
| TenantId | String | The unique identifier for the tenant. This allows the query to target a specific tenant, overriding the connection's default tenant. |
Queries the earnings lines of the employee's pay template. It helps track different types of earnings, such as regular wages, bonuses, and commissions.
| Name | Type | Filterable | Description |
| EmployeeID | String | The unique identifier for the employee, automatically assigned by Xero. | |
| EarningsRateID | String | The unique identifier for the earnings rate applied to this line item. It links to a predefined earnings rate. | |
| CalculationType | String | Specifies how the earnings amount is calculated. Possible values are 'USEEARNINGSRATE' (uses the predefined earnings rate), 'ENTEREARNINGSRATE' (custom rate entered by the user), or 'ANNUALSALARY' (based on an annual salary). | |
| NumberOfUnitsPerWeek | Int | The number of hours the employee works per week, applicable only when the 'ANNUALSALARY' calculation type is used. | |
| AnnualSalary | Decimal | The annual salary of the employee, used when the 'ANNUALSALARY' calculation type is chosen. | |
| RatePerUnit | Decimal | The rate per unit of earnings (for example, hourly rate), used when 'USEEARNINGSRATE' or 'ENTEREARNINGSRATE' is selected. | |
| NormalNumberOfUnits | Decimal | The units of time (for example, hours worked) associated with the earnings line. | |
| TenantId | String | The unique identifier for the tenant, allowing the query to target a specific tenant instead of the default connection tenant. |
Allows querying the leave lines in an employee's pay template. Leave lines track the employee's leave entitlements, such as annual, sick, and other leave types.
| Name | Type | Filterable | Description |
| EmployeeID | String | The unique identifier for the employee, automatically assigned by Xero. | |
| LeaveTypeID | String | The unique identifier for the leave type applied to this leave line item. It links to a predefined leave type. | |
| CalculationType | String | Specifies how the leave amount is calculated. Possible values are 'FIXEDAMOUNTEACHPERIOD' (fixed leave accrual per period), 'ENTIRERATEINPAYTEMPLATE' (leave rate as per the pay template), or 'BASEDONORDINARYEARNINGS' (leave based on the employee's ordinary earnings). | |
| AnnualNumberOfUnits | Decimal | The total number of hours of leave accrued by the employee each year. | |
| FullTimeNumberOfUnitsPerPeriod | Decimal | The number of hours of leave accrued by the employee per pay period (for full-time employees). | |
| NumberOfUnits | Decimal | The fixed amount of leave (may be used for ad-hoc leave amounts). | |
| EntitlementFinalPayPayoutType | String | The type of payout for the employee's final leave entitlement. Possible values are 'NOTPAIDOUT' (leave not paid out) or 'PAIDOUT' (leave paid out). | |
| EmploymentTerminationPaymentType | String | The type of employment termination payment. Valid only if the 'EntitlementFinalPayPayoutType' is 'PAIDOUT'. Possible values are 'O' (Other) or 'R' (Resignation). | |
| IncludeSuperannuationGuaranteeContribution | Boolean | Indicates whether the Employment Termination Payment (ETP) leave earnings are subject to the Superannuation Guarantee Contribution (SGC). | |
| TenantId | String | The unique identifier for the tenant, allowing the query to target a specific tenant instead of the default connection tenant. |
Queries the reimbursement lines in an employee's pay template. Reimbursements cover employee expenses that are paid back by the organization.
| Name | Type | Filterable | Description |
| EmployeeID | String | The unique identifier for the employee, automatically assigned by Xero. | |
| ReimbursementTypeID | String | The unique identifier for the reimbursement type applied to this reimbursement line. It links to a predefined reimbursement type. | |
| Description | String | A description of the reimbursement line, explaining the purpose or reason for the reimbursement. | |
| Amount | Decimal | The monetary amount of the reimbursement line, indicating how much is reimbursed to the employee. | |
| TenantId | String | The unique identifier for the tenant, allowing the query to target a specific tenant instead of the default connection tenant. |
Queries the superannuation lines in an employee's pay template. Superannuation refers to the retirement savings the organization is required to contribute to on behalf of the employee.
| Name | Type | Filterable | Description |
| EmployeeID | String | The unique identifier for the employee, automatically assigned by Xero. | |
| SuperMembershipID | String | The unique identifier of the superannuation fund that this line contributes to. It links the contribution to a specific fund. | |
| ContributionType | String | The type of contribution being made. Valid values include 'SGC' (Superannuation Guarantee Contribution), 'SALARYSACRIFICE', 'EMPLOYERADDITIONAL', and 'EMPLOYEE'. | |
| CalculationType | String | The method used to calculate the superannuation contribution. Valid values are 'FIXEDAMOUNT', 'PERCENTAGEOFEARNINGS', or 'STATUTORY'. | |
| ExpenseAccountCode | String | The account code for the expense account used for recording this superannuation contribution. | |
| LiabilityAccountCode | String | The account code for the liability account used for recording this superannuation contribution. | |
| MinimumMonthlyEarnings | Decimal | The minimum amount of earnings the employee must make in a month for this contribution line to take effect. | |
| Percentage | Decimal | The percentage of the employee's earnings that will be contributed to the superannuation fund, applicable for certain contribution types. | |
| TenantId | String | The unique identifier for the tenant, allowing the query to target a specific tenant instead of the default connection tenant. |
Queries the leave balance for an employee, showing how much leave they have accrued and used, as well as how much leave is available for future use.
| Name | Type | Filterable | Description |
| EmployeeID [KEY] | String | The unique identifier of the employee assigned by Xero. This ID links the leave records to a specific employee in the payroll and HR system. | |
| LeaveTypeID [KEY] | String | The unique identifier of the leave type assigned by Xero. This helps distinguish between various types of leave, such as annual leave or sick leave. | |
| LeaveName | String | The name of the leave type, such as 'Annual Leave', 'Sick Leave', or 'Compassionate Leave'. This allows for easy identification of the type of leave associated with the employee. | |
| NumberOfUnits | Double | The balance of leave available for the employee. This value represents how much of the specified leave the employee has remaining. | |
| TypeOfUnits | String | The unit type of the leave balance, such as 'Days', 'Hours', or 'Shifts'. This defines the unit of measurement for the leave and helps in accurate calculation and usage tracking. | |
| TenantId | String | The ID of the tenant (organization) to query instead of the connection tenant. This ensures that leave data is retrieved from the correct organization within Xero, particularly useful for companies with multiple tenants. |
Queries the leave earnings line items for a payslip. Leave earnings refer to the pay associated with leave taken by the employee, such as annual leave or sick leave.
| Name | Type | Filterable | Description |
| Id [KEY] | String | A unique identifier for the earnings line item, combining the specific line item and the Xero identifier of the associated payslip. This allows for precise identification of the leave earnings line in the payroll system. | |
| PayslipID | String | The unique identifier for the payslip, as assigned by Xero. This links the leave earnings line item to a specific payslip and ensures accurate payroll record keeping for the employee. | |
| EmployeeID | String | The unique identifier of the employee associated with this leave earnings line. This allows for the leave earnings to be tracked and reported against the correct employee's payslip. | |
| LeaveEarningsLine_EarningsRateId | String | The unique identifier of the earnings rate applied to the leave earnings line item. This rate determines how much the employee will earn for their leave time, usually expressed as a rate per unit of time (such as per hour). | |
| LeaveEarningsLine_RatePerUnit | Decimal | The hourly wage or rate of pay for the employee in this leave earnings line item. This represents the amount the employee earns for each unit of leave taken (usually per hour). | |
| LeaveEarningsLine_NumberOfUnits | Double | The number of hours of leave being taken or accrued in this line item. This value reflects the total leave time associated with this particular payslip for the employee. | |
| TenantId | String | The unique identifier for the tenant (or organization) in Xero. This helps ensure that the leave earnings data is associated with the correct organization and enables accurate payroll reporting across multiple tenants or organizations. |
Allows querying payslips for a Xero organization. Payslips provide detailed breakdowns of employee pay, deductions, taxes, and other compensations for a specific pay period.
| Name | Type | Filterable | Description |
| PayRunID | String | The unique identifier for the payrun, which encompasses all the payslips for a specific payroll cycle. This ID links all payslips under the same payrun and is crucial for organizing payroll information across multiple employees. | |
| PayslipID [KEY] | String | The unique identifier for a specific payslip, as assigned by Xero. This ensures that the payslip is distinctly identifiable and can be tracked separately within the payroll system. | |
| EmployeeID | String | The unique identifier assigned to each employee in Xero. This connects the payslip to the employee, ensuring that payroll data is correctly attributed to the right person. | |
| FirstName | String | The first name of the employee, as recorded in Xero. This field helps identify the employee when reviewing or generating payslips for individual workers. | |
| LastName | String | The last name of the employee, as recorded in Xero. This is another identifier used to differentiate employees and is included on payslips for clarity. | |
| EmployeeGroup | String | The name of the group or department the employee belongs to, as defined by the employer in the payroll system. This can be used to categorize employees for payroll or reporting purposes. | |
| LastEdited | Datetime | The timestamp of the most recent modification to the payslip. This allows for tracking and auditing of any changes made to the payslip after it was initially created. | |
| Wages | Decimal | The total wages earned by the employee during the pay period. This is the sum of regular earnings and any applicable allowances or bonuses, minus any deductions. | |
| Deductions | Decimal | The total amount of deductions applied to the employee's wages, such as taxes, retirement contributions, and other withholdings as per the employee's pay details. | |
| NetPay | Decimal | The total amount the employee takes home after all deductions are subtracted from the gross wages. This is the final pay amount the employee receives for the pay period. | |
| Tax | Decimal | The total tax withheld from the employee's wages, including income tax and other statutory taxes, as required by the relevant government regulations. | |
| Super | Decimal | The total superannuation contributions made on behalf of the employee, as required by the employer's superannuation obligations. This is typically a percentage of the employee's wages. | |
| Reimbursements | Decimal | The total amount of reimbursements included in the payslip, covering expenses that the employee incurred during the pay period that are being reimbursed by the employer. | |
| TenantId | String | The unique identifier for the tenant (organization) in Xero. This ensures that the payslip is associated with the correct organization and enables accurate payroll processing across multiple organizations or entities. |
Queries the list of organizations connected to your Xero account. Tenants represent different Xero organizations that the user has access to, each having its own data and configuration.
| Name | Type | Filterable | Description |
| TenantId [KEY] | String | A unique identifier assigned to each tenant (organization or practice) within the system, used to distinguish between different entities. | |
| Name | String | The name of the organization or practice associated with the tenant. This is the primary name displayed for identification purposes. | |
| Type | String | The type of the tenant. This can either be 'organisation' or 'practice', depending on whether the tenant is a business or a professional practice. | |
| IsActive | Boolean | Indicates the current status of the tenant's connection. If set to true, the connection is active and in use; if false, the tenant is inactive and not currently in use. |
Stored procedures are function-like interfaces that extend the functionality of the Cloud beyond simple SELECT/INSERT/UPDATE/DELETE operations with Xero.
Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from Xero, along with an indication of whether the procedure succeeded or failed.
| Name | Description |
| GetLimitInfo | Retrieves limit information, helping monitor API usage and limits for making calls against a specific tenant. |
| RevokeTenant | Revokes the tenant connection, requiring the user to reauthorize next time they attempt to connect to that tenant. |
Retrieves limit information, helping monitor API usage and limits for making calls against a specific tenant.
This procedure reports information that the Cloud caches after each API request. If no requests have been made to a tenant on a connection than this procedure will report 0 rows. Otherwise, the LastModified field reports the last time the information in the row was updated.
If the last modified time is too long ago for your application to use, then this table may be refreshed by executing a query.
The query must read at least one row to ensure that an API request is triggered:
SELECT * FROM PayRuns LIMIT 1
| Name | Type | Description |
| TenantId | String | ID of the tenant that the limit applies to. The output contains a row for each tenant queried during the connection. Usually there is only one. |
| AppRemaining | Integer | The number of API calls the current OAuth app has this minute (max 10000). This applies across all tenants. |
| MinuteRemaining | Integer | The number of API calls the current OAuth app has this minute (max 60). This applies only to this tenant. |
| DayRemaining | Integer | The number of API calls the current OAuth app has today (max 5000). This applies only to this tenant. |
| RetryAfter | Integer | The suggested retry time, if one of the above limits was 0 on the most recent API call to the tenant. |
| LastModified | Datetime | When this information was last updated. The values in this table are only refreshed when performing API calls, so this may be older than the current time. |
Revokes the tenant connection, requiring the user to reauthorize next time they attempt to connect to that tenant.
| Name | Type | Required | Description |
| TenantId | String | False | The unique identifier of the tenant (organization) for which the connection should be revoked. This ID is retrieved from the Tenants view and is used to specify the tenant for which the operation will be performed. |
| Name | Type | Description |
| Success | String | A boolean value indicating whether the connection to the specified tenant was successfully revoked. A value of 'true' means the connection was revoked successfully, while 'false' indicates that the operation failed. |
The CData Cloud models the Xero Files API as an easy-to-use SQL database. There are three parts to the data model: tables, views, and stored procedures.
API limitations and requirements are documented in this section; you can use the SupportEnhancedSQL feature, set by default, to circumvent most of these limitations.
The tables include:
| Table | Description |
| Associations | Manages the associations of files within Xero, including how files are linked to other entities (such as contacts, invoices, or projects). It allows for querying, inserting, and deleting associations between files and records. |
| Files | Stores and manages files in Xero. It allows you to query, update, and delete files, such as invoices, receipts, and contracts. It provides functionality for managing digital documents attached to various records. |
| Folders | Manages folders within Xero's file storage system. It allows for the organization and management of files into categories. |
| Tenants | Queries the list of organizations (tenants) connected to your Xero account. Each tenant corresponds to a specific Xero organization, enabling access to their data for file management. |
API limitations and requirements are documented in each table.
Stored Procedures are actions that are invoked via SQL queries. They perform tasks beyond standard create, read, update, delete (CRUD) operations, including managing file uploads and downloads, and OAuth tokens.
The Cloud models the data in Xero as a list of tables in a relational database that can be queried using standard SQL statements.
| Name | Description |
| Associations | Manages the associations of files within Xero, including how files are linked to other entities (such as contacts, invoices, or projects). It allows for querying, inserting, and deleting associations between files and records. |
| Files | Stores and manages files in Xero. It allows you to query, update, and delete files, such as invoices, receipts, and contracts. It provides functionality for managing digital documents attached to various records. |
| Folders | Manages folders within Xero's file storage system. It allows for the organization and management of files into categories. |
Manages the associations of files within Xero, including how files are linked to other entities (such as contacts, invoices, or projects). It allows for querying, inserting, and deleting associations between files and records.
To create an Association, everything but the Id and ObjectType must be provided:
INSERT INTO Associations (FileId, ObjectId, ObjectGroup)
VALUES ('2bf7b85c-7ed8-47b4-8559-d83f8f5f9b9c', '4819be2c-b3b7-43a2-80fe-ef479ad25351', 'Invoice')
Associations cannot be changed once they have been inserted. If you need to update an Association you must delete it and recreate it.
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | False |
A unique identifier combining the file and the object it is being associated with. |
| FileId | String | False |
The identifier of the file being associated with the object. |
| ObjectId | String | False |
The identifier of the object being linked to the file. |
| ObjectGroup | String | False |
The accounting entity to which the object should be attached, such as a specific department or division. |
| ObjectType | String | True |
A more specific category or classification that the object belongs to, providing further context for its type. |
| TenantId | String | False |
The ID of the tenant to query instead of the connection tenant, enabling tenant-specific queries. |
Stores and manages files in Xero. It allows you to query, update, and delete files, such as invoices, receipts, and contracts. It provides functionality for managing digital documents attached to various records.
If you need to interact with file contents (either uploading or downloading them), please see the Files stored procedures.
| Name | Type | ReadOnly | Description |
| FileId [KEY] | String | True |
The unique identifier assigned by Xero for the file. |
| Name | String | False |
The name of the file as stored in Xero. |
| FolderId | String | False |
The ID of the folder containing the file, representing its location within the system. |
| MimeType | String | True |
The mime type of data contained in the file. |
| Size | Int | True |
The size of the file in bytes, representing the file's storage consumption. |
| User_Id | String | True |
The unique identifier for the user who uploaded the file. |
| User_Name | String | True |
The username of the individual who uploaded the file. |
| User_FirstName | String | True |
The first name of the user who uploaded the file. |
| User_LastName | String | True |
The last name of the user who uploaded the file. |
| User_FullName | String | True |
The full name (first and last) of the user who uploaded the file. |
| Created | Datetime | True |
The timestamp when the file was first uploaded to Xero. |
| Updated | Datetime | True |
The timestamp when the file's metadata was last updated or modified. |
| TenantId | String | False |
The unique identifier of the tenant to query, used instead of the connection tenant. |
Manages folders within Xero's file storage system. It allows for the organization and management of files into categories.
A Name has to be provided when creating a Folder:
INSERT INTO Folders (Name) VALUE ('Legal Documents')
| Name | Type | ReadOnly | Description |
| FolderId [KEY] | String | True |
The unique Xero-generated identifier for the folder. |
| Name | String | False |
The name of the folder, which represents its label or title in Xero. |
| FileCount | Integer | True |
The total number of files that are currently stored in this folder. |
| IsInbox | Boolean | True |
Indicates if this folder is the inbox, which is automatically created by Xero and cannot be modified or deleted. |
| String | True |
The email address that is linked to the folder, enabling the upload of files directly to this folder. This is only available for the Inbox. | |
| TenantId | String | False |
The unique identifier for the tenant, used to query data instead of the default connection tenant. |
Views are similar to tables in the way that data is represented; however, views are read-only.
Queries can be executed against a view as if it were a normal table.
| Name | Description |
| Tenants | Queries the list of organizations (tenants) connected to your Xero account. Each tenant corresponds to a specific Xero organization, enabling access to their data for file management. |
Queries the list of organizations (tenants) connected to your Xero account. Each tenant corresponds to a specific Xero organization, enabling access to their data for file management.
| Name | Type | Description |
| TenantId [KEY] | String | A unique identifier assigned to the tenant, used to distinguish different organizations or practices in the system. |
| Name | String | The name of the organization or practice associated with the tenant. This field represents the official name of the entity. |
| Type | String | Specifies whether the tenant is classified as an organization or a practice. This helps in categorizing the tenant based on its role or structure. |
| IsActive | Boolean | Indicates whether the tenant connection is currently active. If the value is 'true', the connection is active; if the value is 'false', the connection is inactive. |
Stored procedures are function-like interfaces that extend the functionality of the Cloud beyond simple SELECT/INSERT/UPDATE/DELETE operations with Xero.
Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from Xero, along with an indication of whether the procedure succeeded or failed.
| Name | Description |
| GetLimitInfo | Retrieves limit information related to the Xero API, helping to monitor how many API calls remain available for the current tenant within the allowed limits. |
| RevokeTenant | Disconnects the specified tenant from the application. After this operation, the user must reauthorize their connection to the tenant the next time they interact with the app. |
Retrieves limit information related to the Xero API, helping to monitor how many API calls remain available for the current tenant within the allowed limits.
This procedure reports information that the Cloud caches after each API request. If no requests have been made to a tenant on a connection than this procedure will report 0 rows. Otherwise, the LastModified field reports the last time the information in the row was updated.
If the last modified time is too long ago for your application to use, then this table may be refreshed by executing a query.
The query must read at least one row to ensure that an API request is triggered:
SELECT * FROM Files LIMIT 1
| Name | Type | Description |
| TenantId | String | The unique identifier of the tenant that the API rate limit applies to. A row will be returned for each tenant queried during the connection, although typically there is only one tenant. |
| AppRemaining | Integer | The remaining number of API calls available to the current OAuth app for this minute (maximum 10,000). This limit applies across all tenants. |
| MinuteRemaining | Integer | The remaining number of API calls available to the current OAuth app for the current minute (maximum 60). This limit is specific to this tenant. |
| DayRemaining | Integer | The remaining number of API calls available to the current OAuth app for today (maximum 5,000). This limit is specific to this tenant. |
| RetryAfter | Integer | The recommended time to wait before retrying the API call, in the event that one of the above limits was reached. |
| LastModified | Datetime | The timestamp of when the rate limit information was last updated. This data is only refreshed when performing API calls, so it may be older than the current time. |
Disconnects the specified tenant from the application. After this operation, the user must reauthorize their connection to the tenant the next time they interact with the app.
| Name | Type | Required | Description |
| TenantId | String | False | The unique identifier of the tenant to revoke, as provided in the Tenants view. This value is used to identify and revoke the connection for the specific tenant. |
| Name | Type | Description |
| Success | String | Indicates whether the connection was successfully revoked. A boolean value that is true if the operation was successful, false if it was not. |
API limitations and requirements are documented in this section; you can use the SupportEnhancedSQL feature, set by default, to circumvent most of these limitations.
The Tables section, which details standard SQL tables, and the Views section, which lists read-only SQL tables, contain samples of what you might have access to in your Xero account.
The tables include:
| Table | Description |
| Assets | Stores and manages asset records within Xero. It enables querying, inserting, and updating asset data, such as purchase price, asset type, depreciation settings, and more. |
| AssetTypes | Defines asset types in Xero. It enables querying, inserting, and updating different asset categories used in asset management, such as vehicles, property, and equipment. |
| Settings | Provides access to asset-related settings within Xero, including default asset settings for the organization. It helps with configuring asset management preferences. |
| Tenants | Queries the list of organizations (tenants) connected to your Xero account. It provides basic details about each organization, including ID and status, for asset management. |
API limitations and requirements are documented in each table.
Stored Procedures are actions that are invoked via SQL queries. They perform tasks beyond standard create, read, update, delete (CRUD) operations, including managing OAuth tokens.
The Cloud models the data in Xero as a list of tables in a relational database that can be queried using standard SQL statements.
| Name | Description |
| Assets | Stores and manages asset records within Xero. It enables querying, inserting, and updating asset data, such as purchase price, asset type, depreciation settings, and more. |
| AssetTypes | Defines asset types in Xero. It enables querying, inserting, and updating different asset categories used in asset management, such as vehicles, property, and equipment. |
Stores and manages asset records within Xero. It enables querying, inserting, and updating asset data, such as purchase price, asset type, depreciation settings, and more.
An asset can be created with only an AssetName and an AssetNumber. This will create a draft asset with blank settings for purchase date and price, serial number and all other values.
INSERT INTO Assets (AssetName, AssetNumber) VALUES ('Corporate van', 'FA-0042')
UPDATE Assets
SET BookDepreciationSetting_DepreciationRate = 0.12,
BookDepreciationSetting_EffectiveLifeYears = null
WHERE AssetId = '46c7f1f4-7cdb-47d3-8772-2796d0b83e87'
To move an asset from the draft to the registered state, you must assign these properties on it:
Then you can update the AssetStatus field to the value "Registered".
Disposing of assets is not supported through the API.
| Name | Type | ReadOnly | Description |
| AssetId [KEY] | String | True |
The unique identifier generated by Xero for the asset. |
| AssetName | String | False |
The name given to the asset in the system. |
| AssetNumber | String | False |
A unique code or reference number assigned to the asset. |
| AssetStatus | String | False |
The current status of the asset. Valid values are 'DRAFT', 'REGISTERED', or 'DISPOSED'. |
| Description | String | False |
A field for any free-form comments or additional information regarding the asset. |
| PurchaseDate | Date | False |
The date when the asset was acquired. |
| PurchasePrice | Decimal | False |
The cost of the asset at the time of purchase. |
| DisposalDate | Date | False |
The date when the asset was disposed of. |
| DisposalPrice | Decimal | False |
The price at which the asset was disposed of. |
| WarrantyExpiryDate | Date | False |
The date when the asset's warranty expires. |
| SerialNumber | String | False |
The asset's serial number, which can be used for tracking or identification. |
| AssetTypeId | String | False |
The identifier for the category or type of the asset. |
| BookDepreciationSetting_DepreciationMethod | String | False |
The method of depreciation applied to the asset. Options include: 'NoDepreciation', 'StraightLine', 'DiminishingValue100', 'DiminishingValue150', 'DiminishingValue200', or 'FullDepreciation'. |
| BookDepreciationSetting_AveragingMethod | String | False |
The method for calculating depreciation periods. Options include: 'ActualDays' or 'FullMonth'. |
| BookDepreciationSetting_DepreciationRate | Double | False |
The annual depreciation rate as a percentage. |
| BookDepreciationSetting_EffectiveLifeYears | Int | False |
The number of years over which the asset will be depreciated. |
| BookDepreciationSetting_DepreciationCalculationMethod | String | False |
The method used to calculate depreciation. Options include: 'Rate', 'Life', or 'None'. |
| BookDepreciationDetail_CurrentCapitalGain | Decimal | False |
The capital gain realized when the asset is disposed of, calculated as the disposal price minus the purchase price. |
| BookDepreciationDetail_CurrentGainLoss | Decimal | False |
The difference between the purchase price and the current book value, which represents the gain or loss. |
| BookDepreciationDetail_DepreciationStartDate | Date | False |
The date when depreciation on the asset begins. |
| BookDepreciationDetail_CostLimit | Decimal | False |
The maximum value of the asset to be depreciated, if it is less than the actual purchase price. |
| BookDepreciationDetail_ResidualValue | Decimal | False |
The estimated value of the asset after it has been fully depreciated. |
| BookDepreciationDetail_PriorAccumDepreciationAmount | Decimal | False |
The total depreciation accumulated on the asset before the current fiscal year. |
| BookDepreciationDetail_CurrentAccumDepreciationAmount | Decimal | False |
The depreciation amount accumulated during the current fiscal year. |
| CanRollBack | Boolean | True |
Indicates whether the depreciation on the asset can be reversed. |
| AccountingBookValue | Decimal | True |
The current accounting value of the asset, after accounting for depreciation. |
| TenantId | String | False |
The ID of the tenant to query instead of the connection tenant. |
Defines asset types in Xero. It enables querying, inserting, and updating different asset categories used in asset management, such as vehicles, property, and equipment.
An AssetType can be created with one of two methods of computing depreciation. The first is according to a fixed percentage (in this example, 0.15%):
INSERT INTO AssetTypes ( AssetTypeName, FixedAssetAccountId, DepreciationExpenseAccountId, AccumulatedDepreciationAccountId, BookDepreciationSetting_DepreciationMethod, BookDepreciationSetting_AveragingMethod, BookDepreciationSetting_DepreciationRate ) VALUES ( 'Vehicles', '8e968d1a-5e25-4dad-b6f9-c8f4d72c0cac', '20b36596-3d1d-4789-9f08-50c92d19d522', '2a9bb066-3398-40e8-a953-caaabed2b7a7', 'StraightLine', 'FullMonth', 0.15 )
Alternatively, you could create an asset type that depreciates according to an effective lifetime:
INSERT INTO AssetTypes ( AssetTypeName, FixedAssetAccountId, DepreciationExpenseAccountId, AccumulatedDepreciationAccountId, BookDepreciationSetting_DepreciationMethod, BookDepreciationSetting_AveragingMethod, BookDepreciationSetting_EffectiveLifeYears ) VALUES ( 'Vehicles', '8e968d1a-5e25-4dad-b6f9-c8f4d72c0cac', '20b36596-3d1d-4789-9f08-50c92d19d522', '2a9bb066-3398-40e8-a953-caaabed2b7a7', 'StraightLine', 'FullMonth', 12 )
UPDATE AssetTypes
SET BookDepreciationSetting_DepreciationRate = 0.09,
BookDepreciationSetting_EffectiveLifeYears = null
WHERE AssetTypeId = 'bf28b6ca-3cc6-4591-ac5a-2c1115f04b4b'
| Name | Type | ReadOnly | Description |
| AssetTypeId [KEY] | String | True |
The unique Xero-generated identifier for the asset type. |
| AssetTypeName | String | False |
The name of the asset type, used to categorize different types of assets. |
| FixedAssetAccountId | String | False |
The account used to track assets of this type in the general ledger. |
| DepreciationExpenseAccountId | String | False |
The expense account that records depreciation for assets of this type. |
| AccumulatedDepreciationAccountId | String | False |
The account used to track accumulated depreciation for assets of this type. |
| BookDepreciationSetting_DepreciationMethod | String | False |
The method of depreciation applied to assets of this type. Options include: 'NoDepreciation', 'StraightLine', 'DiminishingValue100', 'DiminishingValue150', 'DiminishingValue200', or 'FullDepreciation'. |
| BookDepreciationSetting_AveragingMethod | String | False |
The method used to average the depreciation periods. Options include: 'ActualDays' or 'FullMonth'. |
| BookDepreciationSetting_DepreciationRate | Decimal | False |
The annual depreciation rate applied to assets of this type, expressed as a percentage. |
| BookDepreciationSetting_EffectiveLifeYears | Int | False |
The number of years over which assets of this type will be depreciated. |
| BookDepreciationSetting_DepreciationCalculationMethod | String | True |
The method used to calculate depreciation for assets of this type. Options include: 'Rate', 'Life', or 'None'. |
| Locks | Int | True |
The number of assets currently using this asset type. This helps track how many assets are classified under this category. |
| TenantId | String | False |
The ID of the tenant to query instead of the connection tenant. |
Views are similar to tables in the way that data is represented; however, views are read-only.
Queries can be executed against a view as if it were a normal table.
| Name | Description |
| Settings | Provides access to asset-related settings within Xero, including default asset settings for the organization. It helps with configuring asset management preferences. |
| Tenants | Queries the list of organizations (tenants) connected to your Xero account. It provides basic details about each organization, including ID and status, for asset management. |
Provides access to asset-related settings within Xero, including default asset settings for the organization. It helps with configuring asset management preferences.
| Name | Type | Description |
| AssetNumberPrefix | String | The prefix used when generating fixed asset numbers for the organisation. |
| AssetNumberSequence | String | The next available sequential asset number for the organisation. |
| AssetStartDate | Date | The date on which Xero started calculating depreciation for fixed assets. |
| LastDepreciationDate | Date | The date when the most recent depreciation was calculated for fixed assets. |
| DefaultGainOnDisposalAccountId | String | The default account used to post gains on the disposal of fixed assets. |
| DefaultLossOnDisposalAccountId | String | The default account used to post losses on the disposal of fixed assets. |
| DefaultCapitalGainOnDisposalAccountId | String | The default account used to post capital gains from the disposal of fixed assets. |
| OptInForTax | Boolean | A boolean indicating whether the organisation has opted in for tax calculations related to fixed asset disposals. |
| TenantId | String | The ID of the tenant to query instead of the connection tenant. |
Queries the list of organizations (tenants) connected to your Xero account. It provides basic details about each organization, including ID and status, for asset management.
| Name | Type | Description |
| TenantId [KEY] | String | A unique identifier for the tenant, representing an organisation or practice in the system. |
| Name | String | The name of the organisation or practice associated with the tenant. |
| Type | String | Indicates whether the tenant represents an organisation or a practice. |
| IsActive | Boolean | Indicates whether the current connection is actively using this tenant. |
Stored procedures are function-like interfaces that extend the functionality of the Cloud beyond simple SELECT/INSERT/UPDATE/DELETE operations with Xero.
Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from Xero, along with an indication of whether the procedure succeeded or failed.
| Name | Description |
| GetLimitInfo | Retrieves API call limits for asset management. It allows you to monitor how many API calls are available to interact with the Xero assets data for the tenant. |
| RevokeTenant | Disconnects the specified tenant from the application. It revokes access and requires the user to reauthorize the next time they interact with the tenant's data. |
Retrieves API call limits for asset management. It allows you to monitor how many API calls are available to interact with the Xero assets data for the tenant.
This procedure reports information that the Cloud caches after each API request. If no requests have been made to a tenant on a connection than this procedure will report 0 rows. Otherwise, the LastModified field reports the last time the information in the row was updated.
If the last modified time is too long ago for your application to use, then this table may be refreshed by executing a query.
The query must read at least one row to ensure that an API request is triggered:
SELECT * FROM AssetTypes LIMIT 1
| Name | Type | Description |
| TenantId | String | The ID of the tenant to which the rate limits apply. The output contains a row for each tenant queried during the connection. Typically, only one tenant is involved. |
| AppRemaining | Integer | The remaining number of API calls the current OAuth app can make within this minute (maximum limit: 10,000). This applies across all tenants. |
| MinuteRemaining | Integer | The remaining number of API calls the current OAuth app can make within this minute (maximum limit: 60). This applies only to the specified tenant. |
| DayRemaining | Integer | The remaining number of API calls the current OAuth app can make today (maximum limit: 5,000). This applies only to the specified tenant. |
| RetryAfter | Integer | The suggested wait time before retrying the API call, in case the above limits were exceeded on the most recent request to the tenant. |
| LastModified | Datetime | The timestamp of the last update for this rate-limiting information. Note that this information is updated only when an API call is made, so it may be out-of-date. |
Disconnects the specified tenant from the application. It revokes access and requires the user to reauthorize the next time they interact with the tenant's data.
| Name | Type | Required | Description |
| TenantId | String | False | The unique ID of the tenant to revoke the connection for, as specified in the Tenants view. |
| Name | Type | Description |
| Success | String | A boolean indicating whether the connection to the specified tenant was successfully revoked. |
API limitations and requirements are documented in this section; you can use the SupportEnhancedSQL feature, set by default, to circumvent most of these limitations.
The Tables section, which details standard SQL tables, and the Views section, which lists read-only SQL tables, contain samples of what you might have access to in your Xero account.
The tables include:
| Table | Description |
| Projects | Manages projects in Xero, allowing you to query, insert, and update project data. Projects can be tracked for revenue, expenses, and time entries, allowing you to manage workflows and budgets. |
| Tasks | Stores and manages tasks associated with projects in Xero. You can query, insert, update, and delete tasks, which include details like task name, description, assigned personnel, and deadlines. |
| Time | Stores and manages time entries logged against projects and tasks. It allows for querying, inserting, updating, and deleting time records, which are essential for billing and resource management. |
| Tenants | Queries the list of organizations connected to your Xero account. It helps retrieve tenant details associated with project management and tracking. |
| Users | Queries the users associated with a specific project in Xero. It helps track who is working on a project and their roles, providing insights into team management and collaboration. |
API limitations and requirements are documented in each table.
Stored Procedures are actions that are invoked via SQL queries. They perform tasks beyond standard create, read, update, delete (CRUD) operations, including managing OAuth tokens.
The Cloud models the data in Xero as a list of tables in a relational database that can be queried using standard SQL statements.
| Name | Description |
| Projects | Manages projects in Xero, allowing you to query, insert, and update project data. Projects can be tracked for revenue, expenses, and time entries, allowing you to manage workflows and budgets. |
| Tasks | Stores and manages tasks associated with projects in Xero. You can query, insert, update, and delete tasks, which include details like task name, description, assigned personnel, and deadlines. |
| Time | Stores and manages time entries logged against projects and tasks. It allows for querying, inserting, updating, and deleting time records, which are essential for billing and resource management. |
Manages projects in Xero, allowing you to query, insert, and update project data. Projects can be tracked for revenue, expenses, and time entries, allowing you to manage workflows and budgets.
A Project must be created with a Name and ContactId. The ContactId comes from the ContactId column in the Contacts table of the Accounting API. An EstimateValue may also be provided to set the initial estimate for the project:
INSERT INTO Projects (Name, ContactId, Deadline, EstimateValue) VALUES ('Construct Parking Lot', '1c5ac798-1e31-4c09-82ac-4781261ff20a', '2025-01-01', 250000)
Once a project has been created, only its Deadline and EstimateValue may be updated:
UPDATE Projects SET Deadline = '2022-01-01', EstimateValue = 150000 WHERE ProjectId = '1de78bad-5a81-4cb8-ab53-5a1a3bc73b29'
| Name | Type | ReadOnly | Description |
| ProjectId [KEY] | String | True |
The unique identifier for the project in Xero. This field is generated by Xero to distinguish each project within the system. |
| ContactId | String | False |
The unique identifier of the contact for whom the project was created. This represents the client or business entity associated with the project. |
| Name | String | False |
The name of the project. This is typically a descriptive title given to the project to help identify its purpose or scope. |
| CurrencyCode | String | True |
The ISO code of the currency used within the project. This allows the project to be linked with a specific currency for transactions. |
| MinutesLogged | Int | True |
The total number of minutes logged across all tasks within the project. This is the cumulative time spent working on the project, recorded in minutes. |
| TotalTaskAmountValue | Decimal | True |
The total actual amount for each project task. This value represents the sum of all task-related charges or costs associated with the project. |
| TotalTaskAmountCurrency | String | True |
The currency in which the TotalTaskAmountValue is denominated. This allows different tasks to be measured in various currencies if necessary. |
| TotalExpenseAmountValue | Decimal | True |
The total actual amount for all expenses incurred in the project. This represents the sum of all costs tied to expenses for the project. |
| TotalExpenseAmountCurrency | String | True |
The currency of the TotalExpenseAmountValue, indicating the currency in which the total expenses are recorded. |
| MinutesToBeInvoiced | Int | True |
The total number of minutes for which work has been done but not yet invoiced. This helps track work that still needs to be billed. |
| TaskAmountToBeInvoicedValue | Decimal | True |
The total value of the tasks that have been worked on but not yet invoiced. This represents the amount to be billed for unfinished work. |
| TaskAmountToBeInvoicedCurrency | String | True |
The currency of the TaskAmountToBeInvoicedValue, which indicates the currency in which pending task amounts will be invoiced. |
| TaskAmountInvoicedValue | Decimal | True |
The total value of tasks that have been invoiced. This represents the amount billed to the client for completed tasks. |
| TaskAmountInvoicedCurrency | String | True |
The currency of the TaskAmountInvoicedValue, representing the currency in which invoiced tasks are billed. |
| ExpenseAmountToBeInvoicedValue | Decimal | True |
The total amount of project expenses that have been incurred but not yet invoiced. This represents pending charges for expenses. |
| ExpenseAmountToBeInvoicedCurrency | String | True |
The currency of the ExpenseAmountToBeInvoicedValue, indicating the currency of the pending expense amounts for the project. |
| ExpenseAmountInvoicedValue | Decimal | True |
The total amount of project expenses that have been invoiced. This value represents the billed amount for project expenses. |
| ExpenseAmountInvoicedCurrency | String | True |
The currency of the ExpenseAmountInvoicedValue, indicating the currency used for invoiced expenses. |
| ProjectAmountInvoicedValue | Decimal | True |
The total amount that has been invoiced across the entire project, including both tasks and expenses. |
| ProjectAmountInvoicedCurrency | String | True |
The currency of the ProjectAmountInvoicedValue, reflecting the currency in which the entire project has been invoiced. |
| DepositValue | Decimal | True |
The deposit value for the project. This represents an upfront payment made for the project. |
| DepositCurrency | String | True |
The currency of the DepositValue, indicating the currency in which the deposit was made. |
| DepositAppliedValue | Decimal | True |
The portion of the deposit that has been credited toward project invoices. This reduces the total remaining balance of the project. |
| DepositAppliedCurrency | String | True |
The currency of the DepositAppliedValue, reflecting the currency in which the deposit is being applied. |
| CreditNoteValue | Decimal | True |
The total value of any credit notes issued for the project. This is used to reduce the amount owed on the project. |
| CreditNoteCurrency | String | True |
The currency of the CreditNoteValue, indicating the currency used for the issued credit notes. |
| Deadline | Date | False |
The deadline or due date for completing the project. This helps track the expected project completion date. |
| TotalInvoicedValue | Decimal | True |
The total amount that has been invoiced to the project across all categories (such as tasks or expenses). |
| TotalInvoicedCurrency | String | True |
The currency of the TotalInvoicedValue, indicating the currency in which the total project invoicing was carried out. |
| TotalToBeInvoicedValue | Decimal | True |
The total remaining value of the project that has not yet been invoiced. This includes both tasks and expenses still to be billed. |
| TotalToBeInvoicedCurrency | String | True |
The currency of the TotalToBeInvoicedValue, indicating the currency of the remaining amount to be invoiced. |
| EstimateValue | Decimal | False |
The initial estimated value of the project, representing the projected costs or revenue for the entire project. |
| EstimateCurrency | String | True |
The currency of the EstimateValue, indicating the currency in which the project estimate was calculated. |
| Status | String | True |
The current status of the project. Valid values are 'INPROGRESS' (ongoing) or 'CLOSED' (completed or terminated). |
| TenantId | String | False |
The ID of the tenant to query instead of the connection tenant. This is used to reference a specific tenant in multi-tenant environments. |
Stores and manages tasks associated with projects in Xero. You can query, insert, update, and delete tasks, which include details like task name, description, assigned personnel, and deadlines.
A Task must be created with a ProjectId, Name, RateCurrency, RateValue, and ChargeType. The ProjectId and RateCurrency must come from the project (ProjectId and CurrencyCode respectively). ChargeType determines how the RateValue is applied to the cost of the project:
The EstimateMinutes may also be provided to set the time estimate for the task:
INSERT INTO Tasks (ProjectId, Name, RateCurrency, RateValue, ChargeType, EstimateMinutes) VALUES ('1de78bad-5a81-4cb8-ab53-5a1a3bc73b29', 'Pave Sidewalks', 'USD', 25000, 'FIXED', 1000)
Once a Task has been created, its RateCurrency, RateValue, ChargeType or EstimateMinutes may be updated:
UPDATE Tasks SET RateValue = 250, ChargeType = 'TIME', EstimateMinutes = 2000 WHERE Id = '1de78bad-5a81-4cb8-ab53-5a1a3bc73b29/d15810a1-9324-4765-a357-80d160a0b87c'
Tasks may also be deleted by specifying their Id:
DELETE FROM Tasks WHERE Id = '1de78bad-5a81-4cb8-ab53-5a1a3bc73b29/d15810a1-9324-4765-a357-80d160a0b87c'
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | False |
A unique combination of the project and task identifiers, ensuring that each task is distinctly identified within the project. |
| TaskId | String | True |
The unique Xero identifier for the task, which is automatically assigned when the task is created in Xero. |
| ProjectId | String | False |
The unique identifier for the project to which this task belongs, providing context for the task's association with a specific project. |
| Name | String | False |
The name of the task, which provides a human-readable label for identifying the task. |
| ChargeType | String | False |
Indicates how the task is billed. Possible values include 'TIME' (charged based on hours worked), 'FIXED' (a predetermined amount for the task), or 'NON_CHARGEABLE' (the task cannot be billed). |
| RateValue | Decimal | False |
The per-hour rate that is charged for the task, applicable only if the ChargeType is TIME. This value represents the hourly cost for the task. |
| RateCurrency | String | False |
The currency in which the RateValue is measured, specifying the monetary unit for the rate (such as USD or EUR). |
| EstimateMinutes | Int | False |
The estimated number of minutes required to complete the task, providing a time forecast for project planning. |
| TotalMinutes | Int | True |
The actual total number of minutes logged against the task, indicating how much time has been spent on the task to date. |
| TotalAmountValue | Decimal | True |
The total value of the task, calculated as the product of TotalMinutes and RateValue, reflecting the total cost for the task based on the time spent and the rate. |
| TotalAmountCurrency | String | True |
The currency in which the TotalAmountValue is expressed, specifying the monetary unit for the total task value. |
| MinutesToBeInvoiced | Int | True |
The number of minutes associated with the task that have not yet been invoiced, indicating outstanding work that needs to be billed. |
| MinutesInvoiced | Int | True |
The number of minutes associated with the task that have already been invoiced, showing the work that has been billed. |
| NonChargeableMinutes | Int | True |
The number of minutes for the task that cannot be billed to the client, typically indicating work that is non-billable or covered under a fixed rate. |
| AmountToBeInvoicedValue | Decimal | True |
The total amount of the task that has not been invoiced, calculated as the product of MinutesToBeInvoiced and RateValue, representing the outstanding charge for the task. |
| AmountToBeInvoicedCurrency | String | True |
The currency of the AmountToBeInvoicedValue, indicating the monetary unit for the outstanding invoice amount. |
| AmountInvoicedValue | Decimal | True |
The total amount for the task that has been invoiced, calculated as the product of MinutesInvoiced and RateValue, showing how much has already been billed for the task. |
| AmountInvoicedCurrency | String | True |
The currency of the AmountInvoicedValue, specifying the monetary unit for the amount that has been invoiced. |
| Status | String | True |
The current status of the task. Possible values include 'ACTIVE' (the task is ongoing), 'INVOICED' (the task has been billed), or 'LOCKED' (the task is complete and cannot be modified). |
| TenantId | String | False |
The unique identifier for the tenant to query, allowing you to specify which tenant's data should be returned, useful for multi-tenant environments. |
Stores and manages time entries logged against projects and tasks. It allows for querying, inserting, updating, and deleting time records, which are essential for billing and resource management.
A Time must be created with a ProjectId, TaskId, UserId, Date and Duration. An optional description may also be provided:
INSERT INTO Time (ProjectId, TaskId, UserId, Date, Duration, Description) VALUES ('1de78bad-5a81-4cb8-ab53-5a1a3bc73b29', 'd15810a1-9324-4765-a357-80d160a0b87c', '312b124b-f33f-4cfe-a831-20eb290610d6', '2019-10-01', 250, 'Paved northwest section')
Once a Time has been created, its UserId, Date, Duration or Description may be updated:
UPDATE Time SET Date = '2019-11-01', Duration = 350 WHERE Id = '1de78bad-5a81-4cb8-ab53-5a1a3bc73b29/cb53829a-31ca-4760-a2a7-5a2a46e67cfb'
Time may also be deleted by specifying their Id:
DELETE FROM Time WHERE Id = '1de78bad-5a81-4cb8-ab53-5a1a3bc73b29/cb53829a-31ca-4760-a2a7-5a2a46e67cfb'
| Name | Type | ReadOnly | Description |
| Id [KEY] | String | False |
A unique combination of the project and time entry identifiers, used to uniquely reference a specific time entry record within the system. This ensures that each time entry is distinguishable even if there are multiple entries for the same project or task. |
| TimeEntryId | String | True |
The unique Xero identifier of the time entry, automatically assigned by Xero to track and reference time entries in the system. |
| UserId | String | False |
The ID of the user who logged the time entry, providing a link between the time entry and the employee or contractor who recorded the work hours. |
| ProjectId | String | False |
The ID of the project the task belongs to, linking the time entry to a specific project and ensuring accurate project tracking for billing or reporting purposes. |
| TaskId | String | False |
The ID of the task the time is logged for, allowing detailed tracking of time spent on individual tasks within a larger project. |
| Date | Date | False |
The day the time was logged for, indicating when the work was performed. This is important for proper billing, time management, and project tracking. |
| DateEntered | Datetime | True |
When the time entry was created, recording the exact date and time the time entry was logged into the system for reference and auditing purposes. |
| Duration | Int | False |
The duration of the time logged, typically measured in minutes or hours, representing the length of time the user worked on the task or project. |
| Description | String | False |
A brief description of the time entry, providing context for the work performed, the nature of the task, or any relevant details to accompany the time entry. |
| Status | String | True |
The current status of the time entry. Values can be one of the following: 'ACTIVE' (still open and editable), 'LOCKED' (finalized and no longer editable), or 'INVOICED' (already invoiced and accounted for). |
| TenantId | String | False |
The ID of the tenant to query instead of the connection tenant, allowing the system to identify which organization's data to query when working with multiple tenants. |
Views are similar to tables in the way that data is represented; however, views are read-only.
Queries can be executed against a view as if it were a normal table.
| Name | Description |
| Tenants | Queries the list of organizations connected to your Xero account. It helps retrieve tenant details associated with project management and tracking. |
| Users | Queries the users associated with a specific project in Xero. It helps track who is working on a project and their roles, providing insights into team management and collaboration. |
Queries the list of organizations connected to your Xero account. It helps retrieve tenant details associated with project management and tracking.
| Name | Type | Description |
| TenantId [KEY] | String | A unique identifier for the tenant, which distinguishes each organization or practice in a multi-tenant environment. This ID is used to query data specific to that tenant. |
| Name | String | The name of the organization or practice associated with the tenant, providing a human-readable label to identify the tenant's business or entity. |
| Type | String | The type of the tenant, which can be either an organization or a practice. This helps categorize the type of entity for clearer distinction within a system. |
| IsActive | Boolean | A boolean flag that indicates whether the connection is currently using this tenant. If the value is set to 'true', the tenant is active and can be queried; if 'false', the tenant is inactive or not in use. |
Queries the users associated with a specific project in Xero. It helps track who is working on a project and their roles, providing insights into team management and collaboration.
| Name | Type | Description |
| UserId [KEY] | String | The unique Xero identifier of the user, automatically assigned by Xero to distinguish each user in the system. This ID is critical for user-specific activities such as tracking actions, permissions, and access control. |
| Name | String | The full name of the user, which is typically composed of the user's first name and last name. It is used for displaying the user in reports, notifications, and user management interfaces. |
| String | The email address of the user, which is used for communication, notifications, and authentication purposes. It ensures that the user can be contacted for system updates, alerts, or other relevant correspondence. | |
| TenantId | String | The ID of the tenant to query instead of the connection tenant, used in multi-tenant environments where multiple organizations or entities share the same Xero account. This ensures that data is queried from the correct organization or practice. |
Stored procedures are function-like interfaces that extend the functionality of the Cloud beyond simple SELECT/INSERT/UPDATE/DELETE operations with Xero.
Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from Xero, along with an indication of whether the procedure succeeded or failed.
| Name | Description |
| GetLimitInfo | Retrieves limit information regarding API calls to the Projects API. It's used to monitor how many API calls remain for a tenant. |
| RevokeTenant | Disconnects the specified tenant from the application. Reauthorization is required the next time the user connects the application to the tenant. |
Retrieves limit information regarding API calls to the Projects API. It's used to monitor how many API calls remain for a tenant.
This procedure reports information that the Cloud caches after each API request. If no requests have been made to a tenant on a connection than this procedure will report 0 rows. Otherwise, the LastModified field reports the last time the information in the row was updated.
If the last modified time is too long ago for your application to use, then this table may be refreshed by executing a query.
The query must read at least one row to ensure that an API request is triggered:
SELECT * FROM Projects LIMIT 1
| Name | Type | Description |
| TenantId | String | The unique identifier for the tenant that the API rate limit applies to. This value represents the specific tenant for which the API call limit is being tracked. The output will typically contain one row per tenant queried, though multiple tenants may be queried in some cases. |
| AppRemaining | Integer | The number of remaining API calls allowed for the current OAuth application within the current minute. The maximum allowable API calls for an app in a minute is 10,000, and this value reflects how many are still available. |
| MinuteRemaining | Integer | The number of API calls remaining for the current OAuth application for the current minute. This limit is specific to each individual tenant and the maximum number of calls allowed per minute per tenant is 60. |
| DayRemaining | Integer | The number of API calls the current OAuth app is allowed to make for the current day. The limit per tenant is set at a maximum of 5000 calls per day, and this value indicates how many calls are left for that specific tenant. |
| RetryAfter | Integer | The suggested time (in seconds) before retrying an API request if one of the above rate limits (minute or day) was exceeded. This value helps guide the client to avoid unnecessary retry attempts that could be rejected due to rate limiting. |
| LastModified | Datetime | The timestamp of when the API rate limit information was last updated. This value reflects when the rate limit data was last refreshed based on an API call. Since rate limit data is only updated when performing API calls, this value might be slightly out-of-date. |
Disconnects the specified tenant from the application. Reauthorization is required the next time the user connects the application to the tenant.
| Name | Type | Required | Description |
| TenantId | String | False | The unique identifier of the tenant that is being revoked. This ID is obtained from the Tenants view, which allows you to specify the tenant for which the connection will be removed. |
| Name | Type | Description |
| Success | String | A boolean value indicating whether the revocation operation was successful. If true, the connection has been successfully revoked for the specified tenant, otherwise, the operation has failed. |
You can query the system tables described in this section to access schema information, information on data source functionality, and batch operation statistics.
The following tables return database metadata for Xero:
The following tables return information about how to connect to and query the data source:
The following table returns query statistics for data modification queries, including batch operations::
Lists the available databases.
The following query retrieves all databases determined by the connection string:
SELECT * FROM sys_catalogs
| Name | Type | Description |
| CatalogName | String | The database name. |
Lists the available schemas.
The following query retrieves all available schemas:
SELECT * FROM sys_schemas
| Name | Type | Description |
| CatalogName | String | The database name. |
| SchemaName | String | The schema name. |
Lists the available tables.
The following query retrieves the available tables and views:
SELECT * FROM sys_tables
| Name | Type | Description |
| CatalogName | String | The database containing the table or view. |
| SchemaName | String | The schema containing the table or view. |
| TableName | String | The name of the table or view. |
| TableType | String | The table type (table or view). |
| Description | String | A description of the table or view. |
| IsUpdateable | Boolean | Whether the table can be updated. |
Describes the columns of the available tables and views.
The following query returns the columns and data types for the Contacts table:
SELECT ColumnName, DataTypeName FROM sys_tablecolumns WHERE TableName='Contacts'
| Name | Type | Description |
| CatalogName | String | The name of the database containing the table or view. |
| SchemaName | String | The schema containing the table or view. |
| TableName | String | The name of the table or view containing the column. |
| ColumnName | String | The column name. |
| DataTypeName | String | The data type name. |
| DataType | Int32 | An integer indicating the data type. This value is determined at run time based on the environment. |
| Length | Int32 | The storage size of the column. |
| DisplaySize | Int32 | The designated column's normal maximum width in characters. |
| NumericPrecision | Int32 | The maximum number of digits in numeric data. The column length in characters for character and date-time data. |
| NumericScale | Int32 | The column scale or number of digits to the right of the decimal point. |
| IsNullable | Boolean | Whether the column can contain null. |
| Description | String | A brief description of the column. |
| Ordinal | Int32 | The sequence number of the column. |
| IsAutoIncrement | String | Whether the column value is assigned in fixed increments. |
| IsGeneratedColumn | String | Whether the column is generated. |
| IsHidden | Boolean | Whether the column is hidden. |
| IsArray | Boolean | Whether the column is an array. |
| IsReadOnly | Boolean | Whether the column is read-only. |
| IsKey | Boolean | Indicates whether a field returned from sys_tablecolumns is the primary key of the table. |
| ColumnType | String | The role or classification of the column in the schema. Possible values include SYSTEM, LINKEDCOLUMN, NAVIGATIONKEY, REFERENCECOLUMN, and NAVIGATIONPARENTCOLUMN. |
Lists the available stored procedures.
The following query retrieves the available stored procedures:
SELECT * FROM sys_procedures
| Name | Type | Description |
| CatalogName | String | The database containing the stored procedure. |
| SchemaName | String | The schema containing the stored procedure. |
| ProcedureName | String | The name of the stored procedure. |
| Description | String | A description of the stored procedure. |
| ProcedureType | String | The type of the procedure, such as PROCEDURE or FUNCTION. |
Describes stored procedure parameters.
The following query returns information about all of the input parameters for the RefreshOAuthAccessToken stored procedure:
SELECT * FROM sys_procedureparameters WHERE ProcedureName = 'RefreshOAuthAccessToken' AND Direction = 1 OR Direction = 2
To include result set columns in addition to the parameters, set the IncludeResultColumns pseudo column to True:
SELECT * FROM sys_procedureparameters WHERE ProcedureName = 'RefreshOAuthAccessToken' AND IncludeResultColumns='True'
| Name | Type | Description |
| CatalogName | String | The name of the database containing the stored procedure. |
| SchemaName | String | The name of the schema containing the stored procedure. |
| ProcedureName | String | The name of the stored procedure containing the parameter. |
| ColumnName | String | The name of the stored procedure parameter. |
| Direction | Int32 | An integer corresponding to the type of the parameter: input (1), input/output (2), or output(4). input/output type parameters can be both input and output parameters. |
| DataType | Int32 | An integer indicating the data type. This value is determined at run time based on the environment. |
| DataTypeName | String | The name of the data type. |
| NumericPrecision | Int32 | The maximum precision for numeric data. The column length in characters for character and date-time data. |
| Length | Int32 | The number of characters allowed for character data. The number of digits allowed for numeric data. |
| NumericScale | Int32 | The number of digits to the right of the decimal point in numeric data. |
| IsNullable | Boolean | Whether the parameter can contain null. |
| IsRequired | Boolean | Whether the parameter is required for execution of the procedure. |
| IsArray | Boolean | Whether the parameter is an array. |
| Description | String | The description of the parameter. |
| Ordinal | Int32 | The index of the parameter. |
| Values | String | The values you can set in this parameter are limited to those shown in this column. Possible values are comma-separated. |
| SupportsStreams | Boolean | Whether the parameter represents a file that you can pass as either a file path or a stream. |
| IsPath | Boolean | Whether the parameter is a target path for a schema creation operation. |
| Default | String | The value used for this parameter when no value is specified. |
| SpecificName | String | A label that, when multiple stored procedures have the same name, uniquely identifies each identically-named stored procedure. If there's only one procedure with a given name, its name is simply reflected here. |
| IsCDataProvided | Boolean | Whether the procedure is added/implemented by CData, as opposed to being a native Xero procedure. |
| Name | Type | Description |
| IncludeResultColumns | Boolean | Whether the output should include columns from the result set in addition to parameters. Defaults to False. |
Describes the primary and foreign keys.
The following query retrieves the primary key for the Contacts table:
SELECT * FROM sys_keycolumns WHERE IsKey='True' AND TableName='Contacts'
| Name | Type | Description |
| CatalogName | String | The name of the database containing the key. |
| SchemaName | String | The name of the schema containing the key. |
| TableName | String | The name of the table containing the key. |
| ColumnName | String | The name of the key column. |
| IsKey | Boolean | Whether the column is a primary key in the table referenced in the TableName field. |
| IsForeignKey | Boolean | Whether the column is a foreign key referenced in the TableName field. |
| PrimaryKeyName | String | The name of the primary key. |
| ForeignKeyName | String | The name of the foreign key. |
| ReferencedCatalogName | String | The database containing the primary key. |
| ReferencedSchemaName | String | The schema containing the primary key. |
| ReferencedTableName | String | The table containing the primary key. |
| ReferencedColumnName | String | The column name of the primary key. |
Describes the foreign keys.
The following query retrieves all foreign keys which refer to other tables:
SELECT * FROM sys_foreignkeys WHERE ForeignKeyType = 'FOREIGNKEY_TYPE_IMPORT'
| Name | Type | Description |
| CatalogName | String | The name of the database containing the key. |
| SchemaName | String | The name of the schema containing the key. |
| TableName | String | The name of the table containing the key. |
| ColumnName | String | The name of the key column. |
| PrimaryKeyName | String | The name of the primary key. |
| ForeignKeyName | String | The name of the foreign key. |
| ReferencedCatalogName | String | The database containing the primary key. |
| ReferencedSchemaName | String | The schema containing the primary key. |
| ReferencedTableName | String | The table containing the primary key. |
| ReferencedColumnName | String | The column name of the primary key. |
| ForeignKeyType | String | Designates whether the foreign key is an import (points to other tables) or export (referenced from other tables) key. |
Describes the primary keys.
The following query retrieves the primary keys from all tables and views:
SELECT * FROM sys_primarykeys
| Name | Type | Description |
| CatalogName | String | The name of the database containing the key. |
| SchemaName | String | The name of the schema containing the key. |
| TableName | String | The name of the table containing the key. |
| ColumnName | String | The name of the key column. |
| KeySeq | String | The sequence number of the primary key. |
| KeyName | String | The name of the primary key. |
Describes the available indexes. By filtering on indexes, you can write more selective queries with faster query response times.
The following query retrieves all indexes that are not primary keys:
SELECT * FROM sys_indexes WHERE IsPrimary='false'
| Name | Type | Description |
| CatalogName | String | The name of the database containing the index. |
| SchemaName | String | The name of the schema containing the index. |
| TableName | String | The name of the table containing the index. |
| IndexName | String | The index name. |
| ColumnName | String | The name of the column associated with the index. |
| IsUnique | Boolean | True if the index is unique. False otherwise. |
| IsPrimary | Boolean | True if the index is a primary key. False otherwise. |
| Type | Int16 | An integer value corresponding to the index type: statistic (0), clustered (1), hashed (2), or other (3). |
| SortOrder | String | The sort order: A for ascending or D for descending. |
| OrdinalPosition | Int16 | The sequence number of the column in the index. |
Returns information on the available connection properties and those set in the connection string.
The following query retrieves all connection properties that have been set in the connection string or set through a default value:
SELECT * FROM sys_connection_props WHERE Value <> ''
| Name | Type | Description |
| Name | String | The name of the connection property. |
| ShortDescription | String | A brief description. |
| Type | String | The data type of the connection property. |
| Default | String | The default value if one is not explicitly set. |
| Values | String | A comma-separated list of possible values. A validation error is thrown if another value is specified. |
| Value | String | The value you set or a preconfigured default. |
| Required | Boolean | Whether the property is required to connect. |
| Category | String | The category of the connection property. |
| IsSessionProperty | String | Whether the property is a session property, used to save information about the current connection. |
| Sensitivity | String | The sensitivity level of the property. This informs whether the property is obfuscated in logging and authentication forms. |
| PropertyName | String | A camel-cased truncated form of the connection property name. |
| Ordinal | Int32 | The index of the parameter. |
| CatOrdinal | Int32 | The index of the parameter category. |
| Hierarchy | String | Shows dependent properties associated that need to be set alongside this one. |
| Visible | Boolean | Informs whether the property is visible in the connection UI. |
| ETC | String | Various miscellaneous information about the property. |
Describes the SELECT query processing that the Cloud can offload to the data source.
See SQL Compliance for SQL syntax details.
Below is an example data set of SQL capabilities. Some aspects of SELECT functionality are returned in a comma-separated list if supported; otherwise, the column contains NO.
| Name | Description | Possible Values |
| AGGREGATE_FUNCTIONS | Supported aggregation functions. | AVG, COUNT, MAX, MIN, SUM, DISTINCT |
| COUNT | Whether COUNT function is supported. | YES, NO |
| IDENTIFIER_QUOTE_OPEN_CHAR | The opening character used to escape an identifier. | [ |
| IDENTIFIER_QUOTE_CLOSE_CHAR | The closing character used to escape an identifier. | ] |
| SUPPORTED_OPERATORS | A list of supported SQL operators. | =, >, <, >=, <=, <>, !=, LIKE, NOT LIKE, IN, NOT IN, IS NULL, IS NOT NULL, AND, OR |
| GROUP_BY | Whether GROUP BY is supported, and, if so, the degree of support. | NO, NO_RELATION, EQUALS_SELECT, SQL_GB_COLLATE |
| OJ_CAPABILITIES | The supported varieties of outer joins supported. | NO, LEFT, RIGHT, FULL, INNER, NOT_ORDERED, ALL_COMPARISON_OPS |
| OUTER_JOINS | Whether outer joins are supported. | YES, NO |
| SUBQUERIES | Whether subqueries are supported, and, if so, the degree of support. | NO, COMPARISON, EXISTS, IN, CORRELATED_SUBQUERIES, QUANTIFIED |
| STRING_FUNCTIONS | Supported string functions. | LENGTH, CHAR, LOCATE, REPLACE, SUBSTRING, RTRIM, LTRIM, RIGHT, LEFT, UCASE, SPACE, SOUNDEX, LCASE, CONCAT, ASCII, REPEAT, OCTET, BIT, POSITION, INSERT, TRIM, UPPER, REGEXP, LOWER, DIFFERENCE, CHARACTER, SUBSTR, STR, REVERSE, PLAN, UUIDTOSTR, TRANSLATE, TRAILING, TO, STUFF, STRTOUUID, STRING, SPLIT, SORTKEY, SIMILAR, REPLICATE, PATINDEX, LPAD, LEN, LEADING, KEY, INSTR, INSERTSTR, HTML, GRAPHICAL, CONVERT, COLLATION, CHARINDEX, BYTE |
| NUMERIC_FUNCTIONS | Supported numeric functions. | ABS, ACOS, ASIN, ATAN, ATAN2, CEILING, COS, COT, EXP, FLOOR, LOG, MOD, SIGN, SIN, SQRT, TAN, PI, RAND, DEGREES, LOG10, POWER, RADIANS, ROUND, TRUNCATE |
| TIMEDATE_FUNCTIONS | Supported date/time functions. | NOW, CURDATE, DAYOFMONTH, DAYOFWEEK, DAYOFYEAR, MONTH, QUARTER, WEEK, YEAR, CURTIME, HOUR, MINUTE, SECOND, TIMESTAMPADD, TIMESTAMPDIFF, DAYNAME, MONTHNAME, CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP, EXTRACT |
| REPLICATION_SKIP_TABLES | Indicates tables skipped during replication. | |
| REPLICATION_TIMECHECK_COLUMNS | A string array containing a list of columns which will be used to check for (in the given order) to use as a modified column during replication. | |
| IDENTIFIER_PATTERN | String value indicating what string is valid for an identifier. | |
| SUPPORT_TRANSACTION | Indicates if the provider supports transactions such as commit and rollback. | YES, NO |
| DIALECT | Indicates the SQL dialect to use. | |
| KEY_PROPERTIES | Indicates the properties which identify the uniform database. | |
| SUPPORTS_MULTIPLE_SCHEMAS | Indicates if multiple schemas may exist for the provider. | YES, NO |
| SUPPORTS_MULTIPLE_CATALOGS | Indicates if multiple catalogs may exist for the provider. | YES, NO |
| DATASYNCVERSION | The CData Data Sync version needed to access this driver. | Standard, Starter, Professional, Enterprise |
| DATASYNCCATEGORY | The CData Data Sync category of this driver. | Source, Destination, Cloud Destination |
| SUPPORTSENHANCEDSQL | Whether enhanced SQL functionality beyond what is offered by the API is supported. | TRUE, FALSE |
| SUPPORTS_BATCH_OPERATIONS | Whether batch operations are supported. | YES, NO |
| SQL_CAP | All supported SQL capabilities for this driver. | SELECT, INSERT, DELETE, UPDATE, TRANSACTIONS, ORDERBY, OAUTH, ASSIGNEDID, LIMIT, LIKE, BULKINSERT, COUNT, BULKDELETE, BULKUPDATE, GROUPBY, HAVING, AGGS, OFFSET, REPLICATE, COUNTDISTINCT, JOINS, DROP, CREATE, DISTINCT, INNERJOINS, SUBQUERIES, ALTER, MULTIPLESCHEMAS, GROUPBYNORELATION, OUTERJOINS, UNIONALL, UNION, UPSERT, GETDELETED, CROSSJOINS, GROUPBYCOLLATE, MULTIPLECATS, FULLOUTERJOIN, MERGE, JSONEXTRACT, BULKUPSERT, SUM, SUBQUERIESFULL, MIN, MAX, JOINSFULL, XMLEXTRACT, AVG, MULTISTATEMENTS, FOREIGNKEYS, CASE, LEFTJOINS, COMMAJOINS, WITH, LITERALS, RENAME, NESTEDTABLES, EXECUTE, BATCH, BASIC, INDEX |
| PREFERRED_CACHE_OPTIONS | A string value specifies the preferred cacheOptions. | |
| ENABLE_EF_ADVANCED_QUERY | Indicates if the driver directly supports advanced queries coming from Entity Framework. If not, queries will be handled client side. | YES, NO |
| PSEUDO_COLUMNS | A string array indicating the available pseudo columns. | |
| MERGE_ALWAYS | If the value is true, The Merge Mode is forcibly executed in Data Sync. | TRUE, FALSE |
| REPLICATION_MIN_DATE_QUERY | A select query to return the replicate start datetime. | |
| REPLICATION_MIN_FUNCTION | Allows a provider to specify the formula name to use for executing a server side min. | |
| REPLICATION_START_DATE | Allows a provider to specify a replicate startdate. | |
| REPLICATION_MAX_DATE_QUERY | A select query to return the replicate end datetime. | |
| REPLICATION_MAX_FUNCTION | Allows a provider to specify the formula name to use for executing a server side max. | |
| IGNORE_INTERVALS_ON_INITIAL_REPLICATE | A list of tables which will skip dividing the replicate into chunks on the initial replicate. | |
| CHECKCACHE_USE_PARENTID | Indicates whether the CheckCache statement should be done against the parent key column. | TRUE, FALSE |
| CREATE_SCHEMA_PROCEDURES | Indicates stored procedures that can be used for generating schema files. |
The following query retrieves the operators that can be used in the WHERE clause:
SELECT * FROM sys_sqlinfo WHERE Name = 'SUPPORTED_OPERATORS'
Note that individual tables may have different limitations or requirements on the WHERE clause; refer to the Data Model section for more information.
| Name | Type | Description |
| NAME | String | A component of SQL syntax, or a capability that can be processed on the server. |
| VALUE | String | Detail on the supported SQL or SQL syntax. |
Returns information about attempted modifications.
The following query retrieves the Ids of the modified rows in a batch operation:
SELECT * FROM sys_identity
| Name | Type | Description |
| Id | String | The database-generated Id returned from a data modification operation. |
| Batch | String | An identifier for the batch. 1 for a single operation. |
| Operation | String | The result of the operation in the batch: INSERTED, UPDATED, or DELETED. |
| Message | String | SUCCESS or an error message if the update in the batch failed. |
Describes the available system information.
The following query retrieves all columns:
SELECT * FROM sys_information
| Name | Type | Description |
| Product | String | The name of the product. |
| Version | String | The version number of the product. |
| Datasource | String | The name of the datasource the product connects to. |
| NodeId | String | The unique identifier of the machine where the product is installed. |
| HelpURL | String | The URL to the product's help documentation. |
| License | String | The license information for the product. (If this information is not available, the field may be left blank or marked as 'N/A'.) |
| Location | String | The file path location where the product's library is stored. |
| Environment | String | The version of the environment or rumtine the product is currently running under. |
| DataSyncVersion | String | The tier of CData Sync required to use this connector. |
| DataSyncCategory | String | The category of CData Sync functionality (e.g., Source, Destination). |
The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider. Click the links for further details.
For more information on establishing a connection, see Establishing a Connection.
| Property | Description |
| AuthScheme | Specifies the authentication scheme used to establish a connection to Xero. It determines the authentication mechanism required for validating the user's identity and allows integration with various OAuth providers. Accepted entries are OAuth, PKCE, or OAuthClient. |
| Schema | Specifies the Xero API you want to access, which is exposed through the selected schema in the data model. Each schema corresponds to a specific functional API provided by Xero (for example, Accounting, Payroll, Projects). |
| Tenant | Specifies the Xero organization (tenant) to connect to. This can be either the name of the organization or its unique tenant ID. If not specified, the first authorized tenant is used by default. |
| Property | Description |
| OAuthClientId | Specifies the client ID (also known as the consumer key) assigned to your custom OAuth application. This ID is required to identify the application to the OAuth authorization server during authentication. |
| OAuthClientSecret | Specifies the client secret assigned to your custom OAuth application. This confidential value is used to authenticate the application to the OAuth authorization server. (Custom OAuth applications only.). |
| Scope | Specifies the OAuth scopes that the application requests when authenticating with Xero. Scopes define the specific permissions the application is requesting from the user or organization, and determine what data and actions the application is allowed to access. |
| Property | Description |
| SSLServerCert | Specifies the certificate to be accepted from the server when connecting using TLS/SSL. |
| Property | Description |
| Verbosity | Specifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5. |
| Property | Description |
| BrowsableSchemas | Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC . |
| Property | Description |
| AutoExpandDetails | Specifies whether the connection should automatically expand and include additional details for complex objects such as BankTransfers, ContactGroups, ExpenseClaims, ExpenseClaimPayments, ExpenseClaimReceipts, and Receipts. Enabling this option retrieves embedded or related data without requiring separate item-level queries. |
| IncludeArchived | Specifies whether archived records should be included in query results. Archived records typically represent inactive, soft-deleted, or historical entries that are retained for compliance or auditing purposes. |
| MaxRows | Specifies the maximum number of rows returned for queries that do not include either aggregation or GROUP BY. |
| Pagesize | Specifies the maximum number of results to return per page when retrieving data from Xero. This property controls pagination behavior during data queries, improving performance and controllability of result sets. |
| PseudoColumns | Specifies the pseudocolumns to expose as table columns, expressed as a string in the format 'TableName=ColumnName;TableName=ColumnName'. |
| RetryDailyLimit | Specifies whether the provider should wait and retry when Xero reports that the daily API usage limit has been reached. Enabling this setting allows the connection to pause and resume automatically based on the wait time recommended by Xero. |
| RetryWaitTime | Specifies the amount of time (in milliseconds) that the provider should wait before retrying a request after hitting the Xero API rate limit. This delay helps manage request throttling and prevent repeated failures. |
| Timeout | Specifies the maximum time, in seconds, that the provider waits for a server response before throwing a timeout error. |
| UnitDP | Controls the number of decimal places returned for unit prices in query results. This setting affects the precision of unit price values retrieved from the Xero API. |
| UseOptimizedFiltersOnly | When set to 'true', this property instructs the provider to only push filters that are considered optimized by the Xero API. This improves the reliability of queries targeting high-volume endpoints that may otherwise fail or be throttled when unoptimized filters are used. |
This section provides a complete list of the Authentication properties you can configure in the connection string for this provider.
| Property | Description |
| AuthScheme | Specifies the authentication scheme used to establish a connection to Xero. It determines the authentication mechanism required for validating the user's identity and allows integration with various OAuth providers. Accepted entries are OAuth, PKCE, or OAuthClient. |
| Schema | Specifies the Xero API you want to access, which is exposed through the selected schema in the data model. Each schema corresponds to a specific functional API provided by Xero (for example, Accounting, Payroll, Projects). |
| Tenant | Specifies the Xero organization (tenant) to connect to. This can be either the name of the organization or its unique tenant ID. If not specified, the first authorized tenant is used by default. |
Specifies the authentication scheme used to establish a connection to Xero. It determines the authentication mechanism required for validating the user's identity and allows integration with various OAuth providers. Accepted entries are OAuth, PKCE, or OAuthClient.
string
"PKCE"
Supported authentication methods for new applications include:
Specifies the Xero API you want to access, which is exposed through the selected schema in the data model. Each schema corresponds to a specific functional API provided by Xero (for example, Accounting, Payroll, Projects).
string
"ACCOUNTING"
Set this property to the Xero API you want to access through the Cloud. The following schemas are supported:
Only one schema can be accessed per connection. To work with multiple APIs, you must establish separate connections for each schema.
Specifies the Xero organization (tenant) to connect to. This can be either the name of the organization or its unique tenant ID. If not specified, the first authorized tenant is used by default.
string
""
Xero allows users to authorize applications for access to multiple organizations (tenants) under a single login. By default, the Cloud connects to the first available tenant returned by the Xero API.
To explicitly connect to a specific organization, set the Tenant property to either:
To find the tenant ID:
Tenant = "Demo Company (Global)" Tenant = "d75cc47e-d749-4c93-b050-3177ad62f6d2"Setting this property is recommended when working with integrations that span multiple organizations or require consistent targeting across sessions.
This section provides a complete list of the OAuth properties you can configure in the connection string for this provider.
| Property | Description |
| OAuthClientId | Specifies the client ID (also known as the consumer key) assigned to your custom OAuth application. This ID is required to identify the application to the OAuth authorization server during authentication. |
| OAuthClientSecret | Specifies the client secret assigned to your custom OAuth application. This confidential value is used to authenticate the application to the OAuth authorization server. (Custom OAuth applications only.). |
| Scope | Specifies the OAuth scopes that the application requests when authenticating with Xero. Scopes define the specific permissions the application is requesting from the user or organization, and determine what data and actions the application is allowed to access. |
Specifies the client ID (also known as the consumer key) assigned to your custom OAuth application. This ID is required to identify the application to the OAuth authorization server during authentication.
string
""
This property is required in two cases:
(When the driver provides embedded OAuth credentials, this value may already be provided by the Cloud and thus not require manual entry.)
OAuthClientId is generally used alongside other OAuth-related properties such as OAuthClientSecret and OAuthSettingsLocation when configuring an authenticated connection.
OAuthClientId is one of the key connection parameters that need to be set before users can authenticate via OAuth. You can usually find this value in your identity provider’s application registration settings. Look for a field labeled Client ID, Application ID, or Consumer Key.
While the client ID is not considered a confidential value like a client secret, it is still part of your application's identity and should be handled carefully. Avoid exposing it in public repositories or shared configuration files.
For more information on how this property is used when configuring a connection, see Establishing a Connection.
Specifies the client secret assigned to your custom OAuth application. This confidential value is used to authenticate the application to the OAuth authorization server. (Custom OAuth applications only.).
string
""
This property (sometimes called the application secret or consumer secret) is required when using a custom OAuth application in any flow that requires secure client authentication, such as web-based OAuth, service-based connections, or certificate-based authorization flows. It is not required when using an embedded OAuth application.
The client secret is used during the token exchange step of the OAuth flow, when the driver requests an access token from the authorization server. If this value is missing or incorrect, authentication fails with either an invalid_client or an unauthorized_client error.
OAuthClientSecret is one of the key connection parameters that need to be set before users can authenticate via OAuth. You can obtain this value from your identity provider when registering the OAuth application.
Notes:
For more information on how this property is used when configuring a connection, see Establishing a Connection
Specifies the OAuth scopes that the application requests when authenticating with Xero. Scopes define the specific permissions the application is requesting from the user or organization, and determine what data and actions the application is allowed to access.
string
"offline_access accounting.transactions accounting.journals.read accounting.reports.read accounting.settings accounting.contacts accounting.attachments"
By default, the Cloud requests authorization for the recommended set of scopes for use with Xero:
Example:
Scope = "openid email profile accounting.transactions accounting.reports.read"Only include scopes your application needs to improve user trust and reduce risk. Make sure the scopes are supported by the API endpoints you plan to use. When modifying this property, ensure your OAuth app is registered with those scopes on the provider side as well.
Note: Changes to scopes require re-authentication. Existing tokens are not granted additional permissions automatically.
This section provides a complete list of the SSL properties you can configure in the connection string for this provider.
| Property | Description |
| SSLServerCert | Specifies the certificate to be accepted from the server when connecting using TLS/SSL. |
Specifies the certificate to be accepted from the server when connecting using TLS/SSL.
string
""
If you are using a TLS/SSL connection, use this property to specify the TLS/SSL certificate to be accepted from the server. If you specify a value for this property, all other certificates that are not trusted by the machine are rejected.
This property can take the following forms:
| Description | Example |
| A full PEM Certificate (example shortened for brevity) | -----BEGIN CERTIFICATE----- MIIChTCCAe4CAQAwDQYJKoZIhv......Qw== -----END CERTIFICATE----- |
| A path to a local file containing the certificate | C:\cert.cer |
| The public key (example shortened for brevity) | -----BEGIN RSA PUBLIC KEY----- MIGfMA0GCSq......AQAB -----END RSA PUBLIC KEY----- |
| The MD5 Thumbprint (hex values can also be either space- or colon-separated) | ecadbdda5a1529c58a1e9e09828d70e4 |
| The SHA1 Thumbprint (hex values can also be either space- or colon-separated) | 34a929226ae0819f2ec14b4a3d904f801cbb150d |
Note: It is possible to use '*' to signify that all certificates should be accepted, but due to security concerns this is not recommended.
This section provides a complete list of the Logging properties you can configure in the connection string for this provider.
| Property | Description |
| Verbosity | Specifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5. |
Specifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5.
string
"1"
This property defines the level of detail the Cloud includes in the log file. Higher verbosity levels increase the detail of the logged information, but may also result in larger log files and slower performance due to the additional data being captured.
The default verbosity level is 1, which is recommended for regular operation. Higher verbosity levels are primarily intended for debugging purposes. For more information on each level, refer to Logging.
When combined with the LogModules property, Verbosity can refine logging to specific categories of information.
This section provides a complete list of the Schema properties you can configure in the connection string for this provider.
| Property | Description |
| BrowsableSchemas | Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC . |
Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .
string
""
Listing all available database schemas can take extra time, thus degrading performance. Providing a list of schemas in the connection string saves time and improves performance.
This section provides a complete list of the Miscellaneous properties you can configure in the connection string for this provider.
| Property | Description |
| AutoExpandDetails | Specifies whether the connection should automatically expand and include additional details for complex objects such as BankTransfers, ContactGroups, ExpenseClaims, ExpenseClaimPayments, ExpenseClaimReceipts, and Receipts. Enabling this option retrieves embedded or related data without requiring separate item-level queries. |
| IncludeArchived | Specifies whether archived records should be included in query results. Archived records typically represent inactive, soft-deleted, or historical entries that are retained for compliance or auditing purposes. |
| MaxRows | Specifies the maximum number of rows returned for queries that do not include either aggregation or GROUP BY. |
| Pagesize | Specifies the maximum number of results to return per page when retrieving data from Xero. This property controls pagination behavior during data queries, improving performance and controllability of result sets. |
| PseudoColumns | Specifies the pseudocolumns to expose as table columns, expressed as a string in the format 'TableName=ColumnName;TableName=ColumnName'. |
| RetryDailyLimit | Specifies whether the provider should wait and retry when Xero reports that the daily API usage limit has been reached. Enabling this setting allows the connection to pause and resume automatically based on the wait time recommended by Xero. |
| RetryWaitTime | Specifies the amount of time (in milliseconds) that the provider should wait before retrying a request after hitting the Xero API rate limit. This delay helps manage request throttling and prevent repeated failures. |
| Timeout | Specifies the maximum time, in seconds, that the provider waits for a server response before throwing a timeout error. |
| UnitDP | Controls the number of decimal places returned for unit prices in query results. This setting affects the precision of unit price values retrieved from the Xero API. |
| UseOptimizedFiltersOnly | When set to 'true', this property instructs the provider to only push filters that are considered optimized by the Xero API. This improves the reliability of queries targeting high-volume endpoints that may otherwise fail or be throttled when unoptimized filters are used. |
Specifies whether the connection should automatically expand and include additional details for complex objects such as BankTransfers, ContactGroups, ExpenseClaims, ExpenseClaimPayments, ExpenseClaimReceipts, and Receipts. Enabling this option retrieves embedded or related data without requiring separate item-level queries.
bool
false
When set to 'true', additional details are automatically included when querying certain object types (such as ExpenseClaims), causing some columns that are normally NULL to be populated with related data. This simplifies querying, but may significantly increase response times, especially when retrieving large datasets.
When set to 'false' (default), extra details are omitted to improve performance. To retrieve full details in this mode, individual records must be queried explicitly.
Example:
SELECT * FROM ExpenseClaims WHERE ExpenseClaimId = '12345';Note: Use this setting selectively when you need deep insights into records, and be aware of the potential performance impact.
Specifies whether archived records should be included in query results. Archived records typically represent inactive, soft-deleted, or historical entries that are retained for compliance or auditing purposes.
bool
false
When set to 'true', queries return both active and archived records. This can be useful for historical analysis, reconciliation, or full audit trails.
When set to 'false' (default), only active records are retrieved, improving performance and reducing noise in operational reports.
Note: Enabling this option may increase the size of result sets, especially in datasets with a long history or large volume of archived entries.
Specifies the maximum number of rows returned for queries that do not include either aggregation or GROUP BY.
int
-1
The default value for this property, -1, means that no row limit is enforced unless the query explicitly includes a LIMIT clause. (When a query includes a LIMIT clause, the value specified in the query takes precedence over the MaxRows setting.)
Setting MaxRows to a whole number greater than 0 ensures that queries do not return excessively large result sets by default.
This property is useful for optimizing performance and preventing excessive resource consumption when executing queries that could otherwise return very large datasets.
Specifies the maximum number of results to return per page when retrieving data from Xero. This property controls pagination behavior during data queries, improving performance and controllability of result sets.
int
100
This property defines how many records are returned per page in responses from Xero. It is particularly important when working with endpoints in the Accounting schema that support paginated responses. The default value of 100 is fine for the majority of cases.
Allowed values are 1 to 1000. If a value greater than 1000 is specified, the value is automatically capped at 1000 by the driver.
Choose a value appropriate for your performance and data retrieval needs.
Specifies the pseudocolumns to expose as table columns, expressed as a string in the format 'TableName=ColumnName;TableName=ColumnName'.
string
""
This property allows you to define which pseudocolumns the Cloud exposes as table columns.
To specify individual pseudocolumns, use the following format:
Table1=Column1;Table1=Column2;Table2=Column3
To include all pseudocolumns for all tables use:
*=*
Specifies whether the provider should wait and retry when Xero reports that the daily API usage limit has been reached. Enabling this setting allows the connection to pause and resume automatically based on the wait time recommended by Xero.
bool
false
Setting this option to 'true' is strongly discouraged. Refer to Xero API Limits for detailed guidance on handling rate limits responsibly.
By default, the Cloud fails immediately if the daily API limit is exceeded. This prevents excessive idle time and allows your application to respond promptly.
When this setting is enabled and the daily limit is hit, the Cloud instead enters a wait state and retry after the duration recommended by Xero. This delay can last from minutes to several hours, depending on quota reset timing.
Set to 'true' only in long-running, unattended jobs where automatic resumption is preferred. Avoid enabling in interactive or time-sensitive applications.
Note: This setting does not bypass rate limits—it only changes how the driver responds when limits are reached.
Specifies the amount of time (in milliseconds) that the provider should wait before retrying a request after hitting the Xero API rate limit. This delay helps manage request throttling and prevent repeated failures.
string
"10000"
When the Cloud exceeds the number of allowed API requests, the Xero may temporarily reject additional requests. This property determines how long the Cloud pauses before attempting another request. For example:
This setting works in conjunction with other retry mechanisms to gracefully handle temporary rate-limiting conditions imposed by Xero.
Specifies the maximum time, in seconds, that the provider waits for a server response before throwing a timeout error.
int
60
The timeout applies to each individual communication with the server rather than the entire query or operation. For example, a query could continue running beyond 60 seconds if each paging call completes within the timeout limit.
Timeout is set to 60 seconds by default. To disable timeouts, set this property to 0.
Disabling the timeout allows operations to run indefinitely until they succeed or fail due to other conditions such as server-side timeouts, network interruptions, or resource limits on the server.
Note: Use this property cautiously to avoid long-running operations that could degrade performance or result in unresponsive behavior.
Controls the number of decimal places returned for unit prices in query results. This setting affects the precision of unit price values retrieved from the Xero API.
string
"2"
By default, the Xero API returns unit prices rounded to 2 decimal places. You can increase the precision by setting this property to 4, which returns unit prices with up to 4 decimal places as stored in Xero.
Examples:
UnitDP = "2" // Unit price is 25.00 UnitDP = "4" // Unit price is 25.0048Set this to 4 if your use case requires high precision in pricing, such as inventory valuation or billing scenarios with fractional pricing.
Note: This property only affects unit prices. Other computed values such as line-item amounts and totals continue to be rounded to 2 decimal places as per Xero’s standard behavior and accounting rules.
When set to 'true', this property instructs the provider to only push filters that are considered optimized by the Xero API. This improves the reliability of queries targeting high-volume endpoints that may otherwise fail or be throttled when unoptimized filters are used.
bool
false
Enable this property to ensure that only safe, high-performance filters are included in API requests to Xero. This is particularly important when working with endpoints subject to High Volume Thresholds or stricter rate-limiting constraints. This reduces the chance of query failure due to unsupported or expensive filters and improves performance and stability when querying large datasets.
Set this property to 'true' when accessing endpoints like Invoices, Contacts, or Reports with large result sets, when using tools that auto-generate complex queries, or when you receive errors related to unsupported filters or timeouts.
See Xero API Limits for more information.
LZMA from 7Zip LZMA SDK
LZMA SDK is placed in the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or distribute the original LZMA SDK code, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.
LZMA2 from XZ SDK
Version 1.9 and older are in the public domain.
Xamarin.Forms
Xamarin SDK
The MIT License (MIT)
Copyright (c) .NET Foundation Contributors
All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
NSIS 3.10
Copyright (C) 1999-2025 Contributors THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS COMMON PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.
1. DEFINITIONS
"Contribution" means:
a) in the case of the initial Contributor, the initial code and documentation distributed under this Agreement, and b) in the case of each subsequent Contributor:
i) changes to the Program, and
ii) additions to the Program;
where such changes and/or additions to the Program originate from and are distributed by that particular Contributor. A Contribution 'originates' from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include additions to the Program which: (i) are separate modules of software distributed in conjunction with the Program under their own license agreement, and (ii) are not derivative works of the Program.
"Contributor" means any person or entity that distributes the Program.
"Licensed Patents " mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.
"Program" means the Contributions distributed in accordance with this Agreement.
"Recipient" means anyone who receives the Program under this Agreement, including all Contributors.
2. GRANT OF RIGHTS
a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and such derivative works, in source code and object code form.
b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in source code and object code form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder.
c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program.
d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.
3. REQUIREMENTS
A Contributor may choose to distribute the Program in object code form under its own license agreement, provided that:
a) it complies with the terms and conditions of this Agreement; and
b) its license agreement:
i) effectively disclaims on behalf of all Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose;
ii) effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits;
iii) states that any provisions which differ from this Agreement are offered by that Contributor alone and not by any other party; and
iv) states that source code for the Program is available from such Contributor, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange.
When the Program is made available in source code form:
a) it must be made available under this Agreement; and
b) a copy of this Agreement must be included with each copy of the Program.
Contributors may not remove or alter any copyright notices contained within the Program.
Each Contributor must identify itself as the originator of its Contribution, if any, in a manner that reasonably allows subsequent Recipients to identify the originator of the Contribution.
4. COMMERCIAL DISTRIBUTION
Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense.
For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.
5. NO WARRANTY
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.
6. DISCLAIMER OF LIABILITY
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
7. GENERAL
If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.
If Recipient institutes patent litigation against a Contributor with respect to a patent applicable to software (including a cross-claim or counterclaim in a lawsuit), then any patent licenses granted by that Contributor to such Recipient under this Agreement shall terminate as of the date such litigation is filed. In addition, if Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed.
All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive.
Everyone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency the Agreement is copyrighted and may only be modified in the following manner. The Agreement Steward reserves the right to publish new versions (including revisions) of this Agreement from time to time. No one other than the Agreement Steward has the right to modify this Agreement. IBM is the initial Agreement Steward. IBM may assign the responsibility to serve as the Agreement Steward to a suitable separate entity. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to distribute the Program (including its Contributions) under the new version. Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved.
This Agreement is governed by the laws of the State of New York and the intellectual property laws of the United States of America. No party to this Agreement will bring a legal action under this Agreement more than one year after the cause of action arose. Each party waives its rights to a jury trial in any resulting litigation.