Reopen Fiscal Period

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

Reopen a closed period for adjustment. Only the latest closed period (closed_through) can be reopened; it decrements by one and the period's entries become writable again. To reach an earlier month, reopen latest-first down to it, then re-close forward — an out-of-order reopen is refused (422) with the ordered list, because every later closed month carries statements stamped from the earlier month's numbers. Retracts the month's canonical statement FactSets (a reopened month is no longer a closed assertion; re-closing restamps them). The required reason is captured in the audit log. Use sparingly — reopen invalidates downstream artifacts that trusted the closed state (reports, shared filings).

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.
`reason`required	string	Required reason for the reopen (captured in audit log) Constraints: at least 1 character
`note`optional	string	Additional free-form note
`period`required	string	Period to reopen, in YYYY-MM. Only the latest closed period (the current `closed_through`) can be reopened, and reopening it retreats `closed_through` by one month. To reach an earlier period, reopen the later ones first, latest to earliest. Constraints: matches `^\d{4}-(0[1-9]\|1[0-2])$`

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/reopen-period" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "period": "2026-03",
  "reason": "Discovered late vendor invoice — needs to land in March."
}'

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

FiscalCalendarResponse

Command-specific result payload

FiscalCalendarResponse fields

Field Type Description

graph_idrequired string

entity_idoptional

string

The entity whose calendar this is.

fiscal_year_start_monthrequired integer

closed_throughoptional

string

Latest closed period (YYYY-MM), or null if nothing closed

close_targetoptional

string

Target period the user wants closed through (YYYY-MM)

gap_periodsoptional

integer

Number of periods between closed_through and close_target (inclusive of close_target). 0 means caught up.

Default: 0

catch_up_sequenceoptional

string[]

Ordered list of periods that a close run would process

closeable_nowoptional

boolean

Whether the next period in the catch-up sequence passes all closeable gates

Default: false

blockersoptional

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', 'unmapped_accounts', 'held_bank_lines'; on the consolidation entity, whose close is the group's, also 'entity_open', 'adjustments_unposted', 'residual_unexplained', 'consolidated_does_not_foot'

pending_obligation_countoptional

integer

Number of pending schedule_entry_due events blocking close. Non-zero only when pending_obligations is in blockers.

Default: 0

pending_obligation_sampleoptional

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.

PendingObligationDetailResponse fields

Field	Type	Description
`event_id`required	string
`schedule_id`optional	string
`schedule_name`optional	string
`period`required	string	Period in YYYY-MM format

earliest_pending_periodoptional

string

Earliest period (YYYY-MM) with a pending obligation blocking close. Null when no pending_obligations blocker is active.

sync_stale_daysoptional

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_countoptional

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_sampleoptional

PendingObligationDetailResponse[]

Sample of up to 5 stranded obligations (schedule_id, schedule_name, period, event_id) ordered by occurred_at.

PendingObligationDetailResponse fields

Field	Type	Description
`event_id`required	string
`schedule_id`optional	string
`schedule_name`optional	string
`period`required	string	Period in YYYY-MM format

reconciling_item_countoptional

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_sampleoptional

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_countoptional

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_sampleoptional

string[]

Source identifiers (or event ids) of up to 5 unposted source events, so the blocker names what is holding the close.

held_bank_line_countoptional

integer

Bank lines a sync held out of an earlier, closed month — dated there, arriving after it closed — that no close has decided on. They block the next close: reopen the month they are dated in, which gives them back to post, or close over them knowingly with allow_held_bank_lines. Listed by list-event-blocks with status='voided' and void_reason 'feed_in_closed_month'.

Default: 0

held_bank_line_sampleoptional

string[]

Up to 5 held lines, oldest first, as 'date: description amount [event id]', so the blocker names what is holding the close.

unreconciled_account_countoptional

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_sampleoptional

string[]

Name and status of up to 5 of those reconciliations, so the blocker names what is holding the close.

unmapped_account_countoptional

integer

Accounts in this entity's chart with postings through the period that its mapping does not map to a reporting concept. Their balances are in no statement, so the month cannot be stated until each is mapped: suggest-mapping, then create-mapping-association. No override lifts it.

Default: 0

unmapped_account_sampleoptional

string[]

Code and name of up to 5 of those accounts, so the blocker names what is holding the close.

group_open_entitiesoptional

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_adjustmentsoptional

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_unexplainedoptional

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_footingoptional

string[]

The group close: the consolidated balance sheet's and equity statement's validation failures for the month.

last_close_atoptional string (date-time)

initialized_atoptional string (date-time)

last_sync_atoptional

string (date-time)

Most recent QB sync timestamp (if connected)

periodsoptional

FiscalPeriodSummary[]

Fiscal period rows for this graph

FiscalPeriodSummary fields

Field	Type	Description
`name`required	string	Period name (YYYY-MM)
`start_date`required	string (date)
`end_date`required	string (date)
`status`required	string	'open' \| 'closing' \| 'closed'
`closed_at`optional	string (date-time)
`has_close_receipt`optional	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. Default: `false`

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