Skip to Content
@get-asset/sdkComponents

Transactions

Headless compound that fetches the business's transactions and exposes them as table rows — date, description, the external account, the amount with the currency it's denominated in, and what the transaction is: a category, a split across categories, or a payment against a bill or invoice. Each row's field is a picker with a Categorize | Match switch (see Categorize or match): picking stages the row, and the tick (Transactions.Confirm) records it and confirms the row in one action. Confirmed rows stay editable — a pick there writes at once. Do it yourself shows “For Review” / “Confirmed” and no Status column in the styled table; Done for you shows “In Review” / “Needs Attention” / “Confirmed” and keeps the bookkeeper note (Transactions.Comment, 💬), which posts to the journal entry and then sets bookkeeper_pending, even on previously confirmed rows. The agent feedback form (✕) is off by default and comes back with feedback; its submissions collapse the section and show “Reviewing…”, a transient loading state while the agent recategorises. The table can be filtered by status and by external account — exposed via useTransactions() and applied to the fetch. Results are paginated: a HasMore banner with a LoadMore link fetches and appends the next page. Payments against bills and invoices are listed with their payments, so a matched row stays in the table.

Anatomy

Import the primitive and compose the parts you need.

<Transactions.Root>  <Transactions.Success>    <Transactions.Rows>      <Transactions.Row>        <Transactions.Date />        <Transactions.Description />        <Transactions.Account />        <Transactions.Amount />        <Transactions.Currency />        <Transactions.Status />        {/* the Categorize or match field: open a picker over useTransactions() */}        <Transactions.Treatment />        <Transactions.HasTags>          {/* tag UI */}        </Transactions.HasTags>        {/* Action parts are freely composable. The styled table chooses by plan. */}        <Transactions.Pending>          <Transactions.Confirm />        </Transactions.Pending>        <Transactions.ProvideContext />        <Transactions.Comment />      </Transactions.Row>      <Transactions.SplitEditor>        {/* split lines, Left to split, Save — from useTransactions() */}      </Transactions.SplitEditor>      <Transactions.Context>        {/* inline chat or bookkeeper-note form, based on contextKind */}      </Transactions.Context>    </Transactions.Rows>    <Transactions.HasMore>      <Transactions.LoadMore>Show more</Transactions.LoadMore>    </Transactions.HasMore>  </Transactions.Success></Transactions.Root>

Required scopes

The access token used by AssetProvider must include these scopes for this primitive to fetch data successfully:

  • transaction:read
  • transaction:update
  • ledger:read
  • bill:read
  • invoice:read
  • vendor:read
  • customer:read
  • bill:create
  • bill:delete
  • invoice:create
  • invoice:delete
  • external_account:read
  • business:read
  • tag:read
  • journal_entry:read
  • journal_entry:create
  • chat:create

API reference

Root props

