@get-asset/sdk

Statement Reconciliation

Headless compound for reconciling one account by statement verification, for a business whose reconciliation_method is statement_verified. It lists the account’s completed months and walks each one through uploading (or entering) the statement, verifying that it adds up, and reviewing it against the books. Asset suggests a correction for every discrepancy; the corrections are held here, re-checked by the API after every change, and only applied to the books when the month is approved. Months are reconciled in order. AccountsList mounts it for the open account through AccountsList.StatementReconciliationRoot.

Anatomy

Import the primitive and compose the parts you need.

<StatementReconciliation.Root accountId={accountId}>
<StatementReconciliation.MonthsScreen>
<StatementReconciliation.AccountName />
<StatementReconciliation.Verdict formatAmount={money} />
<StatementReconciliation.BankBalance />
<StatementReconciliation.BooksBalance />
<StatementReconciliation.BankBooksDifference />
<StatementReconciliation.Months>
<StatementReconciliation.Month>
<StatementReconciliation.MonthName />
<StatementReconciliation.MonthStatus />
<StatementReconciliation.MonthApprovedAt />
<StatementReconciliation.MonthChangedSince />
<StatementReconciliation.MonthEndingBalance />
<StatementReconciliation.MonthIs status={["needs_review", "ready"]}>
<StatementReconciliation.OpenMonth>Reconcile</StatementReconciliation.OpenMonth>
</StatementReconciliation.MonthIs>
</StatementReconciliation.Month>
</StatementReconciliation.Months>
<StatementReconciliation.StatementsNeeded />
<StatementReconciliation.UploadStatementsInput />
</StatementReconciliation.MonthsScreen>
<StatementReconciliation.MonthScreen>
<StatementReconciliation.BackToMonths />
<StatementReconciliation.CurrentMonth />
<StatementReconciliation.CurrentMonthStatus />
<StatementReconciliation.UploadStep>
<StatementReconciliation.Dropzone />
<StatementReconciliation.EnterManually />
</StatementReconciliation.UploadStep>
<StatementReconciliation.VerifyStep>
<StatementReconciliation.PreviewPdf />
<StatementReconciliation.DraftViewing>
<StatementReconciliation.DraftOpening />
<StatementReconciliation.StartDraftEdit>Edit</StatementReconciliation.StartDraftEdit>
</StatementReconciliation.DraftViewing>
<StatementReconciliation.DraftEditing>
<StatementReconciliation.OpeningBalanceField />
<StatementReconciliation.SaveDraft>Save</StatementReconciliation.SaveDraft>
</StatementReconciliation.DraftEditing>
<StatementReconciliation.ToggleDraftRows />
<StatementReconciliation.DraftRows>…</StatementReconciliation.DraftRows>
<StatementReconciliation.Verify>Continue</StatementReconciliation.Verify>
</StatementReconciliation.VerifyStep>
<StatementReconciliation.ReviewStep>
<StatementReconciliation.BalanceCheck />
<StatementReconciliation.TransactionCheck />
<StatementReconciliation.SummaryValue side="statement" field="ending_balance" />
<StatementReconciliation.Rows>
<StatementReconciliation.Row>
<StatementReconciliation.StatementAmount />
<StatementReconciliation.BookPreviousAmount />
<StatementReconciliation.BookAmount />
<StatementReconciliation.Effect />
<StatementReconciliation.Action />
<StatementReconciliation.Accept />
<StatementReconciliation.Undo />
</StatementReconciliation.Row>
</StatementReconciliation.Rows>
<StatementReconciliation.AcceptAll />
<StatementReconciliation.Approve>Mark as reconciled</StatementReconciliation.Approve>
</StatementReconciliation.ReviewStep>
</StatementReconciliation.MonthScreen>
<StatementReconciliation.DiscardPrompt>…</StatementReconciliation.DiscardPrompt>
</StatementReconciliation.Root>

Required scopes

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

  • reconciliation:read
  • reconciliation:write
  • document:create
  • document:read

API reference

Root props

