KSA Shipping — Saudi Arabia Carrier Integration

Shopify App | v2.0.0 — January 2025 | Production

Shopify carrier service app purpose-built for the Saudi Arabian logistics landscape. Covers 4,379+ cities across all 13 KSA regions with 3-tier zone-based pricing, COD support, bilingual AR/EN checkout, and intelligent business rules for free shipping thresholds, Home Delivery assembly services, and KSA business calendar-aware delivery estimates.

4,379+

Cities Mapped

KSA Regions

Pricing Tiers

Primary Cities

<200ms

Webhook Response

Languages (AR/EN)

Technology Stack

Remix 2.16 TypeScript 5.7 Prisma 6.2 Polaris 12 Shopify UI Extensions React 18 PostgreSQL GraphQL

13 Saudi Regions Covered

Every city in the Kingdom is mapped to one of 13 administrative regions, each with Arabic and English names. The checkout extension dynamically filters cities by region for accurate address selection.

Riyadh الرياض

Makkah مكة

Madinah المدينة

Qassim القصيم

Eastern Province الشرقية

Asir عسير

Tabuk تبوك

Hail حائل

Northern Borders الحدود الشمالية

Jazan جازان

Najran نجران

Bahah الباحة

Jawf الجوف

Tier Zone-Based Pricing Settings

65 primary cities are organized into pricing tiers based on logistics accessibility. Tiers, rates, and weight surcharges are fully configurable by the merchant. Below is an example configuration:

Example

Tier	Coverage	Example Cities	Rate
Tier 1	Major hubs (6 cities)	Riyadh, Jeddah, Dammam, Al Khobar, Dhahran, Ad Diriyah	19 SAR
Tier 2	Regional centers (33 cities)	Abha, Madinah, Buraydah, Tabuk, Hail	20 SAR
Tier 3	Remote areas (26 cities)	Najran, Jazan, Mecca, Northern Borders	21 SAR

Weight surcharge example: 22 SAR base for 15kg, +1 SAR per additional kg. Home Delivery: 85 SAR base for 40kg, +1 SAR/kg above.

Key Capabilities

‣ Real-time rate calculation via Shopify carrier service webhook (<200ms response)
‣ Bilingual checkout extension — automatic Arabic/English based on checkout language with RTL support
‣ Region → City dropdown — dynamic filtering of 4,379+ cities by selected region
‣ Short address code validation — 8-character format (4 letters + 4 digits) for Saudi National Address
‣ COD (Cash on Delivery) support with reconciliation
‣ Product tag-based routing — GraphQL queries detect Home Delivery, Accessories, Apparel, Footwear tags
‣ GraphQL caching — 5-minute TTL reduces Shopify API calls by 80%
‣ KSA business calendar — delivery estimates respect Saturday–Thursday work week, skip Fridays
‣ Automated waybill and label generation
‣ Buyer journey interception — blocks checkout if region, city, or address code is missing

Shipping Calculation Flow

City Mapping

Parse "Region_City" format with Arabic/English support and Alef normalization

Cart Analysis

Fetch product tags via GraphQL to detect Home Delivery items (cached 5 min)

Order Total

Convert halalas to SAR, sum with quantities, check free shipping threshold (75 SAR)

Business Rule Engine

Apply 6 priority-based rules: Eastern assembly, HD routing, free shipping, tier pricing

Delivery Date

Calculate next business day in Asia/Riyadh timezone, skip Fridays, adjust for 2 PM cutoff

Response

Return service name, code, rate in halalas, and bilingual description to Shopify checkout

Project Details

Type	Shopify Carrier Service App
Version	2.0.0
Production Store	Al Nasser KSA
Hosting	Cloud (Serverless)
Currency	SAR (Saudi Riyal) — calculations in halalas
Repository	Private