PropTypeDefaultDescription
dateFromCalendarDateString—Inclusive start (YYYY-MM-DD) of a fixed reporting range. Setting it detaches the table from the provider's shared range entirely; must be paired with dateTo (one without the other throws). Use periodDateRange to derive the pair from a month, quarter, or year.
dateToCalendarDateString—Inclusive end (YYYY-MM-DD) of a fixed reporting range. Must be paired with dateFrom. Omit both to follow the provider's DatePicker-driven range.
accountIdsstring[]—Only include transactions for these external account ids.
ledgerTypeLedgerType—Only include transactions whose journal entry has a line in a ledger of this type (e.g. "expense"). Always applied to the fetch. Ignored when ledgerSubtype is also set — the subtype is more granular and already implies its type.
ledgerSubtypeLedgerSubType—Only include transactions whose journal entry has a line in a ledger of this subtype (e.g. "operating_expense"). Always applied to the fetch. Takes precedence over ledgerType — when both are set only the subtype is sent to the API.
defaultStatusFilterstring—Pre-select the status filter using an API value or "all". Managed offers "business_pending" (Needs Attention), "bookkeeper_pending" (In Review), and "confirmed" (Confirmed); DIY/core offer "bookkeeper_pending" (For Review) and "confirmed". Uncontrolled — the user can still change it.
defaultAccountFilterstring—Pre-select the account filter (an external account id, or "all"). A specific account overrides accountIds. Uncontrolled — the user can still change it.
pageSizenumber—Page size passed to the API.
entriesTransactionOverride[]—Override the rows shown (skips the API fetch). Used by storybook/tests.
tagFieldsTransactionTagField[]—Override the fetched tag fields (name + values), skipping the fetch. Pass [] to hide all tag UI; omit to fetch the business's fields with their values.
allowCreateTagbooleantrueAllow consumers to offer creation of new tag values (see Tags).
plan"managed" | "diy" | "core"—Override the business plan — "managed" (Done for you), or "diy" / "core" (Do it yourself, identical behaviour); skips the business fetch. Drives status labels, filter options, and actions (see Plan behaviour). Defaults to the fetched plan, or "managed".
hasMoreboolean—Force the load-more banner when using entries (storybook/tests).
state"loading" | "error" | "empty"—Force a specific state for testing.
showCurrencyboolean—Force the ISO code beside each amount on or off, skipping the business fetch (storybook/tests). By default it shows only for a business that holds money in more than one currency.
feedbackbooleanfalseOffer the agent feedback form (✕) on Do it yourself rows, and open it on row click. Off by default — the picker and the tick replace it. Done for you rows keep the bookkeeper note either way (see Plan behaviour).
onAddRecord(transaction, kind: "bill" | "invoice") => void—Called by Add bill / Add invoice in the Match tab with the transaction and the kind, so the host can open its own Bills or Invoices component. The table writes nothing; once the host's lists refresh, the new record is offered like any other. Omit it to hide the action.
onRecorded(transaction, treatment: TransactionTreatment) => void—Called after a row's treatment is recorded — by the tick, or by a pick on a confirmed row.
categoryOptionsTransactionCategoryOptionOverride[]—Override the Categorize list ({ id, name, parentId? }), skipping the ledger fetch. Used by storybook/tests.
openBills / openInvoicesTransactionMatchRecordOverride[]—Override the open bills (money out) and open invoices (money in) offered in the Match tab ({ id, party?, number, dueAt, outstanding, currency? }), skipping their fetches. Used by storybook/tests.
onConfirmed(transaction) => void—Called after the tick confirms a transaction (its treatment recorded and its status set to confirmed).
onContextSubmitted(transaction, message) => void—Notification fired after either the note and status write succeed or the agent chat finishes (including the self-serve status write). Receives the transaction and the message for both kinds.
onTagsChanged(transaction, field, values) => void—Notification hook fired once per edited field after a successful tag write (see Tags).
childrenrequiredReactNode—Compound parts.

Parts

Container

Always rendered. Fetches transactions and external accounts, and provides context.

PartDescription
Transactions.RootOwns fetching (transactions, accounts, categories, open bills and invoices), the staged treatments, the record writes, the split draft, the context callback, and the inline-form state.

Success

Renders when at least one transaction is available.

