{"lexicon":1,"id":"money.atmosphere.order.updateFulfillment","defs":{"main":{"type":"procedure","description":"Apply one app-authored fulfillment transition to a routed commerce order. Requires app service-auth from the order's fulfillment owner. expectedRevision is an optimistic fence against the current canonical revision; idempotencyKey makes retries return the original recorded outcome without duplicating history. Payment-derived financial state is never writable here.","input":{"encoding":"application/json","schema":{"type":"object","required":["id","expectedRevision","fulfillmentStatus","idempotencyKey"],"properties":{"id":{"type":"string","maxLength":64},"expectedRevision":{"type":"integer","minimum":1},"fulfillmentStatus":{"type":"string","knownValues":["ready","processing","partially-fulfilled","fulfilled","on-hold","canceled","failed"],"maxLength":32,"description":"Target fulfillment state. unfulfilled is payment-owned and never an app target; transitions are validated against the fulfillment state machine."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200},"note":{"type":"string","maxLength":1000,"maxGraphemes":1000},"tracking":{"type":"ref","ref":"money.atmosphere.order.defs#tracking"}}}},"output":{"encoding":"application/json","schema":{"type":"object","required":["order","event","replayed"],"properties":{"order":{"type":"ref","ref":"money.atmosphere.order.defs#order"},"event":{"type":"ref","ref":"money.atmosphere.order.defs#fulfillmentEvent"},"replayed":{"type":"boolean","description":"True when this response replays a previously recorded mutation for the same idempotencyKey."}}}},"errors":[{"name":"AppNotRegistered"},{"name":"OrderNotFound"},{"name":"RevisionConflict","description":"expectedRevision does not match the current canonical revision. The error body additionally carries currentRevision plus the current financial/fulfillment state; re-read the order and retry from current state."},{"name":"InvalidFulfillmentTransition"},{"name":"IdempotencyConflict"},{"name":"OrderPaymentSettling","description":"A cancel was refused because the processor reports the order's checkout already completed or is processing: the buyer's payment wins and settlement will advance the order shortly. The error body carries the current revision and financial/fulfillment state; re-read the order and decide from its paid state."},{"name":"OrderCheckoutBusy","description":"A cancel was refused because the order's checkout state could not be confirmed with the processor. Nothing changed; retry shortly."},{"name":"OrderRoutingUnavailable","description":"The federated commerce order lifecycle is not enabled on this deployment."},{"name":"RateLimited"}]}}}