Write bank transactions to Xero

Learn how to write your SMB users' bank transactions via our Xero Bank Feeds integration

When an SMB user has set up a bank feed connection, you can write bank transactions for source bank accounts to Xero. The source account must have connected status, where the SMB user has completed the step of mapping and connecting the account.

Auto-download not supported

Transactions are not automatically downloaded to Xero when the user successfully connects a bank account. They must be written as described later in this article.

This article explains how to:

• View the details of source bank accounts, including their connection statuses.
• Write bank transactions to a target bank account in Xero.

Prerequisites

• You've set up the Xero Bank Feeds integration.

View bank account details

Call the GET connectionInfo/bankFeedAccounts endpoint to view details of the source bank accounts for a specified company and data connection.

List bank feed bank accounts

GET /companies/{connectionId}/connections/{connectionId}/connectionInfo/bankFeedAccounts

The response lists all source bank accounts and their statuses—either pending, connected, or disconnected. The feedStartDate property is returned for connected bank accounts only.

Response example - List bank feed bank accounts (200)

[
  {
    "id": "acc-002", // the ID of the source bank account
    "accountName": "account-081",
    "accountType": "Credit",
    "accountNumber": "1234",
    "sortCode": "123456",
    "currency": "GBP",
    "balance": 99.99,
    "modifiedDate": "2023-01-09T13:46:59.4019628Z",
    "status": "pending" // bank account connection status
  },
  {
    "id": "acc-003",
    "accountName": "account-095",
    "accountType": "Debit",
    "accountNumber": "12345671",
    "sortCode": "123456",
    "currency": "GBP",
    "balance": 100.09,
    "modifiedDate": "2023-01-09T13:46:59.4019628Z",
    "status": "connected",
    "feedStartDate": "2023-01-09T14:56:43.773Z" // only for connected accounts
  }
]

Requirements for writing bank transactions to Xero

When writing bank transactions to Xero:

• You can only write bank transactions to one target account at a time.
• Within a single request, the array of transactions must be in chronological order.
• Transactions must have a date set to the current day or earlier, but be aware of the limitation described in "Writing historic transactions", below.
• A maximum of 1000 transactions can be written at a time.

Writing historic transactions

The feedStartDate on the source bank account is determined by the Feed start date selected by the SMB user in the account mapping UI, but it is not enforced and should be used as a guide.

You can write bank transactions to Xero which are dated up to one year prior to the current date. Write operations that contain bank transactions dated older than one year will fail.

Write bank transactions to Xero

To write bank transactions for a connected source bank account, make the following requests to the Codat API. All write requests are asynchronous. Bank feeds transactions are sent to Xero immediately, not on a schedule.

1. Post the bank transactions using the POST /push/bankAccounts/{accountId}/bankTransactions endpoint:

   Create bank transactions

   POST https://api.codat.io/companies/{companyId}/connections/{connectionId}/push/bankAccounts/{accountId}/bankTransactions

   For the accountId, supply the ID of a connected source bank account (returned from the GET /connectionInfo/BankFeedAccounts request).

   Example request body (all fields are required)

   {
     "accountId": "482342-acc-001", // source bank account ID
     "transactions": [
       {
         "id": "7832323211-GIF",
         "amount": -450,
         "balance": 2000,
         "date": "2022-08-30T17:05:12.191Z", // max. 1 year old
         "description": "events-hospitality",
         "transactionType": "Debit"
       },
       {
         "id": "7832323211-SDC",
         "amount": -730,
         "balance": 2730,
         "date": "2022-08-31T11:06:49.191Z",
         "description": "corporate-training",
         "transactionType": "Debit"
       }
     ]
   }

   The balance of the last bank transaction in the array is used to update the balance of the specified bank account.

   Positive and negative transactions

   Credit transactions are positive and debit transactions are negative, so it's important that the sign of the transaction amount is consistent with the transactionType. A warning is returned from Codat if, for example, a $100 transaction is sent to Xero as a Debit. Be aware that Xero does not reverse a credit card transaction that was sent as a negative amount, and vice versa for a debit card transaction.

2. If the data is valid, the endpoint returns a write operation with a status of Pending (202). The status changes to Success if the write operation completes successfully.

   Pending status

   The write operation status might remain in Pending for some time while Xero processes the bank transactions.

3. Repeat the POST /push/bankAccounts/{accountId}/bankTransactions request for the remainder of the user's source bank accounts.

In the SMB user's Xero package, new bank transactions for the target account will appear on the Incoming Bank Transactions UI.