PartDescription
Transactions.SuccessState wrapper. Compose the table inside.
Transactions.RowsIterates the rows, providing a per-row context to each.
Transactions.Row
asChild?
Per-row wrapper. Adds data-status and data-direction.
Transactions.Date
asChild?, format?
Posting date — shows "Apr 30"; sets dateTime + a full-date title (pair with <time> via asChild). Pass format(date) to override.
Transactions.Description
asChild?
The transaction's description.
Transactions.Account
asChild?
Name of the external account the transaction belongs to.
Transactions.Amount
asChild?, format?
Signed amount (negative for money out). format receives (amount, currency) — the row's ISO 4217 code, or null — so it can print the symbol that goes with this row's money. Adds data-direction (inflow/outflow).
Transactions.Currency
asChild?
ISO 4217 code the amount is denominated in — the currency of the transaction's external account. Meant to sit beside Amount; renders nothing when the account reports no currency of its own. Adds data-currency. Renders nothing at all unless the business holds money in more than one currency.
Transactions.Status
asChild?, format?
Lifecycle status label, plan-dependent — Done for you: Needs Attention / In Review / Confirmed; DIY/core: For Review / Confirmed, including defensive business_pending overrides. Reviewing… is a transient loading state while the agent recategorises, not a backend status. Adds data-status.
Transactions.Treatment
asChild?, format?
What the field reads: the category name, "N categories" for a split, "party · number" for a match, or "Choose a category" — the staged treatment, else an exact-amount suggestion, else what is recorded. Adds data-treatment (none / category / split / match) and data-staged when the tick would write it.
Transactions.Category
asChild?
Name of the first recorded category.
Transactions.Split / SingleGates that render only for split (multi-category) / single-category transactions.
Transactions.LinesIterates the transaction's category lines, providing a per-line context.
Transactions.LineName
asChild?
A split line's category name (inside <Lines>).
Transactions.LineAmount
asChild?, format?
A split line's signed amount (inside <Lines>). format receives (amount, currency) — a line is part of the transaction, so it carries the row's currency.
Transactions.HasTagsRenders children only when the business defines at least one tag field (see Tags).
Transactions.PendingRenders children while the transaction still needs review.
Transactions.ConfirmedRenders children once the transaction's status is confirmed.
Transactions.Confirm
asChild?
The tick. Records the row's treatment and confirms it in one action — the line items for a category or split, or a payment for a match, then the status. A row with nothing staged confirms as it is. Disabled while the write is in flight, while the agent reviews the row, and while its split is expanded. Adds data-staged and data-recording.
Transactions.ProvideContext
asChild?
Button that opens the inline form with contextKind="chat" on any status. Submitting runs the agent chat; only self-serve plans set bookkeeper_pending afterward. Available to headless consumers on any plan; the styled table offers it on Do it yourself rows only with feedback.
Transactions.Comment
asChild?
Opens the inline form with contextKind="note" on any status; submitting posts a journal-entry note, then sets bookkeeper_pending, including previously confirmed rows. Shown beside the tick on Done for you rows in the styled table; headless consumers can compose it freely.
Transactions.Trigger
asChild?
Toggles an optional headless details panel on click. The styled table instead opens the note or feedback form when a row is clicked.
Transactions.DetailsRenders children while the optional headless details panel is expanded. The styled table puts the split breakdown inside the context form.
Transactions.ContextRenders children while the row's context form is open.
Transactions.SplitEditorRenders children while the row's split is expanded (after openSplit). Compose the lines from splitLines / setSplitLine / addSplitLine / removeSplitLine, the figure from splitSummary, and Save from saveSplit.
Transactions.HasMoreRenders children (the load-more banner) only when another page can be fetched.
Transactions.LoadMore
asChild?
Button/link that fetches and appends the next page. Sets data-loading while in flight.

Loading

Renders while the fetch is in flight.

PartDescription
Transactions.LoadingState wrapper. Render skeleton rows inside.

Empty

Renders when there are no transactions.

PartDescription
Transactions.EmptyState wrapper. Render an empty-state message inside.

Error

Renders on fetch error.

PartDescription
Transactions.ErrorState wrapper. Compose the error UI inside.
Transactions.ErrorMessage
asChild?
Renders the error message string.
Transactions.Retry
asChild?
Button that re-runs the fetch.

Hooks

PartDescription
useTransactions()Hook returning the full context (rows, confirm, submitContext, …). The picker reads categoryOptions, matchRecords(row) and optionsLoading, and writes through stage(row, treatment); the split through openSplit, splitLines, splitSummary and saveSplit; Add bill / Add invoice through canAddRecord and addRecord. recordingIds and recordErrors track the record writes. openContext(row, kind = "chat") selects contextKind ("chat" | "note"); submitContext(row, message) uses that action. Also exposes filters (statusFilter/accountFilter + setters and options), pagination (hasMore, loadMore, loadingMore), contextPending for notes, and reviewingIds for rows being recategorised.
useTransactionsRow()Hook returning the current row inside <Rows> — including recorded (what the books hold), treatment (what the field shows and the tick records), isStaged, isSuggested, payments and matchKind.
searchCategoryOptions(options, query)The picker's search: finds a sub-category by its parent's name and keeps a parent whose sub-category matches.

