Order state, explained

As a member, I pay once and get exactly one order, even if my app retries.

Core creates the order from the confirmed basket. The order carries its items, the customer, the tenant and the payment legs.

• Every create carries an idempotency key. A retry returns the same order.
• Status changes run under a row lock, so two updates never cross.
• Each item carries a product domain: merchandise, gift card, booking, add-on or subscription.

As a member paying with points and card, my order confirms only when both legs are paid.

Each payment leg is tracked on its own. The order status follows the legs.

• All legs pending: DRAFT. Some authorised: AWAITING_PAYMENT. All captured: PAYMENT_COMPLETED.
• All legs failed, cancelled or refunded moves the order to the same state.
• Payment status is tracked beside the order status, from UNPAID to FULLY_REFUNDED.

As a member who abandons checkout, my reserved basket does not stay open forever.

A job finds DRAFT and AWAITING_PAYMENT orders past their expiry time and moves them to EXPIRED.

• The default time to live is 15 minutes.
• The payment legs expire with the order.
• EXPIRED is terminal.

As a member with a phone and a gift card in one order, I see each item move on its own.

OMS asks the Fulfillment Service to fulfil each line, and each item carries its own status. The order status is derived from its items, per the roll-up table in section 03.

• Item statuses: PENDING, PROCESSING, CONFIRMED, SHIPPED, PARTIALLY_FULFILLED, FULFILLED, FAILED, CANCELLED, REFUNDED.
• OMS never talks to a carrier. The Fulfillment Service does.

As a seller, what I do in the portal shows up as the order status everywhere else.

Merchandise orders enter OMS through an internal path, with no customer id and no payment legs. Seller actions come back as webhooks and map to OMS statuses, per the table in section 03.

• Idempotency key per seller order: sp, tenant id, merchandise order id.
• OMS is the source of truth for the status the Seller Portal shows.

As Merit Ops, when one gift card in an order fails, I retry that one without touching the rest.

Gift cards are issued through the legacy gift card engine. A failed or partly fulfilled item can be reprocessed.

• One call carries up to five gift cards. Larger lines go through the bulk path.
• Only items in PARTIALLY_FULFILLED or FAILED can be reprocessed.
• Transient failures retry with backoff. A supplier reject or out of stock does not retry.

As a seller who cannot fulfil, I cancel before shipping and the member is refunded.

An order or item is cancelled with a reason and a trigger: customer, system or admin.

• A seller cancels only before shipment, with a reason from a dropdown.
• A seller cancel happens in the merchandise service. The refund is a separate call.
• For Al Fursan, client staff cannot cancel. Merit Ops can.

As customer care, I refund an order or one item, and the record shows who asked and why.

A refund belongs to an order or to one item. A failed fulfilment that runs out of retries opens a refund request by itself. A person still approves it.

• Refundable only from CONFIRMED or FULFILLED in the spec.
• Refund window per country. Saudi Arabia: 14 days from delivery.
• Card refunds must stay inside the payment provider window of 30 days.
• Partial refund amounts, and refunds on mixed points and card payments.OPEN

As the fraud team, a risky gift card order waits a few hours before it is fulfilled.

Admin rules hold an order before fulfilment. They match on product type, minimum price, category or collection. When several match, the longest wait wins.

• The item stays Placed. No new status, and the member sees no difference.
• Reprocess is blocked inside the window. Cancel and refund are allowed.
• The rules are set in the Storefront Admin Portal, and OMS applies them.

As Merit Ops, I can see every status an order went through, when, and who moved it.

Every change writes a row to the order status history.

• Append only. A row is never edited.
• Each row records what triggered it: platform, system or admin.

As a downstream service, I subscribe to the order events I need instead of polling.

OMS sends nine events to registered webhook endpoints.

• ORDER_CREATED, ORDER_CONFIRMED, ORDER_PROCESSING, ORDER_PARTIALLY_FULFILLED, ORDER_FULFILLED, ORDER_CANCELLED, ORDER_REFUNDED, ORDER_FAILED, ORDER_EXPIRED.
• Notifications and settlement react to these events. OMS does not call them directly.

As a seller packing boxes, I read a short reference, not a long system id.

A short reference sits next to the system order id and is printed on the pick and pack label.

• Format SELLER_PREFIX-YYMMDD-NNNN, for example AF-260819-0042.
• The counter runs per seller per day and resets at Riyadh midnight.
• Never usable to look an order up: not in a URL, not in an API.

As a client ordering 3,000 gift cards, I place one order and track one status.

Large gift card orders are split into calls of five behind one order the client sees.

• Bulk orders over five items: 24 hour SLA. Five or fewer: instant.
• The parent order that holds the batches is not built yet, and partial failure handling is not decided.OPEN

As Finance, money moves only when an order is final.

Settlement is its own service. It runs once fulfilment completes or breakage happens, turns the hold into a charge, and records the revenue line.

• OMS tracks the order. Settlement tracks the money.
• Delivery and its money consequences are never built as one thing.

As an Al Fursan member, my Miles cashback lands after delivery, not at payment.

Earned cashback is released by order state, anchored on delivery.

• Delivery must happen first. An open return, refund, cancellation or care case freezes release.
• A refund for non-delivery cancels the order and the earn together.
• Phase 1 cancels and returns the whole order. Per item comes later.