RoboLedger: Fiscal Close

Backfill Plan History

Compile monthly statement history behind the close boundary — the plan's historical columns. Seeds any missing FiscalPeriod rows (baseline-closed) back to the clamped start_period, then restamps each month lacking canonical statement FactSets by running the real reopen → reclose cycle (balance validation, statement rules, and audit events per month). Chunked: at most max_periods months per call, oldest first — loop until remaining_periods comes back empty. Idempotent: already-stamped months are never touched. Months holding draft entries are skipped, never posted. start_period is clamped to the earliest month with ledger data, so deep-history tenants only backfill what actually exists.

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/backfill-plan-history

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/backfill-plan-history
  • 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.

start_periodstring nullable

YYYY-MM period to backfill from. Clamped to the earliest month with ledger data; defaults to that month when omitted. Must be on or before closed_through.

max_periodsinteger

Maximum months to restamp in this call. Each month runs a full reopen → reclose cycle; keep chunks modest and loop on remaining_periods.

allow_stale_syncboolean

Override the sync-currency gate on each reclose. Historical months predate the last sync in the normal case, so this is rarely needed.

allow_stranded_obligationsboolean

Override the stranded-obligation gate on each reclose. Only needed when a matured classified obligation without a drafted entry exists inside the backfill window and you have decided not to draft or void it first.

allow_reconciling_itemsboolean

Override the reconciling-item gate on each reclose. Only needed when an event inside the backfill window is still flagged as changed upstream and you have decided not to resolve it first.

allow_unposted_source_eventsboolean

Override the unposted-source-event gate on each reclose. Only needed when a source event inside the backfill window was never committed and you have decided not to commit or void it first.

allow_unreconciled_accountsboolean

Override the reconciliation gate on each reclose. Needed when a month inside the backfill window has a reconciliation the close waits on that was never compared for it, which is every month closed before the reconciliation existed.

allow_unexplained_residualsboolean

Override the group close's residual gate on each reclose of the consolidation entity's months.

restampboolean

Also re-derive months that ALREADY have canonical statement sets (default: skip them). Use after an engine improvement changes what a stamp produces — each month reruns the full reopen → reclose cycle and replaces its sets. A restamp run is not self-resuming (every month in range stays a candidate); advance start_period between chunks.

notestring nullable

Free-form note attached to each close audit event

Example request

{}

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.