Categorize or match

Every row carries a treatment: a category, a split, a match to a bill or invoice, or nothing yet. The picker offers the business's categories — every ledger except bank ledgers and Opening Balance, top-level A to Z with sub-categories under their parent — and, by direction, the open bills for money out or the open invoices for money in, each with what is left on it. A zero-amount transaction has no direction and no Match tab.

stage(row, treatment) holds a pick on a row that needs review; nothing is written until the tick. When exactly one open record of the right kind has an outstanding balance equal to the row's amount to the cent — and no other row needing review shares that amount — it is staged on load. On a confirmed row a pick writes at once and the row stays confirmed.

Recording runs in order: any payment the new treatment replaces is detached first, so a record is never paid twice; a match applies a payment for the smaller of the transaction and the record's outstanding balance; then one transactions PATCH sets the line items (for a category or split) and the status. If the transaction is larger than the record, the API books the excess as vendor or customer credit. A failed write leaves the row staged and sets recordErrors for it.

A split is drafted in the expanded state: a category and an amount per line. Save is allowed only when every line has a category and an amount above zero and the lines add up; splitSummary reports the amount left to split, or over. Removing lines down to one turns Save into staging that category alone.

Tags

When tagFields isn't forced to [], every row exposes one Tag surface — a picker grouped by field, covering every tag field the business defines. A row can carry values from more than one field at once. Edits (via setRowTags on useTransactions()) write per field through the transactions PATCH merge map: the supplied list replaces that field's values, an empty list clears it, and fields the edit doesn't mention are left untouched.

A field carrying more than one value has the transaction's amount split evenly across those values in reports — there's no per-value amount to set. A value that doesn't exist yet on a field is created automatically (subject to allowCreateTag); matching is case-insensitive, so "NYC" and "nyc" are treated as the same value.

Writes are optimistic — the row updates immediately — and roll back silently if the write fails, consistent with the rest of the SDK, which never surfaces write errors to the UI.

Plan behaviour

Some components behave differently depending on whether a bookkeeper keeps the business's books. On Done for you (the managed plan) a bookkeeper reviews and categorises the books for them. On Do it yourself (the diy and core plans) there is no bookkeeper, so the business keeps its own books — core behaves exactly like diy everywhere below. The plan is resolved from the business automatically — override it with the plan prop.

The review lifecycle differs because Done for you has a bookkeeper in the loop and Do it yourself doesn't. The component resolves the plan from the business (or the plan prop) and adjusts the labels and the status filter. The styled table chooses actions and row-click behavior by plan as shown below. Headless consumers can compose Confirm, ProvideContext, Comment, Trigger, and Details freely. If a headless consumer offers ProvideContext on managed, it runs the agent chat and leaves the status untouched. Submission routing follows the selected action:

BehaviourDone for youmanagedDo it yourselfdiy core
Status labelsThree labels: Needs Attention (awaiting the business), In Review (with the bookkeeper) and Confirmed.Two labels: For Review and Confirmed. Both bookkeeper_pending and defensive business_pending rows read For Review. DIY and core behave identically.
Status filter optionsAll statuses / Needs Attention / In Review / Confirmed.All transactions / For Review / Confirmed — there is no bookkeeper↔business hand-off, so the business_pending option is dropped.
Status columnShown — Needs Attention and In Review are a hand-off the tick can't express.Hidden in the styled table — with one pending state the tick carries it.
ActionsThe picker and ✓ the tick, plus 💬 a note for the bookkeeperThe picker and ✓ the tick; ✕ agent feedback only with feedback
Row clickOpens the note form, with the category breakdown when the row is split.Nothing; with feedback, opens the feedback form.
SubmittingPosts a journal-entry note and sets bookkeeper_pending (In Review), including previously confirmed rows.Runs the agent chat, then sets bookkeeper_pending (For Review) for the business to re-confirm.

On this page