Skip to main content
The Transactions API allows you to create, update, delete, and retrieve financial transactions including income, expenses, and transfers.

​
create

Create a new transaction. 
await client.transactions.create({
  amount: "100.00",
  bankAccountId: "account-id",
  categoryId: "category-id",
  currency: "USD",
  date: new Date("2024-03-01"),
  description: "Grocery shopping",
  type: "EXPENSE"
})

​
Parameters

​
amount
string
required
Transaction amount as a string numeric literal (e.g., “100.00”)
​
bankAccountId
string
ID of the bank account for this transaction
​
categoryId
string
ID of the category for this transaction
​
currency
CurrencyCode
required
Currency code (e.g., “USD”, “EUR”, “GBP”)
​
date
Date
required
Date of the transaction
​
description
string
required
Description of the transaction
​
type
enum
required
Transaction type: INCOME, EXPENSE, or TRANSFER
​
notes
string
Optional notes about the transaction
​
tags
string[]
Optional array of tags for categorization
​
externalId
string
Optional external ID for tracking imported transactions
​
groupId
string
Optional group ID for organizing transactions
​
fromBankAccountId
string
Source bank account ID (only for TRANSFER transactions)
​
toBankAccountId
string
Destination bank account ID (only for TRANSFER transactions)

​
Response

​
id
string
Unique identifier for the transaction
​
amount
string
Transaction amount
​
currency
string
Currency code
​
date
Date
Transaction date
​
description
string
Transaction description
​
type
string
Transaction type
​
createdAt
Date
Timestamp when the transaction was created
​
updatedAt
Date
Timestamp when the transaction was last updated

​
createMany

Create multiple transactions in a single request. 
await client.transactions.createMany([
  {
    amount: "50.00",
    currency: "USD",
    date: new Date("2024-03-01"),
    description: "Coffee",
    type: "EXPENSE"
  },
  {
    amount: "1000.00",
    currency: "USD",
    date: new Date("2024-03-01"),
    description: "Salary",
    type: "INCOME"
  }
])

​
Parameters

​
transactions
array
required
Array of transaction objects (minimum 1 item). Each transaction object has the same structure as the create endpoint parameters.

​
Response

Returns an array of created transaction objects.

​
update

Update an existing transaction. 
await client.transactions.update({
  id: "transaction-id",
  amount: "150.00",
  description: "Updated grocery shopping",
  categoryId: "new-category-id"
})

​
Parameters

​
id
string
required
ID of the transaction to update
All other fields from the create endpoint are optional and can be updated.

​
Response

Returns the updated transaction object.

​
delete

Delete a transaction. 
await client.transactions.delete({
  id: "transaction-id"
})

​
Parameters

​
id
string
required
ID of the transaction to delete

​
Response

Returns the deleted transaction object.

​
deleteMany

Delete multiple transactions. 
await client.transactions.deleteMany([
  { id: "transaction-id-1" },
  { id: "transaction-id-2" }
])

​
Parameters

​
transactions
array
required
Array of objects with id field (minimum 1 item)

​
Response

Returns information about the deleted transactions.

​
getByDateRange

Retrieve transactions within a date range. 
await client.transactions.getByDateRange({
  from: new Date("2024-01-01"),
  to: new Date("2024-03-31")
})

​
Parameters

​
from
Date
required
Start date of the range
​
to
Date
required
End date of the range

​
Response

Returns an array of transactions within the specified date range.

​
getByCategory

Retrieve transactions for a specific category within a date range. 
await client.transactions.getByCategory({
  categoryId: "category-id",
  from: new Date("2024-01-01"),
  to: new Date("2024-03-31")
})

​
Parameters

​
categoryId
string
required
ID of the category to filter by
​
from
Date
required
Start date of the range
​
to
Date
required
End date of the range

​
Response

Returns an array of transactions for the specified category and date range.

​
parseOFX

Parse and import transactions from OFX/QFX files. 
await client.transactions.parseOFX({
  bankAccountId: "account-id",
  files: [ofxFile1, ofxFile2],
  shouldAutoCategorize: true,
  groupId: "import-group-id"
})

​
Parameters

​
bankAccountId
string
required
ID of the bank account to associate imported transactions with
​
files
File[]
required
Array of OFX or QFX files to parse (minimum 1 file). Files must have .ofx or .qfx extension.
​
shouldAutoCategorize
boolean
required
Whether to automatically categorize imported transactions
​
groupId
string
Optional group ID to organize imported transactions

​
Response

​
transactions
array
Array of imported transactions, sorted by date (newest first)
​
baseCurrency
string
Base currency code used for the import
​
convertedCurrencies
string[]
Array of currency codes that were converted during import
​
currencyExchangeAttribution
object
Attribution information for currency exchange rates used

​
TypeScript Types

type Transaction = {
  id: string
  externalId: string | null
  createdAt: Date
  updatedAt: Date
  type: "INCOME" | "EXPENSE" | "TRANSFER"
  date: Date
  amount: Intl.StringNumericLiteral
  currency: CurrencyCode
  description: string
  notes: string | null
  tags: string[] | null
  bankAccountId: string | null
  fromBankAccountId: string | null
  toBankAccountId: string | null
  categoryId: string | null
  groupId: string | null
  userId: string
}

type TransactionWithRelations = Transaction & {
  bankAccount: BankAccount | null
  fromBankAccount: BankAccount | null
  toBankAccount: BankAccount | null
  category: (Category & { parent: Category | null }) | null
  group: Group | null
}

Build docs developers (and LLMs) love

Get started for freeTalk to us