Holding an ordered unique piece until the order is fulfilled or settled

A headlight is listed on two channels and ordered on one. Hours pass before it is packed. If it is ordered again on the second channel in the meantime, one buyer has to be turned down — and that costs more than just this sale.

The reservation binds a concrete stocked piece to an order line. It ends consumed when the goods leave the building, or released when the sale does not happen; state also knows the value expired. Both take quantities and appear as entries in the ledger.

What this case requires

• An order with lines. The reservation requires salesOrderId and orderLineId; a reservation without an order is not provided for.
• A stocked piece instead of an item number. What is reserved is a concrete specimen with a stockItemId.
• The current revision. Every change to the reservation carries expectedRevision.
• A channel that supports reservations. The capabilities state it per channel.

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. Reserve. POST /commerce/v1/inventory/reservations takes stockItemId, quantity, salesOrderId, orderLineId, expectedRevision and optionally expiresAt. From now on the piece is bound to this line; according to the contract, availableQuantity in the stock is derived taking active reservations into account.
2. Check the state. GET /commerce/v1/inventory/reservations/{reservationId} names initialQuantity, reservedQuantity, releasedQuantity, consumedQuantity and state. With several pieces this shows how much is still bound.
3. Consume. POST /commerce/v1/inventory/reservations/{reservationId}/consume takes quantity, reasonCode — on shipment fulfilled — and expectedRevision. Consumption happens when the goods leave the building, not when the order comes in.
4. Release. POST /commerce/v1/inventory/reservations/{reservationId}/release returns quantities, for example with order_cancelled, order_changed, expired or manual_review. A reservation that is never released blocks a sellable part without a buyer.
5. Read the ledger. GET /commerce/v1/inventory/ledger records reservation, consumption and release as entries with reservationId, quantityDelta and balance. Every movement of a unique piece can thus be explained later.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: reservierung-4711-versand' \
  -d '{"quantity":1,"reasonCode":"fulfilled","expectedRevision":"<revision>"}' \
  'https://commerce-preview.invalid/commerce/v1/inventory/reservations/<reservationId>/consume'

What you end up with

In the end reservedQuantity, releasedQuantity and consumedQuantity show which quantity is still bound, released or consumed, and state names the state of the reservation. Whether a second buyer could still order the part in the meantime depends on how promptly the offer on the second channel was updated.

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.