Transaction Object

A Transaction represents a single financial movement in an account, such as a purchase, transfer, payment, or deposit. Transactions include amount, description, category, and settlement status.

Attributes

Field	Type	Description
id	string	Unique identifier for the transaction. Format: `txn_ULID`
accountId	string	ID of the parent account
amount	number	Transaction amount in the smallest currency unit. Negative for debits (purchases, payments, withdrawals), positive for credits (deposits, refunds, incoming transfers)
currency	string	ISO 4217 currency code (e.g., `CLP`, `USD`)
description	string	Transaction description as provided by the bank. May include merchant name, reference numbers, or transfer details
category	string \| null	Transaction category. Possible values: `groceries`, `utilities`, `transport`, `entertainment`, `health`, `transfer`, `payment`, `income`, `other`
transactionDate	string	Date when the transaction occurred, in ISO 8601 format. Time component is typically `00:00:00.000Z` as banks usually provide date-only precision
status	string	Settlement status: `pending` (not yet settled, may change or be reversed) or `posted` (settled and finalized)
createdAt	string	ISO 8601 timestamp when the transaction was first synced to Araucaria
previousTransactionId	string \| undefined	Id of the transaction this one replaced. Present only when a pending transaction on a Plaid-linked connection posted — see Plaid Pending → Posted Transactions

Amount Sign Convention

Transaction amounts follow standard accounting conventions:

Negative amounts (-) represent money leaving the account: purchases, bill payments, outgoing transfers, fees
Positive amounts (+) represent money entering the account: deposits, refunds, incoming transfers, interest

Transaction Status

pending - Transaction is authorized but not yet settled. Amount may change (e.g., tip added) or transaction may be reversed
posted - Transaction has been settled and is final. Will not change unless a separate reversal transaction occurs

💡 Plaid: Pending → Posted

On Plaid-linked connections, a pending transaction posting is a delete + new row, not an update — the old id is gone and previousTransactionId on the new row is your only link back to it. See Plaid Pending → Posted Transactions for the recommended way to handle this.

Example

json

              {
  "id": "txn_01HQ3K5J7X8Y9Z0A1B2C3D4E5F",
  "accountId": "acc_01HQ3K5J7X8Y9Z0A1B2C3D4E5F",
  "amount": -137900,
  "currency": "CLP",
  "description": "Enel",
  "category": "utilities",
  "transactionDate": "2024-01-15T00:00:00.000Z",
  "status": "posted",
  "createdAt": "2024-01-15T10:30:00Z"
}
            

Example: Plaid Pending → Posted

A posted transaction that promoted a Plaid pending transaction carries previousTransactionId:

json

              {
  "id": "txn_01HQ3K5J7X8Y9Z0A1B2C3D4E7H",
  "accountId": "acc_01HQ3K5J7X8Y9Z0A1B2C3D4E5F",
  "amount": -450,
  "currency": "USD",
  "description": "Coffee Shop",
  "transactionDate": "2024-01-16",
  "status": "posted",
  "createdAt": "2024-01-16T09:15:00Z",
  "previousTransactionId": "txn_01HQ3K5J7X8Y9Z0A1B2C3D4E5G"
}
            