| URL | https://api.xero.com/api.xro/2.0/LinkedTransactions |
| Methods Supported | GET, PUT, POST, DELETE |
| Description | Retrieve linked transactions (billable expenses)
Create linked transactions Update linked transactions Delete linked transactions |
The LinkedTransactions endpoint exposes the billable expenses functionality in Xero. The basic purpose is to link line
items from a purchase transaction (e.g. ACCPAY invoice) to a customer and a sales transaction (e.g. ACCREC Invoice).
Read more about
Billable Expenses in the Xero Help Centre or check out the
demo below.
The following elements are returned in a GET response:
| LinkedTransactionID | The Xero generated identifier for a linked transaction. |
| Status | The status of the linked transaction. This is derived from the statuses of the source and target transactions and cannot be explicitly set/updated. |
| Type | This will always be BILLABLEEXPENSE. More types may be added in future. |
| SourceTransactionID | The identifier of the source transaction (the purchase component of a billable expense). Either an invoice with a type of ACCPAY or a banktransaction of type SPEND. |
| SourceLineItemID | The line item identifier from the source transaction. |
| SourceTransactionTypeCode | The Type of the source tranasction. This will be ACCPAY if the linked transaction was created from an invoice and SPEND if it was created from a bank transaction. |
| ContactID | The identifier for the contact on the target transaction i.e. the customer that the expense is being billed on to. |
| TargetTransactionID | The identifier of the target transaction (the sale component of a billable expense). Currently, only invoices with a type of ACCREC can be a target transaction. |
| TargetLineItemID | The line item identifier from the target transaction. It is possible to link multiple billable expenses to the same TargetLineItemID. |
| UpdatedDateUTC | The last modified date in UTC format |
| LinkedTransactionID | The Xero identifier for an Linked Transaction e.g. /LinkedTransactions/297c2dc5-cc47-4afd-8ec8-74990b8761e9 |
| Page | Up to 100 linked transactions will be returned in a single API call. Use the page parameter to specify the page to be returned e.g. page=1. |
| SourceTransactionID | Filter by the SourceTransactionID. Get all the linked transactions created from a particular ACCPAY invoice |
| ContactID | Filter by the ContactID. Get all the linked transactions that have been assigned to a particular customer. |
| ContactID & Status | Filter by the combination of ContactID and Status. Get all the linked transactions that have been assigned to a particular customer and have a particular status e.g. GET /LinkedTransactions?ContactID=4bb34b03-3378-4bb2-a0ed-6345abf3224e&Status=APPROVED. |
| TargetTransactionID | Filter by the TargetTransactionID. Get all the linked transactions allocated to a particular ACCREC invoice |
Paging is enforced by default with a fixed page size of 100. To retrieve a particular page append a page parameter to the URL e.g. ?page=1. If there are 100 records in the response you will need to check if there is any more data by fetching the next page e.g ?page=2 and continuing this process until no more results are returned.
Example response for GET LinkedTransactions
GET https://api.xero.com/api.xro/2.0/LinkedTransactions
| The following elements are required to create a linked transaction | |
| SourceTransactionID | The identifier of the source transaction (the purchase component of a billable expense). Either an invoice with a type of ACCPAY or a banktransaction of type SPEND. |
| SourceLineItemID | The line item identifier from the source transaction. |
| The following elements are optional when creating or updating linked transactions | |
| ContactID | The identifier for the contact on the target transaction i.e. the customer that the expense is being billed on to. |
| TargetTransactionID | The identifier of the target transaction (the sale component of a billable expense). Currently, only invoices with a type of ACCREC can be a target transaction. |
| TargetLineItemID | The line item identifier from the target transaction. It is possible to link multiple billable expenses to the same TargetLineItemID. |
The PUT method is similar to the POST method however you can only create new linked transactions
Example request for creating a new linked transaction with source transaction details only (not assigned to a contact)
POST https://api.xero.com/api.xro/2.0/LinkedTransactions
Example request for creating a Linked Transaction assigned to a contact
POST https://api.xero.com/api.xro/2.0/LinkedTransactions
Example request for creating a fully allocated linked transaction
POST https://api.xero.com/api.xro/2.0/LinkedTransactions
Example request for updating a linked transaction to assign it to a contact
POST https://api.xero.com/api.xro/2.0/LinkedTransactions/c83947a9-5f57-47c4-bdb1-b77862207382
Example request for updating a linked transaction to allocate it to a target transaction
POST https://api.xero.com/api.xro/2.0/LinkedTransactions/c83947a9-5f57-47c4-bdb1-b77862207382
Example request to delete a linked transaction
DELETE https://api.xero.com/api.xro/2.0/LinkedTransactions/b05466c8-dc54-4ff8-8f17-9d7008a2e44b