PropTypeDefaultDescription
accountIdrequiredstring—The external account being reconciled.
monthstring | null—The open month (YYYY-MM), or null for the list. Controlled when given.
defaultMonthstring | null—The month to open on when uncontrolled.
onMonthChange(month) => void—Notified when a month is opened or closed.
onApproved(confirmation) => void—Notified after a month is approved.
confirmationDurationnumber—How long the approval confirmation shows before the months come back, in ms. 0 keeps it until dismissed. Defaults to 4000.
maxFileSizenumber—Per-file ceiling for uploads, checked before a file is sent. Defaults to 25 MB.
account / period / comparisonAccountPeriods / PeriodDetail / ComparisonPublic—Override the fetched data (testing/storybook).
confirmationApprovalConfirmation—Open on an approval's confirmation (testing/storybook).
correctionsStatementCorrection[]—Corrections already accepted in the review (testing/storybook).
document / previewUrlDocumentPublic / string—Override the uploaded statement and its preview (testing/storybook).
nownumber—Fix "today", in milliseconds, for relative days such as "uploaded today" (testing/storybook).
state"loading" | "error" | "empty"—Force a state for testing.
childrenrequiredReactNode—Compound parts.

Parts

Account

The account the root is for, and its bank against its books.

PartDescription
StatementReconciliation.Institution / Bank / AccountName / AccountMask
asChild?, format?
Who the statement is from. Bank is the institution, or the account's name when it has none.
StatementReconciliation.Verdict
asChild?, format?, formatAmount?
The bank against the books in two sentences: “Your books are $250.00 below the bank.” and where to look, “July needs review to find it.” format receives { headline, detail }.
StatementReconciliation.BankBalance / HasBankBalance / NoBankBalance
asChild?, format?
The balance the bank last reported. Manual accounts never have one.
StatementReconciliation.ChecksReceived / HasChecksReceived / ChecksNotCleared / HasChecksNotCleared
asChild?, format?
Checks received and not yet deposited, and checks written the bank has not cleared.
StatementReconciliation.HasChecksClearing / NoChecksClearing / BankAfterChecks
asChild?, format?
Whether any check, received or written, is still to clear, and the bank's balance once they are counted.
StatementReconciliation.BooksBalance / BankBooksDifference
asChild?, format?
The books' balance, and the bank (after checks) less the books. The difference sets data-zero.
StatementReconciliation.StatementsNeeded
asChild?, format?
How many months are waiting on a statement.
StatementReconciliation.UploadStatementsInput / BulkUploading / NotBulkUploading / BulkUploadErrorMessageUpload several statements at once. Each lands on the month it covers once it has been read; the months are polled meanwhile. Files go up twelve to a request, and one over maxFileSize is left out and named by the error message. The input renders nothing when the token lacks document:create.
StatementReconciliation.CanUploadStatementsRenders its children when the token can upload statements for the account, e.g. around the button that opens the picker.

Months

Renders while the month list is showing.

PartDescription
StatementReconciliation.Loading / Error / Success / EmptyState gates for the month list.
StatementReconciliation.ErrorMessage / Retry
asChild?, format?
Error copy and retry for the month list.
StatementReconciliation.MonthsScreen / MonthScreenRender their children while the list, or a month, is showing.
StatementReconciliation.BankBooks
asChild?, format?
The bank against the books as a sentence. Context only — a matching balance does not reconcile a month.
StatementReconciliation.ReconciledThrough
asChild?, format?
The last reconciled month.
StatementReconciliation.MonthsIterates completed months, newest first.
StatementReconciliation.Month
asChild?
The month row. Sets data-status and data-tone (action | neutral | done). A reconciled row opens its record, and a row waiting on its statement opens the statement step, when clicked; its own buttons and inputs keep their clicks.
StatementReconciliation.MonthName / MonthStatus
asChild?, format?
“July 2026”; “Needs statement”, “Waiting on July”, … with data-status and data-tone.
StatementReconciliation.MonthApprovedAt / MonthEndingBalance
asChild?, format?
Approval date and the statement ending balance. Render nothing until known.
StatementReconciliation.MonthChangedSince
asChild?, format?
For a reconciled month, how many of its book transactions were added, removed or changed in amount or date since it was approved.
StatementReconciliation.MonthIs
status
Renders its children when the month being rendered has one of the statuses.
StatementReconciliation.MonthMissing
field: "approvedAt" | "changedSince" | "endingBalance"
Renders its children when the month being rendered has no such figure yet — a placeholder.
StatementReconciliation.OpenMonth
asChild?
Opens the month being rendered.
StatementReconciliation.MonthFileInput
...InputHTMLAttributes
A file input that uploads the chosen statement onto the month being rendered, without opening it. The row then reads Processing while the statement is read. Several months can upload at once, and a month doesn't open while its statement is on its way up. Renders nothing when the token can't upload.
StatementReconciliation.MonthUploading / MonthNotUploadingGates on whether the month being rendered is uploading its statement, e.g. to swap an upload icon for a spinner.
StatementReconciliation.MonthUploadErrorMessage
asChild?
Why the upload from the month being rendered's row failed.
StatementReconciliation.MonthReconciled / MonthOpenGates on whether the month being rendered is reconciled.

