| URL | https://api.xero.com/api.xro/2.0/BankTransactions |
| Methods Supported | GET, PUT, POST |
| Description | Allows you to retrieve any spend or receive money transactions Allows you to create or update spend or receive money transactions Allows you to create a receive or spend overpayment Allows you to create a receive or spend prepayment Allows you to attach files to spend or receive money transactions |
Use this method to retrieve one or many bank transactions.
This endpoint does not return payments applied to invoices, expense claims or transfers between bank accounts.
The following elements are returned in the BankTransactions response
| Type | See Bank Transaction Types |
| Contact | See Contacts |
| Lineitems | See LineItems. The LineItems element can contain any number of individual LineItem sub-elements. |
| BankAccount | Bank account for transaction. See BankAccount |
| IsReconciled | Boolean to show if transaction is reconciled |
| Date | Date of transaction - YYYY-MM-DD |
| Reference | Reference for the transaction. Only supported for SPEND and RECEIVE transactions. |
| CurrencyCode | The currency that bank transaction has been raised in (see Currencies). Setting currency is only supported on overpayments. |
| CurrencyRate | Exchange rate to base currency when money is spent or received. e.g. 0.7500 Only used for bank transactions in non base currency. Setting currency is only supported on overpayments. |
| Url | URL link to a source document - shown as "Go to App Name" |
| Status | See Bank Transaction Status Codes |
| LineAmountTypes | See Line Amount Types |
| SubTotal | Total of bank transaction excluding taxes |
| TotalTax | Total tax on bank transaction |
| Total | Total of bank transaction tax inclusive |
| BankTransactionID | Xero generated unique identifier for bank transaction |
| PrepaymentID | Xero generated unique identifier for a Prepayment. This will be returned on BankTransactions with a Type of SPEND-PREPAYMENT or RECEIVE-PREPAYMENT |
| OverpaymentID | Xero generated unique identifier for an Overpayment. This will be returned on BankTransactions with a Type of SPEND-OVERPAYMENT or RECEIVE-OVERPAYMENT |
| UpdatedDateUTC | Last modified date UTC format |
| HasAttachments | Boolean to indicate if a bank transaction has an attachment |
| Elements for Line Items | |
| Description | The description of the line item |
| Quantity | LineItem Quantity |
| UnitAmount | Lineitem unit amount. By default, unit amount will be rounded to two decimal places. You can opt in to use four decimal places by adding the querystring parameter unitdp=4 to your query. See the Rounding in Xero guide for more information. |
| AccountCode | See Accounts |
| ItemCode | ItemCode can only be present when the Bank Transaction Type is SPEND or RECEIVE. |
| LineItemID | The Xero generated identifier for a LineItem. |
| TaxType | Used as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes. |
| LineAmount | The total of the line including discount |
| Tracking | Optional Tracking Category - see Tracking. Any LineItem can have a maximum of 2 TrackingCategory elements. |
| Elements for Bank Account | |
| Code | BankAccount code (this value may not always be present for a bank account) |
| AccountID | BankAccount identifier |
| Record filter | You can specify an individual record by appending the BankTransactionID to the endpoint, i.e. GET https://.../BankTransactions/297c2dc5-cc47-4afd-8ec8-74990b8761e9 |
| Modified After | The ModifiedAfter filter is actually an HTTP header: 'If-Modified-Since'. A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only bank transactions created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00 |
| Where | Filter by an any element (see Filters) |
| order | Order by any element returned (see Order By) |
| page | e.g. page=1 – Up to 100 bank transactions will be returned in a single API call with line items shown for each bank transaction |
To utilise paging, 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.
By using paging all the line item details for each bank transaction are returned which may avoid the need to retrieve each individual bank transaction.
Example response when retrieving a single BankTransaction
GET https://api.xero.com/api.xro/2.0/BankTransactions/d20b6c54-7f5d-4ce6-ab83-55f609719126
<BankTransactions>
<BankTransaction>
<Contact>
<ContactID>c09661a2-a954-4e34-98df-f8b6d1dc9b19</ContactID>
<ContactStatus>ACTIVE</ContactStatus>
<Name>BNZ</Name>
<Addresses>
<Address>
<AddressType>POBOX</AddressType>
</Address>
<Address>
<AddressType>STREET</AddressType>
</Address>
</Addresses>
<Phones>
<Phone>
<PhoneType>DEFAULT</PhoneType>
</Phone>
<Phone>
<PhoneType>MOBILE</PhoneType>
</Phone>
<Phone>
<PhoneType>DDI</PhoneType>
</Phone>
<Phone>
<PhoneType>FAX</PhoneType>
</Phone>
</Phones>
<UpdatedDateUTC>2010-09-17T19:26:39.157</UpdatedDateUTC>
</Contact>
<Date>2010-07-30T00:00:00</Date>
<LineAmountTypes>Inclusive</LineAmountTypes>
<LineItems>
<LineItem>
<Description>Monthly account fee</Description>
<UnitAmount>15</UnitAmount>
<TaxType>NONE</TaxType>
<TaxAmount>0.00</TaxAmount>
<LineAmount>15.00</LineAmount>
<AccountCode>404</AccountCode>
<Quantity>1.0000</Quantity>
<LineItemID>52208ff9-528a-4985-a9ad-b2b1d4210e38</LineItemID>
</LineItem>
</LineItems>
<SubTotal>15.00</SubTotal>
<TotalTax>0.00</TotalTax>
<Total>15.00</Total>
<UpdatedDateUTC>2008-02-20T12:19:56.657</UpdatedDateUTC>
<FullyPaidOnDate>2010-07-30T00:00:00</FullyPaidOnDate>
<BankTransactionID>d20b6c54-7f5d-4ce6-ab83-55f609719126</BankTransactionID>
<BankAccount>
<AccountID>297c2dc5-cc47-4afd-8ec8-74990b8761e9</AccountID>
<Code>BANK</Code>
</BankAccount>
<Type>SPEND</Type>
<IsReconciled>true</IsReconciled>
</BankTransaction>
</BankTransactions>
Example response when retrieving a collection of BankTransactions
GET https://api.xero.com/api.xro/2.0/BankTransactions
<BankTransactions>
<BankTransaction>
<Contact>
<ContactID>c09661a2-a954-4e34-98df-f8b6d1dc9b19</ContactID>
<Name>BNZ</Name>
</Contact>
<Date>2010-07-30T00:00:00</Date>
<LineAmountTypes>Inclusive</LineAmountTypes>
<SubTotal>15.00</SubTotal>
<TotalTax>0.00</TotalTax>
<Total>15.00</Total>
<UpdatedDateUTC>2008-02-20T12:19:56.657</UpdatedDateUTC>
<FullyPaidOnDate>2010-07-30T00:00:00</FullyPaidOnDate>
<BankTransactionID>d20b6c54-7f5d-4ce6-ab83-55f609719126</BankTransactionID>
<BankAccount>
<AccountID>297c2dc5-cc47-4afd-8ec8-74990b8761e9</AccountID>
<Code>BANK</Code>
</BankAccount>
<Type>SPEND</Type>
<IsReconciled>true</IsReconciled>
</BankTransaction>
....
</BankTransactions>
Use this method to create spend money, receive money, spend prepayment, receive prepayment, spend overpayment or receive overpayment transactions.
It can also be used to update spend money and receive money transactions. Updates on spend prepayment, receive prepayment, spend overpayment or receive overpayment transactions are NOT currently supported.
Note - you cannot create transfers using PUT/POST BankTranasctions. To create a bank transfer you need to use the BankTransfers endpoint.
| The following are mandatory for a PUT / POST request | |
| Type | See Bank Transaction Types |
| Contact | See Contacts |
| Lineitems | See LineItems. The LineItems element can contain any number of individual LineItem sub-elements. At least one is required to create a bank transaction. |
| BankAccount | Bank account for transaction. See BankAccount. Only accounts of Type BANK will be accepted. |
| The following are optional for a PUT / POST request | |
| IsReconciled | Boolean to show if transaction is reconciled. Conversion related apps can set the IsReconciled flag in scenarios when a matching bank statement line is not available. Learn more |
| Date | Date of transaction - YYYY-MM-DD |
| Reference | Reference for the transaction. Only supported for SPEND and RECEIVE transactions. |
| CurrencyCode | The currency that bank transaction has been raised in (see Currencies). Setting currency is only supported on overpayments. |
| CurrencyRate | Exchange rate to base currency when money is spent or received. e.g. 0.7500 Only used for bank transactions in non base currency. If this isn't specified for non base currency accounts then either the user-defined rate (preference) or the XE.com day rate will be used. Setting currency is only supported on overpayments. |
| Url | URL link to a source document - shown as "Go to App Name" |
| Status | See Bank Transaction Status Codes |
| LineAmountTypes | Line amounts are exclusive of tax by default if you don't specify this element. See Line Amount Types |
| Elements for Line Items | |
| Description | Description needs to be at least 1 char long. |
| Quantity | Quantity must be >= 0 |
| UnitAmount | Lineitem unit amount must be >0. By default, unit amount will be rounded to two decimal places. You can opt in to use four decimal places by adding the querystring parameter unitdp=4 to your query. See the Rounding in Xero guide for more information. |
| AccountCode | AccountCode must be active for the organisation. See Accounts |
| ItemCode | ItemCode can only be used when the Bank Transaction Type is SPEND or RECEIVE. If Description, UnitAmount or AccountCode are not specified, then the defaults from the Item will be applied. |
| LineItemID | The Xero generated identifier for a LineItem. If LineItemIDs are not included with line items in an update request then the line items are deleted and recreated. |
| TaxType | Used as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes. |
| LineAmount | If you wish to omit either of the Quantity or UnitAmount you can provide a LineAmount and Xero will calculate the missing amount for you |
| Tracking | Optional Tracking Category - see Tracking. Any LineItem can have a maximum of 2 TrackingCategory elements. |
| Elements for Bank Account. Either of the following are mandatory for a PUT / POST request | |
| Code | BankAccount code (this value may not always be present for a bank account) |
| AccountID | BankAccount identifier |
In an update (POST) request:
If you are entering many bank transactions in a single API call then we recommend you utilise our response format that shows validation errors for each bank transaction. The new response messages for validating bulk API calls would mean a breaking change so to utilise this functionality you’ll need to append ?SummarizeErrors=false to the end of your API calls e.g. POST /api.xro/2.0/BankTransactions?SummarizeErrors=false
Example of minimum elements required to add a new spend money transaction.
POST https://api.xero.com/api.xro/2.0/BankTransactions
<BankTransaction>
<Type>SPEND</Type>
<Contact>
<ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
</Contact>
<LineItems>
<LineItem>
<Description>Yearly Bank Account Fee</Description>
<UnitAmount>20.00</UnitAmount>
<AccountCode>404</AccountCode>
</LineItem>
</LineItems>
<BankAccount>
<Code>BANK-ABC</Code>
</BankAccount>
</BankTransaction>
Example of a receive money transaction using an item code of GB1-White.
POST https://api.xero.com/api.xro/2.0/BankTransactions
<BankTransaction>
<Type>RECEIVE</Type>
<Contact>
<ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
</Contact>
<Date>2014-05-26T00:00:00</Date>
<LineAmountTypes>Exclusive</LineAmountTypes>
<LineItems>
<LineItem>
<Description>Golf balls - white single</Description>
<Quantity>5</Quantity>
<ItemCode>GB1-White</ItemCode>
</LineItem>
</LineItems>
<BankAccount>
<Code>090</Code>
</BankAccount>
</BankTransaction>
Example of specifying a tracking category with a receive money transaction.
POST https://api.xero.com/api.xro/2.0/BankTransactions
<BankTransaction>
<Type>RECEIVE</Type>
<Contact>
<ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
</Contact>
<LineAmountTypes>Inclusive</LineAmountTypes>
<LineItems>
<LineItem>
<Description>Monthly Retainer</Description>
<UnitAmount>575.00</UnitAmount>
<AccountCode>200</AccountCode>
<Tracking>
<TrackingCategory>
<Name>Activity/Workstream</Name>
<Option>Website management</Option>
</TrackingCategory>
</Tracking>
</LineItem>
</LineItems>
<BankAccount>
<Code>BANK-ABC</Code>
</BankAccount>
<Url>http://www.accounting20.com</Url>
</BankTransaction>
Example of creating a receive prepayment
POST https://api.xero.com/api.xro/2.0/BankTransactions
<BankTransaction>
<Type>RECEIVE-PREPAYMENT</Type>
<Contact>
<ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
</Contact>
<BankAccount><Code>090</Code></BankAccount>
<LineAmountTypes>Exclusive</LineAmountTypes>
<LineItems>
<LineItem>
<Description>Prepayment for Kitchen Designs</Description>
<Quantity>1</Quantity>
<UnitAmount>500.00</UnitAmount>
<AccountCode>200</AccountCode>
</LineItem>
<LineItem>
<Description>Prepayment for Kitchen materials</Description>
<Quantity>1</Quantity>
<UnitAmount>1000.00</UnitAmount>
<AccountCode>200</AccountCode>
</LineItem>
</LineItems>
</BankTransaction>
Example of creating a receive-overpayment
POST https://api.xero.com/api.xro/2.0/BankTransactions
<BankTransaction>
<Type>RECEIVE-OVERPAYMENT</Type>
<Contact>
<ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
</Contact>
<BankAccount><Code>090</Code></BankAccount>
<LineAmountTypes>NoTax</LineAmountTypes>
<LineItems>
<LineItem>
<Description>Forgot to cancel annual sub payment</Description>
<LineAmount>100.00</LineAmount>
</LineItem>
</LineItems>
</BankTransaction>
Overpayments can only have a single line item. The line item will be automated coded to either the Accounts Receivable (receive) or Accounts Payable (spend) control account. You will see this account code contained in the response.
You can delete a spend money or receive money transaction by updating the Status to DELETED. Deletes are not supported for spend prepayment, receive prepayment, spend overpayment or receive overpayment transactions.
Example of deleting a BankTransaction
POST https://api.xero.com/api.xro/2.0/BankTransactions/4af93d54-0d13-459a-9d8a-d570982e2fb2
<BankTransaction> <BankTransactionID>4af93d54-0d13-459a-9d8a-d570982e2fb2</BankTransactionID> <Status>DELETED</Status> </BankTransaction>
You can upload up to 10 attachments(each up to 3mb in size) per bank transaction, once the bank transaction has been created in Xero. To do this you'll need to know the ID of the bank transaction which you'll use to construct the URL when POST/PUTing a byte stream containing the attachment file. See the Attachments page for more details.
POST https://api.xero.com/api.xro/2.0/BankTransactions/f0ec0d8c-4330-bb3b-83062c6fd8/Attachments/Image002932.png
Headers:
Authorization: OAuth...
Content Type: image/png
Content-Length: 10293
Body:
{RAW-IMAGE-CONTENT}