How Breadbox syncs, stores, and exposes transactions
Learn how Breadbox syncs, stores, and represents transactions from your connected bank accounts, including field definitions and amount conventions.
Breadbox automatically pulls transactions from your connected bank accounts on a scheduled sync. Each transaction is stored in your PostgreSQL database and exposed through the admin dashboard, REST API, and MCP server.
When you connect a bank account, Breadbox performs an initial sync that pulls your full available transaction history. After that, syncs run on the schedule you configure (every 4, 8, 12, or 24 hours) and also fire immediately whenever your bank pushes a webhook notification.Each sync fetches only the changes since the last run — new transactions, modifications to pending transactions, and removals. Breadbox processes these three lists atomically so your database stays consistent. You can trigger a manual sync at any time from the admin dashboard under Connections, or by calling POST /api/v1/sync from the REST API.
Every transaction record includes the following fields:
Field
Type
Description
id
UUID
Internal Breadbox identifier. Stable for the lifetime of the record.
short_id
string
8-character base62 alias for the same record. Accepted anywhere id is accepted.
account_id
UUID
The account this transaction belongs to. Set to null if the parent account is later removed (the transaction is preserved). See the Accounts API for account-level fields.
amount
decimal
Transaction amount. Positive = money out, negative = money in.
iso_currency_code
string
ISO 4217 currency code (e.g., USD). Never aggregate across different values.
date
date
Settlement date for posted transactions; occurrence date for pending ones. Format: YYYY-MM-DD.
name
string
Raw transaction description from the financial institution. Always populated.
merchant_name
string
Enriched, cleaned merchant name (e.g., McDonald's). May be null when the merchant cannot be identified.
Breadbox category slug when rules or a human/agent has assigned one (e.g., food_and_drink_groceries). Takes precedence over the provider fields for display and filtering.
category_override
string
Who last set the category: none (rule-applied or unset), agent (AI-set), or user (manually set — protected from automatic changes). Rules only update none rows; agents skip user rows.
pending
boolean
true if the transaction has not yet settled. false means posted.
The is what AI agents and MCP tools use when referring to transactions. You can pass either id or short_id to any API endpoint or MCP tool that accepts a transaction identifier.
A transaction starts as pending when the bank reports it but it has not yet settled. Pending transactions may change or be cancelled before they post.When a pending transaction settles, the bank may issue a new transaction ID for the posted version. Breadbox links the posted record back to the pending one and soft-deletes the pending row automatically, so you see only one record per transaction.Pending transactions are included in API responses and dashboard views by default. Use the pending=false query parameter to filter to posted transactions only.
For programmatic access, Breadbox offers two interfaces:
REST API — Use GET /api/v1/transactions with query parameters to filter (date, account, user, category, amount, search), sort, paginate, and filter by tags (tags= / any_tag=). See Transactions API for the full parameter list and Tags API for attaching and detaching tags.
MCP server — AI agents connect to Breadbox’s MCP server and use tools like query_transactions, count_transactions, and update_transactions to query, categorize, tag, and summarize in natural-language workflows. See MCP overview for setup and MCP Reference for the full tool list.
When your bank reports that a transaction has been removed (for example, a declined charge or a reissued pending transaction), Breadbox sets a deleted_at timestamp on the row rather than erasing it. The transaction disappears from normal API responses and dashboard views, but the record is never hard-deleted from your database. This preserves history and keeps any prior agent references consistent.