Month

Renders while a month is open. One step gate renders at a time.

PartDescription
StatementReconciliation.BackToMonths
asChild?
Back to the list. Asks first when corrections are pending.
StatementReconciliation.NextMonth / OpenNextMonth / HasNextMonth
asChild?, format?
The account's next month to work on, other than the open one, and a button to open it, e.g. Reconcile August under a reconciled month. While there is one, the confirmation stays until it is chosen.
StatementReconciliation.CurrentMonth / CurrentMonthStatus
asChild?, format?
The open month and its status. The status is the month's own: corrections accepted in a review change it only once the month is approved.
StatementReconciliation.PeriodLoading / PeriodError / PeriodErrorMessage / RetryPeriodState for the open month.
StatementReconciliation.UploadStep / ProcessingStep / VerifyStep / WaitingStep / ReviewStep / RecordStepStep gates, derived from the month's status.
StatementReconciliation.WaitingOn / OpenWaitingOn
asChild?, format?
The earlier month holding this one, and a button to open it.
StatementReconciliation.ExpectedOpening
asChild?, format?
The previous month's ending balance, which this month should open on.
StatementReconciliation.DocumentName / DocumentUploadedAt / OpenPreview
asChild?, format?
The uploaded statement's file name and when it was uploaded, and a link that opens it.
StatementReconciliation.RecordValue / StatementStart / StatementEnd
field, asChild?, format?
approvedAt, endingBalance, booksBalance or matchedCount, and the period the statement covers — from the confirmation just after approval, and from the record after that.
StatementReconciliation.RecordApprovedAt / RecordApprovedBy / RecordEndingBalance / RecordMatchedCount
asChild?, format?
The approval record of a reconciled month.

Upload

PartDescription
StatementReconciliation.FileInputA file input that uploads the chosen statement for the open month. A file over maxFileSize is refused before it is sent. Renders nothing when the token can't upload.
StatementReconciliation.Dropzone
asChild?
Uploads the first dropped file. Sets data-dragging. A drop while a statement is uploading is ignored. Renders nothing when the token can't upload.
StatementReconciliation.CanUploadRenders its children when the token can upload a month's statement (document:create and reconciliation:write).
StatementReconciliation.Uploading / NotUploading / UploadErrorMessageUpload progress and failure.
StatementReconciliation.UploadFailed / UploadFailureMessageWhen the last statement could not be read: "The file uploaded today couldn't be read", with the reason, when there is one, as its title.
StatementReconciliation.EnterManually
asChild?
Enter the statement by hand instead. Renders nothing when the token lacks reconciliation:write, as do the other controls that save, delete, correct or approve.

Verify

