Orders and returns

The job

A shopper places an order that needs stock from several locations. Your application must reserve inventory, take payment, arrange fulfillment, and show what has happened. Later, the shopper may return an item for inspection, replacement, or refund. Each lifecycle needs a visible result and clear handling of partially completed work.

Orders and returns are related processes with different completion rules. You define those rules and the integrations with inventory, payment, shipping, and accounting services. Ironflow supplies execution and event-state components.

The flow

An order request is validated against application rules. A workflow reserves stock, calls the payment provider, and starts fulfillment. Explicit order events feed customer and operations views. The application can fan out independent warehouse work while keeping one order-level result.

A return request starts its own linked lifecycle. Receive the item, record an inspection decision, and coordinate replacement or refund. Linking by order and item identifiers lets staff see related work without treating a return as a replay of the original purchase.

The difficult moment

A warehouse allocation fails after payment has completed. A transient failure is retried. Registered compensation, such as releasing other stock holds or requesting a refund, runs only when the failure ends the run: a non-retryable error, or the last attempt when the function’s onExhausted policy is fail. Under the default pause policy, the last failed attempt pauses the run with its completed steps, and nothing is compensated until it resumes or is cancelled.

Compensation is an external action that can also fail. Make refunds and releases idempotent and retain the identifiers needed to reconcile uncertain results. Cancelling a run does not automatically execute saga compensations; implement the customer-cancellation policy explicitly.

Ironflow’s role

Durable steps preserve completed payment and allocation results. SDK saga compensation supports application-defined undo steps on non-retryable failures. Entity streams can maintain explicit order and return facts with optimistic concurrency, while projections derive customer details and staff queues.

Your domain rules decide whether a command is valid and whether an allocation can proceed. Version checks detect competing changes to a stream; the application handles the conflict. Provider idempotency is still required for charges, refunds, and external inventory changes around interrupted calls.

Implementation sketch

This is an illustrative flow:

1. Validate the order command and append its domain event.
2. Reserve inventory and register idempotent release actions.
3. Take payment using a stable provider key.
4. Arrange fulfillment and publish order-status events.
5. Compensate according to policy on a terminal failure.
6. Start a linked return run for inspection, replacement, or refund.

Starting point

• CQRS and event sourcing implements an order path through commands, entity events, projections, and queries. It provides an order-state starting point; the complete returns lifecycle is yours to build.
• Sagas and compensation explains durable undo steps and the distinction between retryable failures and compensation.
• Entity streams covers append-only facts and version checks for concurrent order changes.