Inspecting a returned part and deciding what happens to it

A control unit comes back: the buyer writes that it does not fit. On unpacking, a damaged connector turns up. Whether the part may go back on sale, has to be repaired or is recycled is decided not by the buyer’s return reason but by inspection at goods-in.

The contract therefore separates three statements that everyday practice likes to put in one field: why the buyer is returning, what inspection finds and what happens to the part. Accepted does not mean sellable again — the disposition is decided in a call of its own.

What this case requires

• An order with lines. The return references salesOrderId and the returned lines.
• Inspection by someone who knows the part. The disposition decision is technical, not administrative.
• Fixed reasons for findings and disposition. reasonCode is your own lower-case code here; an in-house catalogue keeps it consistent.
• An expected revision. Inspection and disposition require expectedRevision; according to the contract, the return itself carries no revision.

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. Record the return. POST /commerce/v1/returns takes salesOrderId, the lines, reasonCode with not_as_described, damaged, incompatible, buyer_withdrawal or other, and optionally receivedAt. That is the buyer’s reason — not yet a finding.
2. Inspect the goods. POST /commerce/v1/returns/{returnId}/review takes decision with accept, reject, partial or attention_required and per line reviewedQuantity, finding and reasonCode. The response names decisionActorReference: the inspection is attributed to an actor.
3. Decide the disposition. POST /commerce/v1/returns/{returnId}/disposition decides per line between restock, repair, recycle, dispose and hold. hold is a value of its own for disposition; the contract describes no effect on offers.
4. Read the inventory ledger. GET /commerce/v1/inventory/ledger returns per entry entryType, quantityDelta and balance. entryType knows physical_set, safety_stock_set, reserved, released, consumed and expired; the contract describes no link to the disposition decision.
5. Update the stocked piece. PUT /commerce/v1/stock-items/{stockItemId} sets condition with new, used or refurbished and locationKey afresh. If condition or location changes after inspection or repair, the change belongs in the stocked piece, not in a note.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: verwendung-ruecksendung-4711' \
  -d '{"lines":[{"lineId":"<lineId>","quantity":1,"disposition":"repair","reasonCode":"<reasonCode>"}],"expectedRevision":"<revision>"}' \
  'https://commerce-preview.invalid/commerce/v1/returns/<returnId>/disposition'

What you end up with

In the end every returned part has a decided path, an attributed inspection and updated stock. For the control unit with the damaged connector, repair has been set.

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.