---
title: "Resolve Reconciling Item"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/resolve-reconciling-item"
tags: ["RoboLedger: Ledger & Events"]
---

# Resolve Reconciling Item

`POST /extensions/roboledger/{graph_id}/operations/resolve-reconciling-item`

## 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/resolve-reconciling-item`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

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: a standing entry on the item's books, other than the item, and not already counted for something else such as a catch-up or another settlement). An alignment entry authored by hand can name the items it settles in metadata.resolves_reconciling_items instead, each as {event_id, expected_drift_detected_at} carrying the preview's stamp, and each is acknowledged against it as it is recorded — an item left flagged would be caught up a second time. What an acknowledged entry booked counts toward the item's next change; voiding or reversing that entry, or a catch-up, flags the item again, and superseding it by a correction that books exactly the item's difference hands the settlement to the correction. An entry that settles a QuickBooks change has to stay local, as a catch-up does: create it with metadata.publish_to_source false, booking only the differences it settles; one that would publish or books more is refused, and so is a later patch setting it to publish. 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.

## Path parameters

- `graph_id` string, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- ResolveReconcilingItemRequest: Dispose of one reconciling item and clear its flag.
  - `event_id` string, required: Event id (evt_ prefixed) to resolve
  - `expected_drift_detected_at` string, date-time, nullable: The `drift_detected_at` of the preview this resolution was decided on. Pass it: the resolution is refused when the item has been flagged again since, with a newer payload nobody has seen, and must be previewed again.
  - `disposition` 'restate' | 'catch_up' | 'acknowledge', nullable: 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.
  - `posting_date` string, date, nullable: catch_up only: when to post the catch-up entry. Defaults to the end of the earliest open period.
  - `status` 'draft' | 'posted': 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.
  - `note` string, nullable: Why this disposition. Required for acknowledge, where it is the only record of what was done instead.
  - `reference_event_id` string, nullable: acknowledge only: the event that already handled this difference (e.g. an alignment entry authored by hand), recorded on the trail.

## Response `200`

Successful Response

- OperationEnvelopeResolveReconcilingItemResponse
  - `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` ResolveReconcilingItemResponse: The outcome of resolving one reconciling item.
    - `event_id` string, required
    - `external_id` string, nullable
    - `disposition` 'restate' | 'catch_up' | 'acknowledge', required
    - `delta` ReconcilingItemDeltaLine[]
      - `element_id` string, nullable: CoA element id; null when the account is unmapped
      - `element_external_id` string, nullable: Source-system account id, when the line carried one
      - `element_code` string, nullable: Account code
      - `element_name` string, nullable: Account name
      - `prior_net` integer, required: Net of the posted entries, debit-positive
      - `accepted_net` integer, required: Net of the new payload, debit-positive
      - `delta` integer, required: accepted_net - prior_net
    - `no_gl_effect` boolean
    - `catch_up` ReconcilingItemCatchUp: The catch-up entry a resolution posted.
      - `event_id` string, required
      - `entry_id` string, nullable
      - `transaction_id` string, nullable
      - `posting_date` string, date, required
      - `status` string, required
    - `regenerated` ReconcilingItemRegenerated: The entries a restate rebuilt.
      - `transaction_ids` string[]
      - `entry_ids` string[]
    - `reference_event_id` string, nullable
    - `note` string, nullable
    - `resolved_at` string, date-time, required
    - `resolved_by` string, required
  - `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/e661e2d5ca6a?raw)