Headless Commerce in Riyadh — The 2026 Playbook

Headless commerce separates the storefront (what shoppers see) from the commerce engine (inventory, payments, orders). The front end is a custom-built website, usually in React or Next.js. The back end is a commerce API that handles the transactional logic. The two talk over APIs, and you can change either side without breaking the other.

For most Saudi retailers, a hosted platform like Salla or Shopify is the right starting point. Headless is the right move when you have outgrown those platforms: when your checkout needs custom logic that Liquid templates cannot express, when your Arabic RTL design needs pixel-level control that theme engines restrict, when you need a single commerce layer powering a website, a mobile app, and in-store kiosks, or when your ERP or warehouse system requires real-time two-way sync that plugin connectors cannot handle reliably.

This guide is for Riyadh retailers, e-commerce directors, and technical teams who are evaluating whether headless is the right architecture for their next build, and if so, which platform fits their Saudi requirements.

If you are not sure what headless commerce actually means, this five-minute explainer covers the concept clearly:

Headless Commerce Explained in 5 Minutes

Watch on YouTube

When headless makes sense for a Saudi retailer (and when it does not)

Headless is not a default choice. It is the right architecture when your business has specific requirements that hosted platforms cannot meet. Here are the honest triggers:

Go headless if: you need a custom checkout that Salla or Shopify themes cannot express (configurable products, dynamic pricing, B2B quote workflows). Or if you are building a single commerce layer that powers a website, a React Native app, and POS terminals from one API. Or if your Arabic RTL design needs pixel-perfect control beyond what any theme engine offers. Or if your ERP (SAP, Oracle, Odoo) requires real-time inventory sync that hosted platform connectors handle unreliably.

Stay on Salla or Shopify if: your product catalog is under 5,000 SKUs, your checkout is standard (add to cart, pay, ship), you do not have a developer on staff, and you want to be live in weeks rather than months. Headless adds complexity and cost. If your problem is content or marketing, not architecture, headless is the wrong answer. Use our platform finder to check whether hosted fits your needs first.

The four headless options Saudi retailers actually consider

Shopify Hydrogen: the managed headless path

Hydrogen is Shopify’s React-based framework for building custom storefronts powered by the Shopify backend. You get Shopify’s battle-tested commerce engine (checkout, inventory, order management, analytics) with a fully custom front end. For a Saudi retailer with an existing Shopify store that has outgrown Liquid templates, Hydrogen can be the lowest-risk headless migration, but it is a Shopify path rather than an Ijjad build service.

The Saudi-specific catch: Shopify Payments is not available in Saudi Arabia. You must use a third-party gateway (HyperPay, Moyasar, or Tap), which means paying Shopify’s 2% third-party gateway surcharge on every transaction. At SAR 5 million annual revenue, that surcharge alone is SAR 100,000/year. For high-volume Saudi retailers, this cost often justifies moving to an open-source alternative.

ZATCA Phase 2 compliance requires a third-party Shopify app. Arabic RTL is your responsibility in Hydrogen, since you are building the front end from scratch. This is actually an advantage: you get pixel-perfect RTL control instead of fighting a theme engine.

Medusa: the open-source alternative

Medusa is a Node.js headless commerce engine. It handles products, orders, customers, payments, and shipping through a modular API. The license is MIT (free), so your cost is infrastructure (hosting, database, CDN) plus development time. For a Saudi retailer doing SAR 5+ million annually, Medusa saves the Shopify Plus subscription (SAR 8,500/month) and the 2% gateway surcharge.

Mada integration is direct: you wire HyperPay or Moyasar into Medusa’s payment module. There is no platform surcharge on top. ZATCA compliance is a custom integration, which means you build or license a ZATCA module (UBL 2.1 XML generation, QR codes, Fatoora submission). This is more work than Shopify’s app approach, but it gives you full control over invoice formatting and submission timing.

The trade-off is honest: Medusa requires a committed engineering team. You own the hosting, the security updates, the database migrations, and the payment integration. If your team cannot maintain a Node.js application in production, Medusa is the wrong choice regardless of the savings.

Saleor: the multi-market option

Saleor is a GraphQL-first commerce platform built for international brands. Its multi-channel, multi-currency, and multi-warehouse architecture makes it the natural choice for Saudi retailers selling across the GCC (Saudi, UAE, Kuwait, Bahrain, Qatar, Oman) from a single backend. Each market gets its own storefront, currency, tax rules, and shipping options while sharing one product catalog.

