Resolving and evidencing a discrepancy from the reconciliation

The monthly reconciliation reports twelve discrepancies, three of them critical: an order that exists in the channel but not in your system, and two stock levels differing by one piece. Simply adopting the channel figure now removes the discrepancy and keeps the cause.

The contract therefore makes resolution a decision of its own per discrepancy: adopt the source, adopt the target or explicitly accept the difference — each with a reason and an attributed actor. Resolution is evidenced only when a new reconciliation finds no critical discrepancy any more.

What this case requires

• A completed reconciliation. The decision refers to a discrepancy with a discrepancyId inside a reconciliation.
• A person with authority. Adopting source or target changes data; not everyone should be allowed to.
• Reasons someone else understands. reasonCode is your own code; an in-house catalogue keeps it readable.
• The will to find the cause. Ledger and event stream can be read; the contract describes no link between their entries and a discrepancy.

The sequence

The table names the responsible call per stage and what exists afterwards. The reasoning for why a stage cannot be skipped follows below it.

Why each stage is needed

1. Read the reconciliation. GET /commerce/v1/reconciliations/{reconciliationId} returns counts with matched, discrepant and criticalRemaining, integrity with both sides’ checksums and discrepancies with kind, resourceId, severity and state. Critical ones first: severity distinguishes warning and critical; the contract does not describe what effect a critical discrepancy has.
2. Decide. POST /commerce/v1/reconciliations/{reconciliationId}/discrepancies/{discrepancyId}/resolution takes decision with apply_source, apply_target or accept_difference, plus reasonCode and expectedRevision. The response names resultingState and decisionActorReference — the decision is attributed to an actor.
3. Trace the stock. GET /commerce/v1/inventory/ledger shows per entry entryType, quantityDelta and balance. Each entry carries stockItemId; the contract describes no link to a discrepancy.
4. Re-read the events. GET /commerce/v1/events returns events with streamId, sequence and correlationId. They also carry type, resourceId and occurredAt; the contract does not describe what a gap in sequence means.
5. Reconcile again. POST /commerce/v1/reconciliations checks the same period with new checkpoints. Resolution is evidenced when criticalRemaining stands at zero; anything else is an assertion.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: abweichung-2026-08-0003' \
  -d '{"decision":"apply_source","reasonCode":"<reasonCode>","note":"Buchung im Kanal war korrekt, Zustellung fehlte.","expectedRevision":"<revision>"}' \
  'https://commerce-preview.invalid/commerce/v1/reconciliations/<reconciliationId>/discrepancies/<discrepancyId>/resolution'

What you end up with

In the end every discrepancy is decided, reasoned and attributed to an actor, the ledger and the event stream have been read, and a new reconciliation evidences that nothing critical is open.

Where to find this in the documentation

The binding field lists, error codes and sample responses live in this surface’s OpenAPI contract at docs.tapinomahub.com (tapinoma-commerce). All use cases arranged by surface and role: overview of the use cases.