An order has several independent states An ecommerce order can be created before payment, paid before fulfillment, partly shipped, refunded after delivery,...
An order has several independent states
An ecommerce order can be created before payment, paid before fulfillment, partly shipped, refunded after delivery, or canceled while a payment request is still pending. One status string often becomes ambiguous. Model payment, fulfillment, and return state separately, then define the transitions that are valid for each.
For example, payment may move from pending to authorized to captured, while fulfillment moves from unfulfilled to packed to shipped. A refund should refer to the captured payment and quantities affected, not merely set the whole order to "refunded" when only one item was returned.
Define transition rules
Create a table or state diagram listing the actor, precondition, action, resulting state, and side effect. A warehouse user may mark an item shipped but should not change the captured payment amount. A customer can request cancellation, but the operation may require review after fulfillment has started.
Reject invalid transitions in the service layer and test them. A user interface that hides a button is not enough; the same endpoint may be called directly.
Handle asynchronous payment events
Payment providers send webhooks that can be delayed, duplicated, or out of order. Verify signatures and store provider event IDs. The order should be updated idempotently and reconciled with the provider when the local state is uncertain. Do not mark an order paid because the browser returned from checkout.
Reserve stock and define how a failed payment releases it. The exact reservation policy depends on product and traffic; document its expiry and failure recovery.
Preserve an event history
Store who or what triggered each transition, the timestamp, and relevant provider reference. This supports customer support and dispute resolution. Avoid changing historical totals when catalog prices change; order line items should retain the agreed price and tax calculation at purchase time.
Test competing events
Test duplicate payment webhooks, cancellation during fulfillment, partial refund, inventory shortage, and two workers trying to ship the same item. Assert no duplicate side effect and no impossible state combination.
Conclusion
Separate states and explicit transitions make orders understandable during retries and exceptions. Our web and SaaS development service covers ecommerce implementation and integrations.
References