Transactions

Create

Creates a transaction.

POST /transactions
const response = await client.transactions.create(
  {
    account: {
      external_id: 'acct_external_123',
      id: 'ext_account_YWJjMTIz'
    },
    allocations: [],
    amount: '-1000',
    currency: 'USD',
    external_id: 'bank_txn_123',
    posted: '2024-01-13T00:00:00Z'
  }
);
Parameters
NameDescription
external_idstring, required

User-provided unique ID.

accountobject, required

External account for the transaction. Identify it by id, external_id, or both.

posteddatetime, required

Timestamp when the transaction was posted. Uses ISO 8601 format.

currencyADA | BTC | DAI | ..., required

ISO 4217 or crypto currency code.

amountInt64, required

Transaction amount, as a string in the smallest currency unit, such as cents for USD. Can be positive or negative.

allocationsobject[], required

Allocations for the transaction. An empty array indicates unreconciled funds.

tagsobject[]

Tags for the transaction.

Response
NameDescription
dataobject

Transaction object.

{
  "data": {
    "id": "txn_dHhuX2ZyYWdfMDAx",
    "external_id": "bank_txn_123",
    "account": {
      "id": "ext_account_YWJjMTIz",
      "external_id": "acct_external_123"
    },
    "posted": "2024-01-13T00:00:00Z",
    "currency": "USD",
    "amount": "-1000",
    "allocations": [
      {
        "invoice_id": "inv_abc123",
        "amount": "1000",
        "type": "invoice_payin",
        "user": {
          "id": "user_abc123",
          "external_id": "user_ext_001"
        }
      }
    ],
    "tags": [
      {
        "key": "department",
        "value": "engineering"
      }
    ],
    "unallocated_amount": "-1000",
    "created": "2024-01-13T00:00:00Z",
    "modified": "2024-01-13T00:00:00Z",
    "version": 1
  }
}

List

Lists all transactions.

GET /transactions
const response = await client.transactions.list(
  {
    account: 'ext_account_YWJjMTIz',
    reconciliation_status: 'reconciled'
  }
);
Parameters
NameDescription
reconciliation_statusreconciled | unreconciled

Filter by reconciliation status. reconciled returns transactions where unallocated_amount is 0. unreconciled returns transactions where unallocated_amount is not 0. Omit for all transactions.

accountstring

Filter by account id or external_id. If the account does not exist, returns an empty list.

Response
NameDescription
dataobject[]

List of transaction objects matching the filter criteria.

{
  "data": [
    {
      "id": "txn_dHhuX2ZyYWdfMDAx",
      "external_id": "bank_txn_123",
      "account": {
        "id": "ext_account_YWJjMTIz",
        "external_id": "acct_external_123"
      },
      "posted": "2024-01-13T00:00:00Z",
      "currency": "USD",
      "amount": "-1000",
      "allocations": [
        {
          "invoice_id": "inv_abc123",
          "amount": "1000",
          "type": "invoice_payin",
          "user": {
            "id": "user_abc123",
            "external_id": "user_ext_001"
          }
        }
      ],
      "tags": [
        {
          "key": "department",
          "value": "engineering"
        }
      ],
      "unallocated_amount": "-1000",
      "created": "2024-01-13T00:00:00Z",
      "modified": "2024-01-13T00:00:00Z",
      "version": 1
    }
  ]
}

List History

Retrieves the version history of a transaction.

GET /transactions/{transaction_ref}/history
const response = await client.transactions.listHistory('txn_abc123');
Parameters
NameDescription
transaction_refstring, required

Transaction id or external_id.

Response
NameDescription
dataobject[]

List of transaction versions over time, ordered by version, oldest first.

{
  "data": [
    {
      "id": "txn_dHhuX2ZyYWdfMDAx",
      "external_id": "bank_txn_123",
      "account": {
        "id": "ext_account_YWJjMTIz",
        "external_id": "acct_external_123"
      },
      "posted": "2024-01-13T00:00:00Z",
      "currency": "USD",
      "amount": "-1000",
      "allocations": [
        {
          "invoice_id": "inv_abc123",
          "amount": "1000",
          "type": "invoice_payin",
          "user": {
            "id": "user_abc123",
            "external_id": "user_ext_001"
          }
        }
      ],
      "tags": [
        {
          "key": "department",
          "value": "engineering"
        }
      ],
      "unallocated_amount": "-1000",
      "created": "2024-01-13T00:00:00Z",
      "modified": "2024-01-13T00:00:00Z",
      "version": 1
    }
  ]
}

Retrieve

