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
Allows you to attach files to 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. 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
<CurrencyCode> The currency that invoice has been raised in (see Currencies)
<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
<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
<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
<HasAttachments> Boolean to indicate if a bank transaction has an attachment

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.
The following are recommended for a PUT / POST request
<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.
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 a (RECEIVE) receive money transaction using an item code of GB1-White. NB The price and account code of the item are not given so the default sales price and account code on the item will be used. If the UnitAmount and AccountCode element are specified then this will override the default UnitPrice value defined for the item.

<BankTransaction>
      <Type>RECEIVE</Type>
      <Contact>
        <Name>Westpac</Name>
      </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.

<BankTransaction>
      <Type>RECEIVE</Type>
      <Contact>
        <Name>Flowers Ltd</Name>
      </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>
          </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> 
<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

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

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>
      <LineAmountTypes>Inclusive</LineAmountTypes>
      <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>

Uploading an Attachment

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. e.g. https://api.xero.com/api.xro/2.0/BankTransactions/f0ec0d8c-6fce-4330-bb3b-8306278c6fd8/Attachments/image.png. See the Attachments page for more details.

e.g.

POST /api.xro/2.0/BankTransactions/f0ec0d8c-4330-bb3b-83062c6fd8/Attachments/Image002932.png
Authorization: OAuth...
Content Type: image/png
Content-Length: 10293

{RAW-IMAGE-CONTENT}

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>