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

GET BankTransactions

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

Optional parameters

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

Paging BankTransactions (recommended)

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>

POST 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 not equal 0. Line item amounts may be negative, but the total value for the document must be positive. 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

Creating, updating and deleting line items when updating bank transactions

In an update (POST) request:

  • Providing an existing LineItem with its LineItemID will update that line item.
  • Providing a LineItem with no LineItemID will create a new line item.
  • Not providing an existing LineItem with it's LineItemID will result in that line item being deleted.

SummarizeErrors

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.

Deleting spend and receive money transactions

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>

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. 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}

PUT BankTransactions

The PUT method is similar to the POST BankTransactions method, however you can only create new bank transactions with this method.