Resolve Reconciling Item

post/extensions/roboledger/{graph_id}/operations/resolve-reconciling-item

Dispose of one reconciling item and clear its flag. Three treatments: 'restate' regenerates the event's entries from the accepted payload in place (prior months' figures change — right when nothing external binds them); 'catch_up' leaves history alone and posts the difference as an alignment entry in an open period, local-only so it cannot travel back to the source system and apply the change twice; 'acknowledge' records that the difference was handled elsewhere and clears the flag without touching the ledger (a note is required, and reference_event_id should name the entry that handled it). Omit disposition to take the default from preview-reconciling-item. Clearing the flag means the item stays cleared: the event's payload is set to the accepted one, so the next sync no longer sees a difference.

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

Header parameters

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

Request body

Required, application/json.

Field	Type	Description
`event_id`required	string	Event id (evt_ prefixed) to resolve
`disposition`optional	string	How to dispose of the difference. Omit to take the default the preview reports: restate when every period the event touches is open, catch_up when any is closed. One of: `restate`, `catch_up`, `acknowledge`
`posting_date`optional	string (date)	catch_up only: when to post the catch-up entry. Defaults to the end of the earliest open period.
`status`optional	string	catch_up only: whether the catch-up entry is drafted for review at close (default) or posted immediately. A draft appears in list-period-drafts and posts locally when the period closes. One of: `draft`, `posted` Default: `draft`
`note`optional	string	Why this disposition. Required for acknowledge, where it is the only record of what was done instead.
`reference_event_id`optional	string	acknowledge only: the event that already handled this difference (e.g. an alignment entry authored by hand), recorded on the trail.

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/resolve-reconciling-item" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "event_id": "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

ResolveReconcilingItemResponse

Command-specific result payload

ResolveReconcilingItemResponse fields

Field Type Description

event_idrequired string

external_idoptional string

dispositionrequired

string

One of: restate, catch_up, acknowledge

deltaoptional

ReconcilingItemDeltaLine[]

One account's net change between the posted entries and the new payload. Amounts are signed minor units in debit-positive convention: a positive figure is a net debit, a negative one a net credit. ``delta`` is what a catch-up entry would post to bring the books level.

ReconcilingItemDeltaLine fields

Field	Type	Description
`element_id`optional	string	CoA element id; null when the account is unmapped
`element_external_id`optional	string	Source-system account id, when the line carried one
`element_code`optional	string	Account code
`element_name`optional	string	Account name
`prior_net`required	integer	Net of the posted entries, debit-positive
`accepted_net`required	integer	Net of the new payload, debit-positive
`delta`required	integer	accepted_net - prior_net

no_gl_effectoptional

boolean

Default: false

catch_upoptional

ReconcilingItemCatchUp

Present when the disposition posted a catch-up entry

ReconcilingItemCatchUp fields

Field	Type	Description
`event_id`required	string
`entry_id`optional	string
`transaction_id`optional	string
`posting_date`required	string (date)
`status`required	string

regeneratedoptional

ReconcilingItemRegenerated

Present when the disposition rebuilt the event's entries

ReconcilingItemRegenerated fields

Field	Type	Description
`transaction_ids`optional	string[]
`entry_ids`optional	string[]

reference_event_idoptional string

noteoptional string

resolved_atrequired string (date-time)

resolved_byrequired string

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation (null for legacy callers)

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