Close Fiscal Period

post/extensions/roboledger/{graph_id}/operations/close-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.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id Constraints: matches `^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?\|sec(?:_[a-zA-Z0-9]{1,20})?\|library)$`

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field	Type	Description
`entity_id`optional	string	The entity whose books this acts on, by id. Omit for the group parent — the single-entity default.
`note`optional	string	Free-form note attached to the close event
`allow_stale_sync`optional	boolean	Override the sync-currency gate. Only use when you have manually verified that the source data for the period is complete. Default: `false`
`allow_stranded_obligations`optional	boolean	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. Default: `false`
`allow_reconciling_items`optional	boolean	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. Default: `false`
`allow_unposted_source_events`optional	boolean	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. Default: `false`
`allow_unreconciled_accounts`optional	boolean	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. Default: `false`
`period`required	string	Period to close, in YYYY-MM. Must be exactly `closed_through + 1` — close runs sequentially. Constraints: matches `^\d{4}-(0[1-9]\|1[0-2])$`

Example request

curl · example 1 of 2

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/close-period" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "period": "2026-03"
}'

curl · example 2 of 2

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/close-period" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "allow_stale_sync": true,
  "note": "QB sync down; data manually verified.",
  "period": "2026-03"
}'

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: completed, pending, failed

resultoptional

ClosePeriodResponse

Command-specific result payload

ClosePeriodResponse fields

Field Type Description

fiscal_calendarrequired

FiscalCalendarResponse

Current fiscal calendar state for one entity of a graph.

FiscalCalendarResponse fields

Field	Type	Description
`graph_id`required	string
`entity_id`optional	string	The entity whose calendar this is.
`fiscal_year_start_month`required	integer
`closed_through`optional	string	Latest closed period (YYYY-MM), or null if nothing closed
`close_target`optional	string	Target period the user wants closed through (YYYY-MM)
`gap_periods`optional	integer	Number of periods between closed_through and close_target (inclusive of close_target). 0 means caught up. Default: `0`
`catch_up_sequence`optional	string[]	Ordered list of periods that a close run would process
`closeable_now`optional	boolean	Whether the next period in the catch-up sequence passes all closeable gates Default: `false`
`blockers`optional	string[]	Structured blocker codes when closeable_now is False: 'sequence_violation', 'period_incomplete', 'sync_stale', 'calendar_not_initialized', 'period_already_closed', 'pending_obligations', 'stranded_obligations', 'reconciling_items', 'unposted_source_events', 'unreconciled_accounts'
`pending_obligation_count`optional	integer	Number of pending schedule_entry_due events blocking close. Non-zero only when `pending_obligations` is in `blockers`. Default: `0`
`pending_obligation_sample`optional	PendingObligationDetailResponse[]	Sample of up to 5 pending obligations (schedule_id, schedule_name, period, event_id) ordered by occurred_at. Use `list-event-blocks` with event_type=schedule_entry_due&status=pending for the full set.
`earliest_pending_period`optional	string	Earliest period (YYYY-MM) with a pending obligation blocking close. Null when no pending_obligations blocker is active.
`sync_stale_days`optional	integer	Days the most recent sync is stale relative to the period to close. Populated only when `sync_stale` is in `blockers` and last_sync_at exists (null when there's a connection but no sync has ever run).
`stranded_obligation_count`optional	integer	Matured schedule_entry_due events already at 'classified' with no drafted closing entry for their (schedule, period) — adjusting entries a close would silently omit. Resolve by running promote-obligations with dispatch_handlers=true (which reaches them) or voiding the obligation. Default: `0`
`stranded_obligation_sample`optional	PendingObligationDetailResponse[]	Sample of up to 5 stranded obligations (schedule_id, schedule_name, period, event_id) ordered by occurred_at.
`reconciling_item_count`optional	integer	Posted events in or before this period whose source payload changed afterwards and that nobody has dispositioned — differences between the books and the source system. Resolve each with resolve-reconciling-item, or close over them knowingly with allow_reconciling_items. Default: `0`
`reconciling_item_sample`optional	string[]	Source identifiers (or event ids) of up to 5 unresolved reconciling items, so the blocker names what is holding the close.
`unposted_source_event_count`optional	integer	Source events dated in this period that were never committed: bank-feed lines still captured or classified, and QuickBooks transactions whose automatic posting failed. Commit or void each, or close over them knowingly with allow_unposted_source_events. Default: `0`
`unposted_source_event_sample`optional	string[]	Source identifiers (or event ids) of up to 5 unposted source events, so the blocker names what is holding the close.
`unreconciled_account_count`optional	integer	Reconciliations the close waits on that are not reconciled for this period, including any never compared for it. Run refresh-reconciliations and clear what it reports, release one with set-reconciliation-policy, or close over them knowingly with allow_unreconciled_accounts. Default: `0`
`unreconciled_account_sample`optional	string[]	Name and status of up to 5 of those reconciliations, so the blocker names what is holding the close.
`last_close_at`optional	string (date-time)
`initialized_at`optional	string (date-time)
`last_sync_at`optional	string (date-time)	Most recent QB sync timestamp (if connected)
`periods`optional	FiscalPeriodSummary[]	Fiscal period rows for this graph

periodrequired string

entries_postedoptional

integer

Total draft entries the close transitioned to posted, across both post paths (QB pre-publish + local bulk transition). See entries_published_to_qb / entries_posted_locally for the split.

Default: 0

entries_published_to_qboptional

integer

Drafts published to QuickBooks by the close's pre-publish step (each is promoted to posted at publish time).

Default: 0

entries_posted_locallyoptional

integer

Drafts posted by the local bulk transition (entries that don't publish to QuickBooks, e.g. native-only graphs or local-only sources).

Default: 0

target_auto_advancedoptional

boolean

Whether close_target was auto-advanced because it was reached

Default: false

rule_summaryoptional

object

Aggregated rule-eval outcome across every schedule Structure with facts in the closed period — keys: pass/fail/error/skipped. None when no schedules had facts in the period (auto-run on close).

evaluated_structure_idsoptional

string[]

ids of schedule Structures whose rules were evaluated during the close. Pairs with rule_summary.

statements_stampedoptional

boolean

Whether the close stamped the period's canonical statement FactSets (the close-time pivot). False when the tenant hasn't set up reporting yet — see statement_stamp_note.

Default: false

shadowoptional

boolean

True when the close ran in shadow (the QuickBooks connection's write_policy is 'shadow'): nothing was written to QuickBooks, nothing posted, the in-window drafts were shadowed, and the gates that would have blocked the close are in gate_findings.

Default: false

entries_shadowedoptional

integer

Drafts a shadow close took as expectations (status 'shadowed') instead of posting. Always 0 outside shadow.

Default: 0

gate_findingsoptional

string[]

Blocker codes a shadow close recorded instead of enforcing: sync_stale, pending_obligations, stranded_obligations, reconciling_items, unposted_source_events, unreconciled_accounts. Empty outside shadow.

gate_finding_countsoptional

object

Each finding's size: days stale for sync_stale, a count for the rest.

statement_stamp_noteoptional

string

Soft-skip reason when statements_stamped is false: no_coa_mapping | no_entity | no_statement_structures | no_taxonomy.

stamped_statement_setsoptional

object

structure_id -> fact_set_id for every canonical statement FactSet minted by this close (report_id NULL; replaced on reclose).

statement_rule_summaryoptional

object

Aggregated statement-rule verification outcome across the stamped structures — keys: pass/fail/error/skipped. None when no statement rules exist. Distinct from rule_summary (the schedule-rule pass).

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: false

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