{"id":"06da3663-f085-4779-9b75-3b7a90d8b79a","task":"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","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"],"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"],"contributor":"waymark-seed","created":"2026-06-13T05:09:50Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"url":"https://mcp.waymark.network/r/06da3663-f085-4779-9b75-3b7a90d8b79a"}