Bank Transactions
| 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 add or update spend or receive money transactions. |
Elements for Bank Transactions
| The following are mandatory for a PUT / POST request | |
| <Type> | See Bank Transaction Types |
| <Contact> | See Contacts |
| <Lineitems> | See LineItems |
| <BankAccount> | Bank account for transaction |
| The following are optional for a PUT / POST request | |
| <Date> | Date of transaction – YYYY-MM-DD |
| <Reference> | reference for the transaction |
| <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 daily rate will be used |
| <Url> | URL link to a source document – shown as "Go to App Name" |
| <Status> | See Bank Transaction Status Codes |
| <SubTotal> | Total of bank transaction excluding taxes |
| <TotalTax> | Total tax on bank transaction |
| <Total> | Total of bank transaction tax inclusive |
| The following are only returned on a GET request | |
| <BankTransactionID> | Xero generated unique identifier for invoice |
| <UpdatedDateUTC> | Last modified date UTC format |
Elements for Line Items
The <LineItems> element can contain any number of individual <LineItem> sub-elements. At least one is required to create a bank transaction.
| All of these elements are returned on a GET request. | |
| <Description> | Description needs to be at least 1 char long. |
| <Quantity> | Quantity must be >= 0 |
| <UnitAmount> | Lineitem unit amount must be > 0 |
| <AccountCode> | AccountCode must be active for the organisation |
| The following are recommended for a PUT / POST request | |
| <Description> | LineItem Description |
| <Quantity> | LineItem Quantity |
| <UnitAmount> | LineItem Unit Amount |
| <AccountCode> | See Accounts |
| The following are optional for a PUT / POST request | |
| <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. |
POST BankTransactions
Use this method to create or update a SPEND MONEY or RECEIVE MONEY transaction.
Example of minimum elements required to add a new spend money transaction.
<BankTransaction>
<Type>SPEND</Type>
<Contact>
<Name>ABC Bank</Name>
</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 specifying a tracking category with a receive money transaction.
<BankTransaction>
<Type>RECEIVE</Type>
<Contact>
<Name>Flowers Ltd</Name>
</Contact>
<LineItems>
<LineItem>
<Description>Monthly Retainer</Description>
<UnitAmount>575.00</UnitAmount>
<AccountCode>200</AccountCode>
<Tracking>
<TrackingCategory>
<Name>Activity/Workstream</Name>
<Option>Website management</Option>
</Tracking>
</LineItem>
</LineItems>
<BankAccount>
<Code>BANK-ABC</Code>
</BankAccount>
<Url>http://www.accounting20.com</Url>
</BankTransaction>
If you are entering many bank transactions in a single API call then we recommend you utilise our new response format that shows validation errors for each invoice. 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 deleting a receive money transaction
<BankTransaction> <BankTransactionID>4af93d54-0d13-459a-9d8a-d570982e2fb2</BankTransactionID> <Status>VOIDED</Status> </BankTransaction>
PUT BankTransactions
The PUT method is similar to the POST BankTransactions method, however you can only create new bank transactions with this method.
GET BankTransactions
Use this method to retrieve either one or many bank transactions.
NB This endpoint does not return payments applied to invoices or transfers between bank accounts
Optional parameters
| Record filter | You can specify an individual record by appending the value to the endpoint, i.e. GET https://…/BankTransactions/{identifier} |
| InvoiceID – The Xero identifier for a Bank Transaction e.g. 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) |
Line amounts are inclusive of tax by default if you don’t specify this element
By default GET BankTransactions responses are formatted as XML. You can also retrieve responses in JSON format.
Examples for GET BankTransactions
Example 1. This is an example response when a filter has been applied to request just a single bank transaction. In this case the BankTransactionID of d20b6c54-7f5d-4ce6-ab83-55f609719126 was specified. NB The response format is more detailed compared with when bank transactions are returned. This response includes full line item details.
<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>
</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 2. GET BankTransactions with no filter applied. Notice the subtle differences from the example above. As many bank transactions are being returned only a summary of the contact is returned and no line details are returned – this is to keep the response more compact.
<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>