PartDescription
StatementReconciliation.HasDocument / NoDocument / PreviewPdf / PreviewImage / PreviewLoadingThe uploaded statement beside the extracted data. PreviewPdf frames the file, or hands its URL to a slotted renderer as src.
StatementReconciliation.HasStatement / DraftViewing / DraftEditingA statement read off a file is shown first, its lines in date order, to be checked against it; one typed by hand opens for editing, on the balance the month should open on.
StatementReconciliation.StartDraftEdit / CancelDraftEdit / SaveDraft / Saving
asChild?
Open the statement for editing, drop the edits, or save them without confirming the statement. SaveDraft is disabled while a balance, date or amount is blank or unreadable; the statement need not add up to be saved.
StatementReconciliation.DeleteStatement
asChild?
Drops the month's statement so it needs one again. The document is kept.
StatementReconciliation.ToggleDraftRows / DraftRowsOpen
asChild?
Shows or hides the transactions, which start collapsed. Sets data-state.
StatementReconciliation.DraftClosing / DraftRowDate / DraftRowDescription / DraftRowAmount
asChild?, format?
The statement's figures as values, for showing rather than editing.
StatementReconciliation.PeriodStartField / PeriodEndField / OpeningBalanceField / ClosingBalanceField
asChild?
Inputs bound to the statement being checked.
StatementReconciliation.DraftRowsIterates the statement's transactions, with DraftRowDateField, DraftRowDescriptionField, DraftRowAmountField (aria-invalid when not a number) and RemoveDraftRow.
StatementReconciliation.AddDraftRow / DraftRowCountAdd a missing row; how many there are.
StatementReconciliation.DraftOpening / DraftNet / CalculatedClosing / Difference
asChild?, format?
The arithmetic, in whole cents.
StatementReconciliation.AddsUp / DoesNotAddUp / IncompleteWhether the opening balance plus the transactions equals the closing balance.
StatementReconciliation.Verify
asChild?
Confirms the statement. Disabled until it adds up. Never changes the books.
StatementReconciliation.Verifying / VerifyErrorMessage / CancelEditStatementSave state, and leaving a statement re-opened from the review unchanged. CancelEditStatement renders nothing for a statement being typed by hand, which has no review to go back to.

Review

