@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:readreconciliation:writedocument:createdocument:read
API reference
Root props
| Prop | Type | Default | Description |
|---|---|---|---|
accountIdrequired | string | — | The external account being reconciled. |
month | string | null | — | The open month (YYYY-MM), or null for the list. Controlled when given. |
defaultMonth | string | 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. |
confirmationDuration | number | — | How long the approval confirmation shows before the months come back, in ms. 0 keeps it until dismissed. Defaults to 4000. |
maxFileSize | number | — | Per-file ceiling for uploads, checked before a file is sent. Defaults to 25 MB. |
account / period / comparison | AccountPeriods / PeriodDetail / ComparisonPublic | — | Override the fetched data (testing/storybook). |
confirmation | ApprovalConfirmation | — | Open on an approval's confirmation (testing/storybook). |
corrections | StatementCorrection[] | — | Corrections already accepted in the review (testing/storybook). |
document / previewUrl | DocumentPublic / string | — | Override the uploaded statement and its preview (testing/storybook). |
now | number | — | Fix "today", in milliseconds, for relative days such as "uploaded today" (testing/storybook). |
state | "loading" | "error" | "empty" | — | Force a state for testing. |
childrenrequired | ReactNode | — | Compound parts. |
Parts
Account
The account the root is for, and its bank against its books.
| Part | Description |
|---|---|
StatementReconciliation.Institution / Bank / AccountName / AccountMaskasChild?, format? | Who the statement is from. Bank is the institution, or the account's name when it has none. |
StatementReconciliation.VerdictasChild?, 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 / NoBankBalanceasChild?, format? | The balance the bank last reported. Manual accounts never have one. |
StatementReconciliation.ChecksReceived / HasChecksReceived / ChecksNotCleared / HasChecksNotClearedasChild?, format? | Checks received and not yet deposited, and checks written the bank has not cleared. |
StatementReconciliation.HasChecksClearing / NoChecksClearing / BankAfterChecksasChild?, format? | Whether any check, received or written, is still to clear, and the bank's balance once they are counted. |
StatementReconciliation.BooksBalance / BankBooksDifferenceasChild?, format? | The books' balance, and the bank (after checks) less the books. The difference sets data-zero. |
StatementReconciliation.StatementsNeededasChild?, format? | How many months are waiting on a statement. |
StatementReconciliation.UploadStatementsInput / BulkUploading / NotBulkUploading / BulkUploadErrorMessage | Upload 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.CanUploadStatements | Renders 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.
| Part | Description |
|---|---|
StatementReconciliation.Loading / Error / Success / Empty | State gates for the month list. |
StatementReconciliation.ErrorMessage / RetryasChild?, format? | Error copy and retry for the month list. |
StatementReconciliation.MonthsScreen / MonthScreen | Render their children while the list, or a month, is showing. |
StatementReconciliation.BankBooksasChild?, format? | The bank against the books as a sentence. Context only — a matching balance does not reconcile a month. |
StatementReconciliation.ReconciledThroughasChild?, format? | The last reconciled month. |
StatementReconciliation.Months | Iterates completed months, newest first. |
StatementReconciliation.MonthasChild? | 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 / MonthStatusasChild?, format? | “July 2026”; “Needs statement”, “Waiting on July”, … with data-status and data-tone. |
StatementReconciliation.MonthApprovedAt / MonthEndingBalanceasChild?, format? | Approval date and the statement ending balance. Render nothing until known. |
StatementReconciliation.MonthChangedSinceasChild?, 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.MonthIsstatus | Renders its children when the month being rendered has one of the statuses. |
StatementReconciliation.MonthMissingfield: "approvedAt" | "changedSince" | "endingBalance" | Renders its children when the month being rendered has no such figure yet — a placeholder. |
StatementReconciliation.OpenMonthasChild? | 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 / MonthNotUploading | Gates on whether the month being rendered is uploading its statement, e.g. to swap an upload icon for a spinner. |
StatementReconciliation.MonthUploadErrorMessageasChild? | Why the upload from the month being rendered's row failed. |
StatementReconciliation.MonthReconciled / MonthOpen | Gates on whether the month being rendered is reconciled. |
Month
Renders while a month is open. One step gate renders at a time.
| Part | Description |
|---|---|
StatementReconciliation.BackToMonthsasChild? | Back to the list. Asks first when corrections are pending. |
StatementReconciliation.NextMonth / OpenNextMonth / HasNextMonthasChild?, 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 / CurrentMonthStatusasChild?, 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 / RetryPeriod | State for the open month. |
StatementReconciliation.UploadStep / ProcessingStep / VerifyStep / WaitingStep / ReviewStep / RecordStep | Step gates, derived from the month's status. |
StatementReconciliation.WaitingOn / OpenWaitingOnasChild?, format? | The earlier month holding this one, and a button to open it. |
StatementReconciliation.ExpectedOpeningasChild?, format? | The previous month's ending balance, which this month should open on. |
StatementReconciliation.DocumentName / DocumentUploadedAt / OpenPreviewasChild?, format? | The uploaded statement's file name and when it was uploaded, and a link that opens it. |
StatementReconciliation.RecordValue / StatementStart / StatementEndfield, 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 / RecordMatchedCountasChild?, format? | The approval record of a reconciled month. |
Upload
| Part | Description |
|---|---|
StatementReconciliation.FileInput | A 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.DropzoneasChild? | 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.CanUpload | Renders its children when the token can upload a month's statement (document:create and reconciliation:write). |
StatementReconciliation.Uploading / NotUploading / UploadErrorMessage | Upload progress and failure. |
StatementReconciliation.UploadFailed / UploadFailureMessage | When 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.EnterManuallyasChild? | 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
| Part | Description |
|---|---|
StatementReconciliation.HasDocument / NoDocument / PreviewPdf / PreviewImage / PreviewLoading | The uploaded statement beside the extracted data. PreviewPdf frames the file, or hands its URL to a slotted renderer as src. |
StatementReconciliation.HasStatement / DraftViewing / DraftEditing | A 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 / SavingasChild? | 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.DeleteStatementasChild? | Drops the month's statement so it needs one again. The document is kept. |
StatementReconciliation.ToggleDraftRows / DraftRowsOpenasChild? | Shows or hides the transactions, which start collapsed. Sets data-state. |
StatementReconciliation.DraftClosing / DraftRowDate / DraftRowDescription / DraftRowAmountasChild?, format? | The statement's figures as values, for showing rather than editing. |
StatementReconciliation.PeriodStartField / PeriodEndField / OpeningBalanceField / ClosingBalanceFieldasChild? | Inputs bound to the statement being checked. |
StatementReconciliation.DraftRows | Iterates the statement's transactions, with DraftRowDateField, DraftRowDescriptionField, DraftRowAmountField (aria-invalid when not a number) and RemoveDraftRow. |
StatementReconciliation.AddDraftRow / DraftRowCount | Add a missing row; how many there are. |
StatementReconciliation.DraftOpening / DraftNet / CalculatedClosing / DifferenceasChild?, format? | The arithmetic, in whole cents. |
StatementReconciliation.AddsUp / DoesNotAddUp / Incomplete | Whether the opening balance plus the transactions equals the closing balance. |
StatementReconciliation.VerifyasChild? | Confirms the statement. Disabled until it adds up. Never changes the books. |
StatementReconciliation.Verifying / VerifyErrorMessage / CancelEditStatement | Save 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
| Part | Description |
|---|---|
StatementReconciliation.ComparisonLoading / ComparisonError / ComparisonErrorMessage / RetryComparison / HasComparison | State for the comparison. |
StatementReconciliation.WorkingStatusasChild?, format? | Ready or Needs review, with corrections applied. Sets data-status. |
StatementReconciliation.BalanceCheck / TransactionCheckasChild?, format? | The two checks. Set data-passed. |
StatementReconciliation.SummaryValueside, 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.SummaryDifferencefield, asChild?, format? | The statement, with checks counted when they were written, less the books, for one summary figure. Sets data-zero. |
StatementReconciliation.SummaryEffectfield, 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 / HasAdjustingChecksasChild?, format? | How many checks the bank's figures are adjusted for. |
StatementReconciliation.CheckAdjusted / NotCheckAdjustedfield | 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.CheckAdjustmentadjustment, 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 / SummaryOpenasChild? | Collapses the summary. Sets data-state. |
StatementReconciliation.HasDifferences / RowTotalasChild?, format? | Whether any row differs or was corrected — without any, every row shows — and how many rows there are. |
StatementReconciliation.HasOutstandingChecks / OutstandingChecks | Checks the bank has not cleared, which the balance check allows for. |
StatementReconciliation.ViewOptionvalue, asChild? | Switches between discrepancies (corrected rows stay visible) and every row by date. Sets data-state and aria-pressed. |
StatementReconciliation.Rows / NoRows / Row | Iterates review rows. Row sets data-type, data-resolved and data-corrected. |
StatementReconciliation.RowLabelasChild? | “Amount differs”, “Duplicate in books”, “Matched”, … |
StatementReconciliation.HasStatementSide / NoStatementSide / HasBookSide / NoBookSide / BookRemoved / Resolved / Unresolved / Matched | Row gates. |
StatementReconciliation.StatementDate / StatementDescription / StatementAmountasChild?, format? | The statement side. |
StatementReconciliation.CanEditBook / CannotEditBook | Gate 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 / BookPreviousAmountasChild?, format? | The book side, with the value before a pending correction (render nothing when unchanged). |
StatementReconciliation.ActionasChild?, 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.EffectasChild?, format? | How much accepting the suggestion moves the books' balance. Nothing for a change of date. |
StatementReconciliation.OpenCheck / ClearedCheck / CheckLabelasChild?, 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 / ShowingAllRows | Checks 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 / CanEditBook | Row gates: a pending correction touches the row; its book transaction can still be corrected by hand (useStatementReconciliation().updateBook). |
StatementReconciliation.Accept / Undo / EditRowasChild? | Accept the row's suggestion (labelled with it by default), undo its corrections, or edit the book transaction directly. |
StatementReconciliation.Editing / RowEditDateField / RowEditAmountField / ApplyRowEdit / CancelRowEdit | The direct edit. |
StatementReconciliation.CanMatch / MatchOptions / MatchOptionDate / MatchOptionDescription / MatchOptionAmount / ChooseMatch | Match a book transaction to an unmatched statement row, closest amount first. The transaction, its journal entry, categories, splits and tags are kept. |
StatementReconciliation.AcceptAll / SuggestionCountasChild? | Accept every unresolved suggestion. |
StatementReconciliation.PendingCount / HasPendingChanges / NoPendingChanges / Updating / CorrectionErrorMessage | The pending corrections, and why one was refused. |
StatementReconciliation.EditStatementasChild? | Re-open the verified statement. Asks first when corrections are pending. |
StatementReconciliation.Approve / Approving / ApproveErrorMessageasChild? | 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 / DismissConfirmationfield, asChild?, format? | The confirmation: account, month, approvedAt, endingBalance, booksBalance, matchedCount. Leaving the month ends it. |
Leaving
| Part | Description |
|---|---|
StatementReconciliation.DiscardPrompt / ConfirmDiscard / CancelDiscard | Shown when leaving would discard pending corrections. The browser also warns before a reload or closed tab. |
Hooks
| Part | Description |
|---|---|
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. |