How an order becomes a parcel, which system decides that, and why it is built this way.
Owner: Brian Arfi Faridhi, Product Director · Audience: anyone new to fulfilment, product or engineering
01In one minute
If you read one section, read this one.
When someone buys a physical product on the Merit stack, something has to book a courier, print a label, and tell the customer where the parcel is. In the Old World that is MGC, and MGC only knows products that exist in the old Online Catalogue. A product a seller lists in the new Seller Portal is unknown to it.
Two pieces do the job in the New World. The Merit Fulfillment Service sits between OMS and every possible way of fulfilling an order, and decides which one to use. OTO is a commercial shipping aggregator: one API reaching 200 or more carriers across the GCC, so we never integrate Aramex, SMSA or Saudi Post one at a time.
MGC stays behind the Fulfillment Service as one more provider: it issues gift cards, and it is the fallback for physical goods, so no order is ever stranded.
02Four systems, one job
These four names get used interchangeably in standups and they are not the same thing. Getting them apart is most of the confusion.
The brain
Merit Fulfillment Service
Ours, its own service. Takes an approved order line from OMS and decides who fulfils it: OTO, STC, MGC or the legacy Merchandise service. Owns the fulfillment record and its history, turns every provider status into one shape, and pushes it back to OMS. It does not ship anything itself.
The courier network
OTO (tryoto.com)
A third-party shipping aggregator we pay for. One integration, 200 or more GCC carriers behind it. Creates shipments, returns labels and tracking, quotes rates. Physical goods only. It cannot fulfil a gift card.
The legacy engine
MGC
The old platform. Still ships anything living in the old Online Catalogue, and still issues gift cards. It stays as a gift card supplier behind the Fulfillment Service, and it is the fallback for physical goods.
Upstream
OMS
The order layer, and the single source of truth for order status. Hands an approved order to the fulfillment service, and never calls OTO directly. The Seller Portal reads fulfilment status from OMS, not from the fulfillment service.
Why OMS never calls OTO
Orders pass to the fulfillment service first, and the fulfillment service routes to OTO as one provider among several. It matters because the alternative, OMS calling OTO itself, would have hard-wired one courier network into the order layer and made STC, SACO and Salasa a rewrite each.
03The system map
Left to right. The middle box is the piece being built. Switch the line type and watch which branch carries it.
Physical line, sourced from the Seller Portal. Question one passes, question two sends it to OTO.
Two properties of this shape are worth naming, because they are why it was drawn this way rather than the obvious way.
Providers are swappable. Today it routes to OTO, STC, MGC and the legacy Merchandise service. SACO and Salasa are the next ones. In this shape each is an adapter behind the same interface, not a change to OMS.
The toggle makes rollout reversible. The OTO path sits behind a per-environment feature toggle. Turn it off and every order falls back to MGC, no deploy, no stranded orders.
Phase 1 is an extraction, not a green field
Phase 1 lifts vendor-selection logic that already exists inside OMS out into the new service. OMS keeps order state management and nothing else.
04The routing rule
Two questions, asked in this order. The order is the whole rule.
Is the line digital or physical?
A gift card, voucher or digital code always takes the gift card route, whatever else is true about it. OTO is a shipping aggregator and physically cannot fulfil a code. Only a physical line falls through to question two.
Where did the item come from?
Sourced from the Seller Portal, the new world, it goes to OTO. Sourced from the Online Catalogue, the old world, it stays on MGC. The source is stamped onto the order line at creation as item_source, so routing reads a recorded value rather than re-deriving it later, when the product record may have changed.
If either answer is unknown, fall back
Undetermined source, or the toggle switched off, routes to MGC and is logged for review. No order is ever stranded during rollout.
A rule for a case that does not exist yet
Today the Seller Portal carries third-party physical merchandise only, and digital products run first-party through the Live Ops console, so a digital line can never arrive carrying a Seller Portal source. The precedence rule exists precisely so the router does not silently depend on that staying true. Cheap now, expensive later.
The money guardrail
A shipment is blocked when item cost + taxes + OTO shipping cost exceeds selling price × 1.01. We never knowingly ship at a loss; a blocked shipment is flagged and falls back to the old flow, and a manager can override it with the override logged.
05One order, end to end
A customer buys a physical product from a Seller Portal seller.
Order placed and paid
B2C Super App or a tenant Storefront. OMS records it and manages its state.
OMS hands the approved order over
Tenant ID, client order ref, and line items with item_source already stamped. A 5xx is retried by OMS against an idempotency key, so a retry never creates a second shipment.
The service creates a record and routes
One authoritative record per fulfillable order item, opened in PENDING. Product type first, then item source.
Rate check and guardrail
Rate fetched from OTO by weight, size and destination. If the total breaches the 1 percent rule, the shipment is blocked and flagged instead of booked.
Shipment created in OTO
OTO picks the carrier and returns a tracking number and a label, stored against the order. No manual step anywhere in this path.
Stock decremented through the Seller Portal
Not through MGC. This is what finally makes stock accuracy independent of the legacy platform.
Tracking flows back as one timeline
OTO webhooks normalised into a single status flow, so the customer sees the same timeline whether the parcel went via OTO or MGC.
The delivery event fires
Which is what seller payout and settlement wait on. OMS tracks the order, Settlement tracks the money.
06Where a warehouse lives
The obvious answer is wrong: a seller warehouse is not stored in the Seller Portal.
The grain is per warehouse, not per seller. A seller has many warehouses, and each offer ships from one of them. Switching a warehouse off switches off every offer linked to it, the same as zero stock.
A business address is not a warehouse
The seller's registered business address, the one checked at onboarding, also lives in Identity. It is a different record. OTO collects from a warehouse, so a warehouse needs what a courier needs: an exact map pin, and a pickup contact name, email and mobile.
07One provider that works differently: STC
The Al Fursan Apple Store, where STC is the Apple distributor.
First, Riyadh only
Availability is checked for Riyadh. STC ships the goods to the Merit warehouse in Riyadh, and Merit runs the last mile through SPL.
Then, by city
The member picks a city when entering the Apple Store, availability is checked for that city, and STC delivers direct.
Supplier order
STC first, then Aleph, then Almanea. A product is available when at least one of them holds stock.
08Glossary
The words that get used loosely in this lane.
Fulfillment Service
Merit's own service. Decides which provider fulfils each order line, owns the record of what happened, and reports status back to OMS.
OTO
tryoto.com. A commercial shipping aggregator reaching 200 or more GCC carriers through one API. Physical goods only.
TMS
Transport Management System. The older internal name for the logistics layer. Today "TMS" and "the OTO integration" mean the same thing: carrier orchestration on OTO, behind the Fulfillment Service.
MGC
The legacy platform. Issues gift cards and ships Old World goods. In the New World it is one provider behind the Fulfillment Service.
Item source
SELLER_PORTAL or ONLINE_CATALOGUE, stamped onto each order line at creation. The second question the router asks.
Feature toggle
Per-environment switch controlling whether the OTO path is live. Off means everything falls back to MGC with no deploy.
Margin guardrail
The rule blocking a shipment when item cost plus taxes plus shipping exceeds selling price times 1.01. Overridable by a manager, override logged.
NDR
Non-Delivery Report. What happens after a failed delivery attempt. Designed as three automated re-attempts through OTO before escalating to LiveOps.