Merit · Al Fursan · STC · Internal
What STC is, why its stock model does not fit Merit, the shape the team settled on, and exactly where the legacy build stands today. Written for the Al Fursan migration team, because STC exists in legacy and does not exist in the new Seller Portal at all.
Nothing here is data that moves. All of it is code that has to be written a second time.
Al Fursan sells Apple products, and STC is the official Apple distributor in Saudi Arabia. Merit onboarded STC because the previous supplier was unreliable and orders were cancelled after payment for lack of stock. That integration lives in the legacy Platform merchandise service today, under MPS-1468.
The new Seller Portal has no supplier integration for STC. It has no coordinate-gated fulfilment, no per-city stock model, and no order placement against an external distributor. So when Al Fursan moves to the Ecommerce Solution, STC does not migrate. It gets built.
The Platform team sized the legacy work at roughly 9 to 14 days back in July, before the scope was cut. Nobody has sized the new Seller Portal build. Muneeb Meer was asked on 31 August and the request is still open, so the effort against this line is unknown.
Four properties of STC's model. Every complication downstream comes from one of them.
STC exposes in stock or out of stock, per city, refreshed daily. There is no quantity per SKU, per warehouse or per coordinate. Merit's inventory model is SKU based and location agnostic.
STC requires an exact latitude and longitude at order placement and fulfils only if the item is available in that area. Merit holds short code addresses, not coordinates.
STC ships from many warehouses, identified at city level only, and self ships by default.
STC has no human operator on their side. They push a catalogue and expose stock and order APIs. Everything is machine to machine.
STC's stock is real per city, and the Al Fursan storefront is national. A Riyadh buyer and a Jeddah buyer see the same page, but STC can only answer for one city at a time.
Six calls are in scope. Requests and responses are wrapped in an
mw_request and mw_response envelope with a transaction id and timestamp.
| Endpoint | Method | Purpose | Notes |
|---|---|---|---|
/getAvailableStock | GET | Cities, each with the item codes available there | Boolean per city. No quantities |
/getItemsAvailability | POST | Availability for latitude, longitude, item code and quantity | Returns availableQuantity. Open whether it is the total or capped at the requested amount |
| Endpoint | Required fields | Notes |
|---|---|---|
/placeOrder | orderNumber, latitude, longitude, itemCode, quantity, idempotency key | Reserves stock for around ten minutes |
/confirmOrder | orderNumber, mobileNumber, fullName | Creates the real order. Optional collectAmount, preferSingleShipment, preferredDateAndTime |
/cancelOrder | orderNumber | |
/return | orderNumber, latitude, longitude, itemCode, quantity | Optional serial number from STC post delivery status |
| Status tracking | orderNumber | STC gives no end user tracking details. Confirmed |
/getItemPrice returns itemCode, netPrice,
netPriceWithVat, grossPrice and Currency. Which one is
customer facing is still an open question with STC.
One delivery address. It removes the city mismatch rather than solving it.
Every earlier proposal spent its length on cross city fallback, location aware listings, capturing the buyer's city while browsing, and rejection at checkout. The current approach deletes all of it.
STC delivers to a single Merit address. Merit delivers to the customer. STC is only ever asked about one city, so the buyer's location stops being an input to STC. It becomes an input to Merit's own delivery leg, which Merit already runs for every other supplier.
| Problem in the direct to customer model | What one delivery address does to it |
|---|---|
| Buyer completes checkout, then is told the item cannot reach them | Gone. STC is only asked about the office city |
| Storefront shows national stock that is not nationally real | Gone. One warehouse, one truth |
| Cross city fallback needed before launch | Gone. Not needed at all |
| Buyer city must be captured during browsing | Gone. Never asked |
| STC gives no tracking URL | Gone. The customer sees Merit's tracking |
| Merit holds short addresses, STC needs coordinates | One constant. The resolver stops being a per order lookup |
The cost is one extra hop, plus Operations receiving and dispatching by hand. That is the same trade Operations already make for Almanea and Let's Tango.
Akshay Chennupati confirms on Monday 14 September whether STC delivers to one Merit address or direct to the customer. A direct to customer answer brings the per order coordinate lookup back, and the deleted rows above return with it.
Nine steps. Two of them are deliberately manual.
| # | What the customer does | What runs behind it | Where |
|---|---|---|---|
| 1 | Browses the Apple Store, anywhere in Saudi | get_stock_api gives STC's in stock flag for the office city, merged with Almanea and Let's Tango | MPS-1579 |
| 2 | Picks a product, goes to checkout | No STC call. The buyer's city does not matter yet | no change |
| 3 | Enters a delivery address | Merit validates it for its own delivery leg, as for every other supplier | no change |
| 4 | Places the order and pays | check_item_availability with the office coordinates, then place_order reserves stock, then confirm_order on payment | MPS-1580 |
| 5 | Sees the order confirmed | Merit's order status. STC's statuses stay internal | MPS-1578 |
| 6 | Waits | STC ships to the Merit office. get_status_api or callback_api reports arrival | MPS-1578 |
| 7 | Waits | Operations receive, check and dispatch on Merit's normal courier | manual |
| 8 | Gets tracking | From Merit's delivery leg, not STC's | no change |
| 9 | Returns within 7 days | Returns to Merit. Operations settle with STC by hand | manual |
The customer never experiences STC. They see an Al Fursan order, one tracking number, one point of contact.
Verified in Jira on 11 September 2026. Four sub-tasks are in flight, two items are not started.
| Ticket | Title | Status | Owner | Journey step |
|---|---|---|---|---|
| MPS-1468 | STC Supplier Integration (parent) | In Progress | Akshay Chennupati | all |
| MPS-1578 | STC API integration | In Code Review | Vitaly Koval | 5, 6 |
| MPS-1581 | Coordinates resolver | In Code Review | Vitaly Koval | 4, now a fixed constant |
| MPS-1579 | Inventory and price sync business logic | In Progress | Vitaly Koval | 1 |
| MPS-1580 | Order placement business logic | In Progress | Vitaly Koval | 4 |
| MPS-1649 | Stock validation API for Apple Store checkout | To Do | unassigned | 4 |
| MP-12159 | Record STC stock availability on the order (Marketplace side) | To Do | unassigned | 4 |
| MPS-1527 | API review and planning | To Do | unassigned | redundant, to close |
Akshay confirmed on 10 September that the STC API integration itself is done. The only new work the single address approach adds is one configuration item: the Merit office address and its coordinates, set once.
MP-12159 and MPS-1649 were rewritten after the Marketplace sprint planning of 10 September.
The original requirement read the customer's short address, derived the city, checked STC stock for that city, and blocked payment when the item was unavailable there. That is not what is being built.
The order item carries stc_fulfillable = true. The customer sees no change.
stc_fulfillable = false. The order proceeds and the existing supplier fulfils it.
The customer sees no change.
stc_fulfillable = unknown. The order completes as normal. The check never delays
an order and never stops one.
The customer never sees an out of stock outcome, because if an item is live on the marketplace then either STC or the existing supplier holds it. Supplier switching itself stays manual. This ticket records the answer on the order, it does not route the order. Automated switching lands with the Ecommerce Solution.
The check blocks nothing and shows nothing, so it does not have to sit in the checkout path. Option A runs it at the payment step with a two second budget. Option B runs it right after the order is placed, which removes every latency risk. Product recommends Option B.
Four questions sit with STC. Two have been open since the technical call of 19 August.
| # | Open item | Owner | Why it blocks |
|---|---|---|---|
| 1 | What the R7 field is, and what it keys to | STC IMS team | Without it STC items cannot be mapped to the Merit catalogue, so step 1 cannot run |
| 2 | Which price field is customer facing: netPrice, netPriceWithVat or grossPrice | STC IMS team | The wrong field means the wrong money on every order at step 4 |
| 3 | Which order statuses are terminal, and what PARTIALLY-COMPLETED means | STC IMS team | Step 6 cannot decide when the item has arrived |
| 4 | Whether STC delivers to one Merit address or direct to the customer | Akshay Chennupati | It sets MPS-1580 and MPS-1581, and whether MP-12159 ships at all. Due Monday 14 September |
One more, and it is commercial rather than technical. If the single address approach holds, the Merit office address does not exist in any document yet. Operations have to name it and confirm STC can deliver to it. The delivery SLA with a second leg added, and who absorbs the cost of that leg, are also unanswered.
This is the line for the laundry list, and the sizing that is missing.
An effort estimate for the six items above, and any gap or question that has to close before build starts. The full brief written for this purpose is the STC API and Integration Brief, listed below. The Platform team's own number for the legacy build was 9 to 14 days, before the scope was cut to one delivery address.
All of these live in the product repo as markdown. None of them is in Drive yet, which is why this page exists.
What it does not tell you, and what goes stale first.
No source code was read. The build state comes from Jira on 11 September 2026 and from the tickets' own descriptions, so a branch merged since then is not reflected here.
The new Seller Portal effort is unsized. Every number on this page describes the legacy build.
The single delivery address is a proposal, not a decision. Akshay's answer on Monday 14 September changes sections 3, 4 and 6 if it goes the other way.
The commercial questions are not answered anywhere: who carries the cancellation risk with Al Fursan, and whether the launch catalogue is full or limited to what a supplier can back nationally. Both have been open since 20 August.