RoboLedger: Fiscal Close

Close Fiscal Period

Lock a single fiscal period. Posts draft entries, runs the balance-sheet equation check, advances closed_through by one, auto-advances close_target if this close caught up to it, and stamps the period's canonical statement FactSets from the posted ledger (statements_stamped / stamped_statement_sets in the response; soft-skipped with statement_stamp_note when reporting isn't set up). Period must be exactly closed_through + 1 — sequence violations return 422 with structured blockers. Common blockers: sync_stale (override with allow_stale_sync=true after manual verification), period_incomplete (draft entries unbalanced), sequence_violation (out-of-order). Under a QuickBooks connection whose write_policy is shadow, the close observes instead: nothing is written to QuickBooks or posted, the drafts become shadowed expectations (entries_shadowed), and the gates that would have blocked are returned as gate_findings rather than enforced.

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.

post/extensions/roboledger/{graph_id}/operations/close-period

Request

  • Base URL: https://api.robosystems.ai (the document declares no server; this is the origin it was published from)
  • URL: https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/close-period
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

graph_idstring required

Headers

Idempotency-Keystring nullable

Request body

entity_idstring nullable

The entity whose books this acts on, by id. Omit for the group parent — the single-entity default.

notestring nullable

Free-form note attached to the close event

allow_stale_syncboolean

Override the sync-currency gate. Only use when you have manually verified that the source data for the period is complete.

allow_stranded_obligationsboolean

Override the stranded-obligation gate — close even though matured classified obligations have no drafted closing entry, knowingly omitting those adjusting entries from the period. Prefer running promote-obligations with dispatch_handlers=true (which drafts them) or voiding the obligations instead. The override is recorded in the close audit note.

allow_reconciling_itemsboolean

Override the reconciling-item gate — close even though posted events in the period are still flagged as changed in the source system, leaving those differences undecided. The next sync will still report them, and the statements stamped by this close may disagree with the source. Prefer resolve-reconciling-item on each first. The override is recorded in the close audit note.

allow_unposted_source_eventsboolean

Override the unposted-source-event gate — close even though source events dated in the period (bank-feed lines, QuickBooks transactions whose automatic posting failed) were never committed. Once the period closes they cannot post into it, so the stamped statements leave them out. Prefer classifying and committing, or voiding, each first. The override is recorded in the close audit note.

allow_unreconciled_accountsboolean

Override the reconciliation gate — close even though a reconciliation the close waits on is not reconciled for the period, or was never compared for it. The books are then closed without that check. Prefer refresh-reconciliations and clearing what it reports first. The override is recorded in the close audit note.

allow_unexplained_residualsboolean

On the consolidation entity, the group close: close even though a residual or an intercompany disagreement is left unexplained. Its difference stays in the consolidated statements. Prefer correcting the books or posting the explaining entry with its basis. The override, and each item it closed over, is recorded in the close audit note.

periodstring required

Period to close, in YYYY-MM. Must be exactly closed_through + 1 — close runs sequentially.

Example request

{
  "period": "2026-03"
}

Response

Successful Response

operationstring required

Kebab-case operation name

operationIdstring required

op_-prefixed ULID for audit and SSE correlation

status'completed' | 'pending' | 'failed' required

Operation lifecycle state

atstring required

ISO-8601 UTC timestamp

createdBystring nullable

User ID that initiated the operation

idempotentReplayboolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Changes

No recorded changes to this operation across all 1 revision of this API.