For Riyadh retailers expanding internationally, Saleor handles the complexity that both Shopify and Medusa struggle with: SAR pricing in Saudi, AED in UAE, KWD in Kuwait, each with different VAT rates, different payment gateways, and different shipping carriers, all managed from one admin panel.

Saleor Cloud (managed hosting, starting at $500/month) removes the infrastructure burden. The open-source core is free for self-hosting. Mada integration is via direct PSP connection. ZATCA compliance is custom, similar to Medusa.

Mada, STC Pay, and BNPL in a headless setup

In a headless architecture, you integrate payment gateways directly instead of relying on platform plugins. This gives you more control but more responsibility.

Mada integration means wiring HyperPay, Moyasar, or Checkout.com into your custom checkout. The gateway provides an SDK or hosted payment fields that you embed in your React checkout page. Tokenized card-on-file billing for subscriptions is handled at the gateway level. See our payment gateway comparison for which PSP fits headless builds best.

Tabby and Tamara (BNPL) provide REST APIs that you call from your backend. The flow: your checkout sends the order total to Tabby/Tamara, receives a payment URL, redirects the customer, and receives a webhook on completion. Both have clear API documentation. Budget 2-3 engineer-days per BNPL integration on a headless build.

The advantage of headless payments: no 2% platform surcharge (unlike Shopify), direct negotiation with the PSP for volume pricing, and full control over the checkout UX (which measurably affects conversion).

ZATCA Phase 2 in a headless architecture

ZATCA Phase 2 e-invoicing is mandatory above SAR 375,000 annual revenue (Wave 24 deadline: June 30, 2026). Any Saudi retailer doing headless commerce is well above this threshold.

In a headless setup, ZATCA compliance is your responsibility. Your backend must generate UBL 2.1 XML for every invoice, embed a QR code, apply cryptographic stamps (CSID), and submit to ZATCA’s Fatoora platform via API in real time. This is a backend module that connects to your order management system. Budget 4-6 engineer-days for a production-grade ZATCA integration if building from scratch, or use a Saudi ZATCA SaaS (like ZATCA.co or Cleartax) via their API.

Arabic RTL: the headless advantage

This is where headless actually wins for Saudi retailers. On Salla or Shopify, your Arabic RTL quality is limited by the theme engine. CSS overrides fight the theme’s assumptions. Direction-aware animations break. Checkout form labels sit on the wrong side.

In a headless build (Next.js, Remix, or Astro), you control every pixel. Arabic RTL is baked into the design system from the first component. `dir="rtl"` on the HTML root, `logical properties` in CSS (`margin-inline-start` instead of `margin-left`), bidirectional text handling in product descriptions, and RTL-native form components that feel right to Arabic readers.

Arabic-speaking shoppers convert 30-50% better on native RTL stores. If your brand serves Saudi customers primarily, the RTL quality of your storefront directly affects revenue. Ijjad has been building Arabic-English web design with RTL-first architecture since 2020.

How to choose: the decision framework

When evaluating headless platforms for a Saudi retailer, the 3S Framework (Strategy, Skill, Support) applies to both the platform and the agency you hire to build on it.

Choose Shopify Hydrogen if you already run Shopify, your team knows React, you want the fastest path to a custom storefront, and the 2% surcharge is acceptable at your volume.

Choose Medusa if you have a strong Node.js team, you want zero license fees, you need custom payment and ZATCA integrations, and you are willing to own the infrastructure.

Choose Saleor if you sell across multiple GCC countries, you need multi-currency and multi-warehouse from day one, and you want managed hosting (Saleor Cloud) to reduce ops burden.

Choose custom (Next.js + API) if your business model is genuinely unique: marketplace, configurator, subscription box, or a commerce experience that no existing engine models correctly.

We audited the headless commerce guides ranking for this query

Where this guide might be biased

Ijjad builds custom/headless commerce stores. We recommend custom architecture because that is what we ship. If your business runs fine on a hosted platform and you are considering headless because it sounds modern, save the budget. Headless adds real complexity and cost that only pay off when your requirements genuinely outgrow hosted platforms.

Our platform comparisons are grounded in builds we have shipped and published documentation. We have the deepest experience with Next.js + Medusa and Next.js + custom API backends. Our Saleor and Hydrogen experience is narrower.

Frequently asked questions

Written by Karam Abdalqader, founder of Ijjad (Shmeisani, Amman, Jordan; +962 79 565 0502; Sun-Thu 9 AM-6 PM). We build conversion-focused websites and headless commerce for SMEs and founders across Jordan, Saudi Arabia, and the GCC. Internet use among Saudis 15-74 stands at 99% (GASTAT, 2025).