Change Calendar Start

post/extensions/roboledger/{graph_id}/operations/change-calendar-start

Move where an entity's fiscal calendar starts, allowed only before its first close. Earlier adds open months back to first_open_period, for history that predates the start; later removes empty leading months. Refused once any month has closed (409), and when moving later would drop months that hold entries or unposted source lines (409).

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

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.
`first_open_period`required	string	YYYY-MM: the new first month of the calendar, open. Constraints: matches `^\d{4}-(0[1-9]\|1[0-2])$`
`note`optional	string	Free-form note attached to the audit event

entity_idoptional

string

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

first_open_periodrequired

string

YYYY-MM: the new first month of the calendar, open.

Constraints: matches ^\d{4}-(0[1-9]|1[0-2])$

noteoptional

string

Free-form note attached to the audit event

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/change-calendar-start" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "first_open_period": "string"
}'

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

ChangeCalendarStartResponse

Command-specific result payload

ChangeCalendarStartResponse 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

periods_createdoptional

integer

Open FiscalPeriod rows added by moving the start earlier

Default: 0

periods_removedoptional

integer

Empty FiscalPeriod rows removed by moving the start later

Default: 0

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