Order Processing Pipeline
Why orders need a pipeline
Section titled “Why orders need a pipeline”Placing an order is not the end of the transaction. It is the beginning of a multi-step process that spans payment capture, fraud review, warehouse picking, shipping, delivery confirmation, and potentially returns. Treating order processing as a single step means losing visibility into where each order stands, which makes customer service reactive and fulfillment error-prone.
Optimizely Commerce models order processing as an event-driven pipeline with explicit states. Each order moves through a defined sequence, and each transition publishes events that downstream systems can consume. This gives operations teams real-time visibility and gives developers clean integration points for connecting external systems.
Order states
Section titled “Order states”An order moves through a series of states from placement to completion. The built-in state machine covers the standard lifecycle.
| State | Meaning | Typical next states |
|---|---|---|
| In Progress | Cart is still being built (pre-checkout) | Completed |
| Completed | Order has been placed and payment authorized | On Hold, Awaiting Exchange |
| On Hold | Order paused for manual review (fraud, stock, etc.) | Completed, Cancelled |
| Awaiting Exchange | Processing a fulfillment or shipment | Partially Shipped, Shipped |
| Partially Shipped | Some line items shipped, others pending | Shipped |
| Shipped | All items shipped | Returned |
| Cancelled | Order cancelled before fulfillment | — (terminal) |
| Returned | All items returned | — (terminal) |
Not every order follows the same path. A digital-only order might skip from Completed directly to Shipped. A partially available order might split into multiple shipments, moving through Partially Shipped before reaching Shipped.
Shipments and fulfillment
Section titled “Shipments and fulfillment”Commerce separates orders from shipments. A single order can produce multiple shipments when items ship from different warehouses, have different delivery dates, or use different shipping methods.
Each shipment tracks:
- Line items — Which variants and quantities are in this shipment
- Warehouse — Which inventory location fulfills this shipment
- Shipping method — The carrier and service level
- Tracking information — Carrier tracking numbers and URLs
- Shipment status — Its own state independent of the order state
This separation matters because an order is not “shipped” until all its shipments are shipped. The pipeline aggregates shipment states to determine the overall order state automatically.
Payment capture
Section titled “Payment capture”Payment authorization happens at checkout, but capture — actually moving money from the customer to the merchant — happens at fulfillment. This is a deliberate design choice.
The capture flow:
- Checkout — Payment is authorized for the full order amount
- Shipment created — A shipment is prepared for a subset of line items
- Shipment dispatched — Payment is captured for the shipped amount
- Partial shipment — If only some items ship, only the corresponding amount is captured
- Remaining items — Captured when their shipment dispatches, or voided if cancelled
This per-shipment capture model prevents overcharging. If a customer orders three items and one is backordered, they are only charged for the two items that ship. The backordered item’s payment is captured when it ships or voided if cancelled.
Returns and RMA
Section titled “Returns and RMA”Returns are modeled as a reverse flow through the pipeline. Commerce supports Return Merchandise Authorization (RMA) as a structured process.
The return workflow:
- RMA requested — Customer or service agent initiates a return for specific line items
- RMA approved — The return request is reviewed and approved (can be automatic based on rules)
- Items received — Warehouse confirms receipt of returned items
- Refund processed — Payment refund is issued to the original payment method
- Inventory updated — Returned items are added back to available stock (if in sellable condition)
Each step publishes events, enabling external systems to react. An ERP might update its accounting when a refund is processed. A customer service platform might close the support ticket when items are received.
Partial returns
Section titled “Partial returns”A customer who ordered five items can return two. Commerce tracks returns at the line-item level, so partial returns do not affect the remaining fulfilled items. The refund amount corresponds only to the returned items, including any applicable restocking fees defined in your return policy.
Why the pipeline is event-driven
Section titled “Why the pipeline is event-driven”The order processing pipeline publishes events at each state transition. This architecture provides three key benefits:
Loose coupling. External systems (ERP, warehouse, email, analytics) subscribe to events rather than being called directly. Adding a new integration does not require modifying the pipeline.
Auditability. Every state change is recorded with a timestamp and the triggering action. You can reconstruct the full history of any order from its event stream.
Extensibility. Custom event handlers can inject business logic at any transition point. When an order moves to “Completed,” a handler might trigger a fraud check. When a shipment is dispatched, a handler might send a shipping confirmation email.
| Event | Typical subscribers |
|---|---|
| Order completed | Fraud review service, ERP sync, confirmation email |
| Shipment dispatched | Email notification, tracking page, analytics |
| Payment captured | ERP accounting, revenue reporting |
| Return approved | Warehouse system, customer service platform |
| Refund processed | ERP accounting, customer notification |
Customizing the pipeline
Section titled “Customizing the pipeline”Commerce Customized lets you modify the state machine by adding custom states or changing transition rules. For example, a pharmaceutical company might add a “Compliance Review” state between Completed and Awaiting Exchange. A made-to-order manufacturer might add a “Production” state.
Custom states participate in the same event system. Your custom “Compliance Review” state publishes events that your compliance system subscribes to, and the pipeline only advances when the compliance system signals approval.
1. A customer orders three items. Two ship immediately, but one is backordered. How does Commerce handle payment capture?
Commerce captures payment per shipment, not per order. Only the shipped items' value is captured. The backordered item's portion is captured when it ships or voided if the item is cancelled.
Commerce captures payment per shipment, not per order. Only the shipped items' value is captured. The backordered item's portion is captured when it ships or voided if the item is cancelled.
Review this topic →2. An architect wants to add an ERP sync when orders are placed, without modifying the existing order pipeline code. What approach should they use?
The event-driven architecture lets you subscribe to pipeline events without modifying the pipeline itself. This maintains loose coupling and makes the integration easy to add or remove.
The event-driven architecture lets you subscribe to pipeline events without modifying the pipeline itself. This maintains loose coupling and makes the integration easy to add or remove.
Review this topic →3. A customer returns 2 of 5 items from an order. What happens to the other 3 items?
Commerce tracks returns at the line-item level. Partial returns process only the specified items and issue a refund for those items without affecting the rest of the order.
Commerce tracks returns at the line-item level. Partial returns process only the specified items and issue a refund for those items without affecting the rest of the order.
Review this topic →