PartDescription
StatementReconciliation.ComparisonLoading / ComparisonError / ComparisonErrorMessage / RetryComparison / HasComparisonState for the comparison.
StatementReconciliation.WorkingStatus
asChild?, format?
Ready or Needs review, with corrections applied. Sets data-status.
StatementReconciliation.BalanceCheck / TransactionCheck
asChild?, format?
The two checks. Set data-passed.
StatementReconciliation.SummaryValue
side, field, asChild?, format?
Beginning balance, money in, money out or ending balance: side is statement (the bank's figures), statement_after_checks (counting checks when written, as the books do) or books.
StatementReconciliation.SummaryDifference
field, asChild?, format?
The statement, with checks counted when they were written, less the books, for one summary figure. Sets data-zero.
StatementReconciliation.SummaryEffect
field, asChild?, format?
One figure's difference signed by its effect on the ending balance, so the beginning, cash in and cash out differences add down to the ending one. Sets data-zero.
StatementReconciliation.AdjustingCheckCount / HasAdjustingChecks
asChild?, format?
How many checks the bank's figures are adjusted for.
StatementReconciliation.CheckAdjusted / NotCheckAdjusted
field
Whether checks move a summary figure. The books count a check when it is written and the bank when it pays it, so a figure checks move is shown as the bank's, the checks, and the figure after them.
StatementReconciliation.CheckAdjustment
adjustment, asChild?, format?
open_at_start, written_not_cleared, cleared_from_earlier or open_at_end: the amount, signed as it moves the statement figure, and how many checks. Renders nothing when no check applies.
StatementReconciliation.ToggleSummary / SummaryOpen
asChild?
Collapses the summary. Sets data-state.
StatementReconciliation.HasDifferences / RowTotal
asChild?, format?
Whether any row differs or was corrected — without any, every row shows — and how many rows there are.
StatementReconciliation.HasOutstandingChecks / OutstandingChecksChecks the bank has not cleared, which the balance check allows for.
StatementReconciliation.ViewOption
value, asChild?
Switches between discrepancies (corrected rows stay visible) and every row by date. Sets data-state and aria-pressed.
StatementReconciliation.Rows / NoRows / RowIterates review rows. Row sets data-type, data-resolved and data-corrected.
StatementReconciliation.RowLabel
asChild?
“Amount differs”, “Duplicate in books”, “Matched”, …
StatementReconciliation.HasStatementSide / NoStatementSide / HasBookSide / NoBookSide / BookRemoved / Resolved / Unresolved / MatchedRow gates.
StatementReconciliation.StatementDate / StatementDescription / StatementAmount
asChild?, format?
The statement side.
StatementReconciliation.CanEditBook / CannotEditBookGate on whether the row's book line can be corrected here: an open row whose book line is not a check. Show a date picker under one and the plain date under the other.
StatementReconciliation.BookDate / BookDescription / BookAmount / BookPreviousDate / BookPreviousAmount
asChild?, format?
The book side, with the value before a pending correction (render nothing when unchanged).
StatementReconciliation.Action
asChild?, format?
The row's suggestion while open, or the correction that resolved it: { kind, amount?, date?, check? }. rowActionLabel words it — “Change amount to $9,860.50”, “Move to Aug 1”, “Matched to statement”, “Match to check 1043”, “Change to $1,257.00”. A bank line naming an open check by number is matched to it rather than added, whatever the amount; a check the bank then paid for another amount is a check_amount_mismatch row, whose suggestion corrects a check written this month to what the bank paid. Sets data-kind.
StatementReconciliation.Effect
asChild?, format?
How much accepting the suggestion moves the books' balance. Nothing for a change of date.
StatementReconciliation.OpenCheck / ClearedCheck / CheckLabel
asChild?, format?
A row that is a check: still not paid, or paid on this statement — matched by its number, or by its amount when the line says it is a check. CheckLabel words it, “Check 10493 · not cleared”; format receives { number, payee, issuedOn, cleared, carried }. Approving the month marks the checks the statement paid as cleared.
StatementReconciliation.CarriedChecks / HasCarriedChecks / ShowingAllRowsChecks written before the period that the bank still has not paid, listed apart from the period's own rows; ShowingAllRows renders while every row is showing.
StatementReconciliation.Corrected / CanEditBookRow gates: a pending correction touches the row; its book transaction can still be corrected by hand (useStatementReconciliation().updateBook).
StatementReconciliation.Accept / Undo / EditRow
asChild?
Accept the row's suggestion (labelled with it by default), undo its corrections, or edit the book transaction directly.
StatementReconciliation.Editing / RowEditDateField / RowEditAmountField / ApplyRowEdit / CancelRowEditThe direct edit.
StatementReconciliation.CanMatch / MatchOptions / MatchOptionDate / MatchOptionDescription / MatchOptionAmount / ChooseMatchMatch a book transaction to an unmatched statement row, closest amount first. The transaction, its journal entry, categories, splits and tags are kept.
StatementReconciliation.AcceptAll / SuggestionCount
asChild?
Accept every unresolved suggestion.
StatementReconciliation.PendingCount / HasPendingChanges / NoPendingChanges / Updating / CorrectionErrorMessageThe pending corrections, and why one was refused.
StatementReconciliation.EditStatement
asChild?
Re-open the verified statement. Asks first when corrections are pending.
StatementReconciliation.Approve / Approving / ApproveErrorMessage
asChild?
Applies the corrections and approves the month. Disabled until both checks pass. If the books changed since the review loaded, the API refuses and the review re-runs.
StatementReconciliation.Approved / ConfirmationValue / DismissConfirmation
field, asChild?, format?
The confirmation: account, month, approvedAt, endingBalance, booksBalance, matchedCount. Leaving the month ends it.

Leaving

PartDescription
StatementReconciliation.DiscardPrompt / ConfirmDiscard / CancelDiscardShown when leaving would discard pending corrections. The browser also warns before a reload or closed tab.

Hooks

PartDescription
useStatementReconciliation()The full context: months, period, step, draft, totals, comparison, corrections, correct(c), updateBook(id, { date, amount }), undo(row), acceptAll(), approve(), …
useStatementReconciliationMonth() / Row() / DraftRow() / MatchOption()The item being iterated.