Bank Transactions


Overview

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

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. See BankAccount
The following are optional for a PUT / POST request
<IsReconciled> Boolean to show if transaction is reconciled
<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.

Elements for Bank Account


Only accounts of Type BANK will be accepted.

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

POST BankTransactions

Use this method to create or update a spend money, receive money, spend prepayment, receive prepayment, spend overpayment or receive overpayment transaction

Note – you cannot create transfers using PUT/POST BankTranasctions at this time. Support for these will be added in a future release

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>

Example of creating a receive prepayment

<BankTransaction>
<Contact><Name>Joe Blogs</Name></Contact>
<Type>RECEIVE-PREPAYMENT</Type>
<BankAccount><Code>090</Code></BankAccount> 
<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

<BankTransaction>
<Contact><Name>Danger Mouse</Name></Contact>
<Type>RECEIVE-OVERPAYMENT</Type>
<BankAccount><Code>090</Code></BankAccount> 
<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.

Example of marking a bank transaction as reconciled

Conversion related apps can utilise the IsReconciled flag in scenarios when a matching bank statement line is not available. Learn more

    <BankTransaction>
      <Type>SPEND</Type>
      <Contact>
        <Name>Westpac</Name>
      </Contact>
      <Date>2014-01-21T00:00:00</Date>
      <LineItems>
        <LineItem>
          <Description>Yearly Bank Account Fee</Description>
          <Quantity>1.0000</Quantity>
          <UnitAmount>20.00</UnitAmount>
          <AccountCode>404</AccountCode>
        </LineItem>
      </LineItems>
      <BankAccount>
        <Code>090</Code>
      </BankAccount>
      <IsReconciled>true</IsReconciled>
    </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>DELETED</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>