Record Statement Balance
/extensions/roboledger/{graph_id}/operations/record-statement-balancePart of RoboLedger: Ledger & Events.
Record the ending balance of a statement (a bank, card or loan statement) for one balance-sheet account, and reconcile the account to it. Give the balance as the statement shows it, as a positive number in the account's normal direction, with the statement's ending date. The ledger's balance at that date is set beside it, counting the drafts the close will post, and the result is recorded on the account's statement reconciliation for the period the statement ends in. On an account a bank feed keeps, ledger lines that did not come from the feed and are dated on or before the statement are listed as outstanding and adjust the statement balance, since the bank had not cleared them; one dated before the statement's own cycle is listed as stale_outstanding and does not, since the bank should have cleared it by now, so the difference stays until it clears, is voided or is re-dated; a statement ending before the period's last day is carried to it by the feed's own lines (roll_forward). Attach the statement as evidence by passing the document_id of its stored file (create-document-upload, then complete-document-upload); recording it again with another document lapses a sign-off, and recording it again without one keeps the document already attached (an empty string detaches it). Writes no books. The first statement recorded for an account creates its reconciliation, which does not hold the close: turn required_for_close on with set-reconciliation-policy to make every period's close wait for a statement on that account. Recording the same account and date again replaces the earlier balance; when more than one statement ends in a period, the one with the latest date stands. Recording a balance that differs from one already signed off lapses that sign-off. A difference left after the outstanding lines is activity one side has and the other does not yet, or an error on either. Returns the reconciliation's standing for the period.
Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
Authentication
Authenticate in any one of these ways — not all of them:
- API key in the
X-API-Keyheader. - Bearer token in the
Authorizationheader.
Path parameters
| Name | Type | Description |
|---|---|---|
graph_idrequired | string | Graph Id Constraints: matches |
Header parameters
| Name | Type | Description |
|---|---|---|
Idempotency-Keyoptional | string | Idempotency-Key |
Request body
Required, application/json.
| Field | Type | Description |
|---|---|---|
element_idrequired | string | The balance-sheet account the statement is for (a chart-of-accounts element id). |
entity_idoptional | string | The entity whose books the account is in, by id. Omit for the group parent. The account must be in that entity's chart. |
as_ofrequired | string (date) | The statement's ending date. |
balancerequired | number | The ending balance as the statement shows it, as a positive number in the account's normal direction: money in a bank account, or the amount owed on a loan or a card. Negative for the opposite, such as an overdrawn bank account. Constraints: -10000000000000–10000000000000 |
document_idoptional | string | The statement itself, as a document already added with create-document. Kept on the record as evidence. Recording the same account and date again keeps the earlier record's document when this is omitted; an empty string drops it. |
noteoptional | string | Anything worth keeping with the recorded balance. |
Example request
curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/record-statement-balance" \
-H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
-H "Idempotency-Key: <Idempotency-Key>" \
-H "Content-Type: application/json" \
-d '{
"element_id": "string",
"as_of": "2026-08-31",
"balance": 18250.75
}'Responses
200 Successful Response
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
operationrequired | string | Kebab-case operation name | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
operationIdrequired | string | op_-prefixed ULID for audit and SSE correlation | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string | Operation lifecycle state One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
resultoptional | ReconciliationSummary | Command-specific result payload ReconciliationSummary fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
atrequired | string | ISO-8601 UTC timestamp | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdByoptional | string | User ID that initiated the operation | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
idempotentReplayoptional | boolean | True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions. Default: |
| Status | Meaning |
|---|---|
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Access denied |
| 404 | Resource not found |
| 409 | Idempotency-Key conflict — key reused with different body |
| 422 | Validation error |
| 429 | Rate limit exceeded |
| 500 | Internal server error |