Concurrency

Trips, purchase orders, groups, group agreements and configuration documents carry a version that increases on every change. Use it to make a write conditional on what the user saw, so two agents cannot overwrite each other.

Purchase orders: If-Match

POST /purchase-orders/{poId}/transition and POST /purchase-orders/{poId}/changes accept an If-Match header with the version you read:

If-Match: "4"

Header	Result
Absent, or *	The write is unconditional.
The current version (4, "4" or W/"4")	The write applies; the response carries the new version.
An older version	412 version_mismatch; nothing changes. Read the order again and decide.
Not a version number	400 invalid_if_match.

POST/order-orchestration/purchase-orders/PO-8B18D9E89570/transitionA write conditional on a stale version

Request

curl -X POST "$BASE/order-orchestration/purchase-orders/PO-8B18D9E89570/transition" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Request-Id: req-0035" \
  -H "If-Match: "3"" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "frozen",
  "reason": "Hold for payment review"
}'

Response

HTTP/1.1 412
X-Request-Id: req-0035

{
  "error": "version_mismatch",
  "message": "purchase order PO-8B18D9E89570 is at version 4, not 3",
  "code": "version_mismatch",
  "requestId": "req-0035"
}

Other resources: expectedVersion

These writes take the version in the body instead:

Write	Field	Conflict
PUT /order-orchestration/config, POST /order-orchestration/config/rollback	expectedVersion	409 version_conflict
PATCH /oms-ops/groups/{groupId}	expectedVersion (required)	409 group_version_conflict
POST /oms-ops/groups/{groupId}/trips/{tripId}/status	expectedVersion	409 member_version_conflict
POST /oms-ops/lines	expectedVersion per line	409 line_version_conflict
PATCH /group-agreements/{id}	expectedVersion (required)	409 agreement_version_conflict
PUT /group-sales/group-requests/{id}/fare, POST /group-sales/party-quotes/{id}/book	expectedVersion	409 version_conflict

Mass changes

A mass change is applied with optimistic checks per line: the plan records each affected line's version, and a line that changed after planning is not overwritten (the item is reported as failed, and can be retried after review). Committing requires the plan's commitToken, so a change cannot be committed by accident or twice. See Mass change and operations.