Implement commercetools Order Management System (OMS) state machine with custom order states and transition guards for B2B order approval workflow
domain: commercetools OMS state machine · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Define custom order states in commercetools using the States API with type Order, creating states for PendingApproval, Approved, Rejected, InFulfillment, and Completed with explicit allowed transition pairs
Set the initial state on order creation to PendingApproval by including the state reference in the order creation payload, bypassing the default open state
Implement a backend approval service that subscribes to commercetools message subscriptions for the OrderStateChanged message type and routes approval notifications to the appropriate approver based on order value thresholds or customer group
On approver action, transition the order state via the Order Update endpoint using the changeOrderState or transitionState action, which validates the transition against the state machine definition and rejects invalid transitions
When the state transitions to Approved, trigger the fulfillment workflow by creating fulfillment-related custom objects or publishing an event to a downstream fulfillment service
Expose the current order state and transition history to the B2B customer portal via the commercetools GraphQL API, filtering state transitions by type Order to provide an audit trail
Known gotchas
commercetools state machine transitions are validated server-side; attempting an invalid transition returns a 400 error with an InvalidTransition error code that must be surfaced to the approver as a meaningful UI message
Custom states replace the built-in order state; built-in fulfillment and payment state machines remain separate and must be managed independently alongside the custom approval state machine
The OrderStateChanged message is published asynchronously after the state change is committed; message subscription consumers may receive it with a delay and must not assume the order is still in the original state when processing the message
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?