Retrieves a transaction by ID or external ID.

GET /transactions/{transaction_ref}
const response = await client.transactions.retrieve('txn_abc123');
Parameters
NameDescription
transaction_refstring, required

Transaction id or external_id.

Response
NameDescription
dataobject

Transaction object.

{
  "data": {
    "id": "txn_dHhuX2ZyYWdfMDAx",
    "external_id": "bank_txn_123",
    "account": {
      "id": "ext_account_YWJjMTIz",
      "external_id": "acct_external_123"
    },
    "posted": "2024-01-13T00:00:00Z",
    "currency": "USD",
    "amount": "-1000",
    "allocations": [
      {
        "invoice_id": "inv_abc123",
        "amount": "1000",
        "type": "invoice_payin",
        "user": {
          "id": "user_abc123",
          "external_id": "user_ext_001"
        }
      }
    ],
    "tags": [
      {
        "key": "department",
        "value": "engineering"
      }
    ],
    "unallocated_amount": "-1000",
    "created": "2024-01-13T00:00:00Z",
    "modified": "2024-01-13T00:00:00Z",
    "version": 1
  }
}

Update

Updates a transaction.

PATCH /transactions/{transaction_ref}
const response = await client.transactions.update(
  'txn_abc123',
  {
    current_transaction_version: 1,
    tags: { set: [{ key: 'department', value: 'engineering' }] }
  }
);
Parameters
NameDescription
transaction_refstring, required

Transaction id or external_id.

current_transaction_versioninteger, required

Current version of the transaction. Must match the stored version.

tagsobject

Tag updates.

allocationsobject

Allocation updates.

Response
NameDescription
dataobject

Transaction object.

{
  "data": {
    "id": "txn_dHhuX2ZyYWdfMDAx",
    "external_id": "bank_txn_123",
    "account": {
      "id": "ext_account_YWJjMTIz",
      "external_id": "acct_external_123"
    },
    "posted": "2024-01-13T00:00:00Z",
    "currency": "USD",
    "amount": "-1000",
    "allocations": [
      {
        "invoice_id": "inv_abc123",
        "amount": "1000",
        "type": "invoice_payin",
        "user": {
          "id": "user_abc123",
          "external_id": "user_ext_001"
        }
      }
    ],
    "tags": [
      {
        "key": "department",
        "value": "engineering"
      }
    ],
    "unallocated_amount": "-1000",
    "created": "2024-01-13T00:00:00Z",
    "modified": "2024-01-13T00:00:00Z",
    "version": 1
  }
}

Search

Searches transactions.

POST /transactions/search
const response = await client.transactions.search(
  { filter: {} }
);
Parameters
NameDescription
filterobject, required

Filter for searching transactions.

page_infoobject

Pagination parameters.

Response
NameDescription
data_v2object

{
  "data_v2": {
    "transactions": [
      {
        "id": "txn_dHhuX2ZyYWdfMDAx",
        "external_id": "bank_txn_123",
        "account": {
          "id": "ext_account_YWJjMTIz",
          "external_id": "acct_external_123"
        },
        "posted": "2024-01-13T00:00:00Z",
        "currency": "USD",
        "amount": "-1000",
        "allocations": [
          {
            "invoice_id": "inv_abc123",
            "amount": "1000",
            "type": "invoice_payin",
            "user": {
              "id": "user_abc123",
              "external_id": "user_ext_001"
            }
          }
        ],
        "tags": [
          {
            "key": "department",
            "value": "engineering"
          }
        ],
        "unallocated_amount": "-1000",
        "created": "2024-01-13T00:00:00Z",
        "modified": "2024-01-13T00:00:00Z",
        "version": 1
      }
    ],
    "page_info": {
      "next_cursor": "string"
    }
  }
}

Search Allocations

Searches transaction allocations.

POST /transactions/allocations/search
const response = await client.transactions.searchAllocations(
  { filter: { invoice_id: { any: ['inv_abc123'] } } }
);
Parameters
NameDescription
filterobject, required

Filter for searching transaction allocations.

Response
NameDescription
dataobject[]

List of allocation search results.

{
  "data": [
    {
      "invoice_id": "inv_abc123",
      "amount": "1000",
      "type": "invoice_payin",
      "user": {
        "id": "user_abc123",
        "external_id": "user_ext_001"
      },
      "id": "alloc_abc123",
      "posted": "2024-01-13T00:00:00Z",
      "transaction": {
        "id": "txn_dHhuX2ZyYWdfMDAx",
        "external_id": "bank_txn_123"
      }
    }
  ]
}