---
title: "Close Fiscal Period"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/close-period"
tags: ["RoboLedger: Fiscal Close"]
---

# Close Fiscal Period

`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

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.

## Path parameters

- `graph_id` string, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- ClosePeriodOperation: Close a single fiscal period. Carries the YYYY-MM `period` in the request body alongside the close-time options inherited from :class:`ClosePeriodRequest`.
  - `entity_id` string, nullable: The entity whose books this acts on, by id. Omit for the group parent — the single-entity default.
  - `note` string, nullable: Free-form note attached to the close event
  - `allow_stale_sync` boolean: Override the sync-currency gate. Only use when you have manually verified that the source data for the period is complete.
  - `allow_stranded_obligations` 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.
  - `allow_reconciling_items` 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.
  - `allow_unposted_source_events` 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.
  - `allow_unreconciled_accounts` 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.
  - `allow_unexplained_residuals` boolean: 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.
  - `period` string, required: Period to close, in YYYY-MM. Must be exactly `closed_through + 1` — close runs sequentially.

## Response `200`

Successful Response

- OperationEnvelopeClosePeriodResponse
  - `operation` string, required: Kebab-case operation name
  - `operationId` string, required: op_-prefixed ULID for audit and SSE correlation
  - `status` 'completed' | 'pending' | 'failed', required: Operation lifecycle state
  - `result` ClosePeriodResponse: Response from a single-period close operation.
    - `fiscal_calendar` FiscalCalendarResponse, required: Current fiscal calendar state for one entity of a graph.
      - `graph_id` string, required
      - `entity_id` string, nullable: The entity whose calendar this is.
      - `fiscal_year_start_month` integer, required
      - `closed_through` string, nullable: Latest closed period (YYYY-MM), or null if nothing closed
      - `close_target` string, nullable: Target period the user wants closed through (YYYY-MM)
      - `gap_periods` integer: Number of periods between closed_through and close_target (inclusive of close_target). 0 means caught up.
      - `catch_up_sequence` string[]: Ordered list of periods that a close run would process
      - `closeable_now` boolean: Whether the next period in the catch-up sequence passes all closeable gates
      - `blockers` 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'; on the consolidation entity, whose close is the group's, also 'entity_open', 'adjustments_unposted', 'residual_unexplained', 'consolidated_does_not_foot'
      - `pending_obligation_count` integer: Number of pending schedule_entry_due events blocking close. Non-zero only when `pending_obligations` is in `blockers`.
      - `pending_obligation_sample` 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.
        - `event_id` string, required
        - `schedule_id` string, nullable
        - `schedule_name` string, nullable
        - `period` string, required: Period in YYYY-MM format
      - `earliest_pending_period` string, nullable: Earliest period (YYYY-MM) with a pending obligation blocking close. Null when no pending_obligations blocker is active.
      - `sync_stale_days` integer, nullable: 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` 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.
      - `stranded_obligation_sample` PendingObligationDetailResponse[]: Sample of up to 5 stranded obligations (schedule_id, schedule_name, period, event_id) ordered by occurred_at.
        - `event_id` string, required
        - `schedule_id` string, nullable
        - `schedule_name` string, nullable
        - `period` string, required: Period in YYYY-MM format
      - `reconciling_item_count` 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.
      - `reconciling_item_sample` 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` 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.
      - `unposted_source_event_sample` 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` 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.
      - `unreconciled_account_sample` string[]: Name and status of up to 5 of those reconciliations, so the blocker names what is holding the close.
      - `group_open_entities` string[]: The group close: the entities the month consolidates, the parent and its equity-method members included, that have not closed it. Close each first.
      - `group_pending_adjustments` string[]: The group close: the consolidating entries the consolidation entity neither holds nor has drafted, by kind and member, or what the engine left out and why. Run propose-consolidation-entries.
      - `group_unexplained` string[]: The group close: residuals and intercompany disagreements left unexplained. Correct the books or post the explaining entry, or close over them knowingly with allow_unexplained_residuals.
      - `group_not_footing` string[]: The group close: the consolidated balance sheet's and equity statement's validation failures for the month.
      - `last_close_at` string, date-time, nullable
      - `initialized_at` string, date-time, nullable
      - `last_sync_at` string, date-time, nullable: Most recent QB sync timestamp (if connected)
      - `periods` FiscalPeriodSummary[]: Fiscal period rows for this graph
        - `name` string, required: Period name (YYYY-MM)
        - `start_date` string, date, required
        - `end_date` string, date, required
        - `status` string, required: 'open' | 'closing' | 'closed'
        - `closed_at` string, date-time, nullable
        - `has_close_receipt` boolean: Whether this period carries a close receipt. A flag rather than the receipt itself keeps the calendar listing compact; fetch the receipt from `get-period-close-status` for the period. False on open periods and on periods closed before receipts shipped.
    - `period` string, required
    - `entries_posted` 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.
    - `entries_published_to_qb` integer: Drafts published to QuickBooks by the close's pre-publish step (each is promoted to posted at publish time).
    - `entries_posted_locally` integer: Drafts posted by the local bulk transition (entries that don't publish to QuickBooks, e.g. native-only graphs or local-only sources).
    - `target_auto_advanced` boolean: Whether close_target was auto-advanced because it was reached
    - `rule_summary` object, nullable: 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_ids` string[]: ids of schedule Structures whose rules were evaluated during the close. Pairs with rule_summary.
    - `statements_stamped` 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.
    - `shadow` 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.
    - `entries_shadowed` integer: Drafts a shadow close took as expectations (status 'shadowed') instead of posting. Always 0 outside shadow.
    - `gate_findings` 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_counts` object: Each finding's size: days stale for sync_stale, a count for the rest.
    - `statement_stamp_note` string, nullable: Soft-skip reason when statements_stamped is false: no_coa_mapping | no_entity | no_statement_structures | no_taxonomy.
    - `stamped_statement_sets` object: structure_id -> fact_set_id for every canonical statement FactSet minted by this close (report_id NULL; replaced on reclose).
    - `statement_rule_summary` object, nullable: 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).
  - `at` string, required: ISO-8601 UTC timestamp
  - `createdBy` string, nullable: User ID that initiated the operation
  - `idempotentReplay` boolean: True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

## Other responses

- `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

---

[API](https://skmtc.dev/robosystems/apis/robosystems-api.md) · [All operations](https://skmtc.dev/robosystems/apis/robosystems-api/llms.txt) · [OpenAPI document](https://skmtc.dev/robosystems/apis/robosystems-api/revisions/28ffd375c457?raw)