Al-Shrouq Express
ALSHROUQ EXPRESS API v1.0
Developer Portal & API Reference | Al-Shrouq Express
🇸🇦
Quick Start

Overview & Server Environments

Welcome to the official Al-Shrouq API Documentation. Here you will find all official URLs, endpoints, and parameters needed to integrate with our logistics services across Saudi Arabia.

REST JSON APIs
< 150ms Latency
URL Token Auth
1 Configure API Token

Inject your account secret token into all code snippets and live interactive testing.

2 Choose Environment

Test safely on Sandbox (Staging) or dispatch real orders directly to live drivers.

3 Dispatch & Track Orders

Create orders with pickup coordinates, recipient location, and cash on delivery details.

Official Base URLs & Server Environments

All requests must be transmitted over HTTPS to the verified endpoints below.

Export Postman Collection
Production (Live) Live Drivers
https://alshrouqdelivery.com

Live production environment for executing actual delivery operations and driver dispatch.

Staging (Sandbox) Zero Billing
https://staging.alshrouqsse.org/

Sandbox environment for testing integrations, simulating order webhooks, and validating payload models.

Security

Authentication & Security

Authentication is performed by embedding your secret API token directly in the request URL path (Token in URL Path). No request is processed without a valid active token.

URL Path Token Pattern

Replace {API_TOKEN} with your merchant secret key provided by Al-Shrouq Express.

# Generic Path Specification:
POST https://alshrouqdelivery.com/api/integration/{API_TOKEN}/orders/create
# Resolved live request with your active session token:
POST https://alshrouqdelivery.com/api/integration/YOUR_API_TOKEN/orders/create
Security Best Practices & Token Protection
  • Never expose your secret API_TOKEN in client-side code, mobile frontend apps, or public Git repositories.
  • Always perform API requests from your secure backend servers (Node.js, PHP, Python, Java, etc.).
  • If you suspect a token leak, contact the Al-Shrouq Express developer operations team immediately to rotate it.
Official Core APIs

Core Direct Orders Lifecycle

Official core endpoints for creating, tracking, updating, and canceling delivery orders dispatched to the Al-Shrouq Express fleet.

Create New Order

Production
POST
/api/integration/{token}/orders/create
Required Scope: orders.create
Auth: URL Token

Request Headers

Accept: application/json
Content-Type: application/json

Body Parameters & Attributes

25 fields
branch_lat integer body
Required
Required if "branch_id" is missing
Example: 24.7136
branch_lng integer body
Required
Required if "branch_id" is missing
Example: 46.6753
branch_id integer body
Required
Required if "branch_lat" & "branch_lng" are missing
Example: 9999927651182
client_order_id string body
Optional
Example: "Test--0007"
value float body
Optional
Order Value
Example: 100.5
payment_type enum<integer> body
Required
Payment type
Allowed values
  • 1 COD (Cash on Delivery)
  • 2 Span Machine
  • 3 Paid
  • 4 AlshrouqPay
Example: 1= COD (Cash on Delivery) , 2= SPAN Machine , 3= Paid , 4= AlshrouqPay
preparation_time integer body
Optional
Example: 3
customer_lat float body
Optional
Example: 24.7136
customer_lng float body
Optional
Example: 46.6753
customer_phone string body
Required
Customer phone number
Example: 501234567
customer_name string body
Required
Customer name
Example: Ahmed
details string body
Optional
Order Details
Example: Extra sauce, no onions
customer_national_address string body
Optional
Customer national address
Example: test address
building_no string body
Optional
Example: 14
floor_no string body
Optional
Example: 16
apartment_no string body
Optional
Example: 3
customer_address string body
Optional
Example: ""
deliver_at string body
Optional
Example: "2029-05-20 14:00:00"
city integer body
Optional
Example: 3
ingr_branch_name string body
Optional
Example: ""
otp string body
Optional
Example: ""
pick_up_code string body
Optional
Example: ""
service_type integer body
Optional
weight float body
Optional
items_no float body
Optional

List of HTTP Statuses Code

Status Code Status Description
200 Success, Order Created successfully
Responses:
Order Created successfully 
{
  "order_id": 609077,
  "client_order_id": 12345,
  "customer_name": "Ahmed",
  "customer_phone": "501234567",
  "customer_lat": 24.7136,
  "customer_lng": 46.6753,
  "customer_address": null,
  "branch_name": "Tawera",
  "branch_id": 33,
  "fees": "0",
  "distance": "0",
  "status_id": "",
  "status_label": "Order created",
  "value": "100.5",
  "cod": "100.5",
  "payment_type_label": "Cash",
  "payment_type": 1,
  "details": "Extra sauce, no onions",
  "created_at": "2025-04-21 1:17 PM"
}

Cancel order

Production
POST
/api/integration/{token}/orders/cancel
Required Scope: orders.create
Auth: URL Token

Request Headers

Accept: application/json
Content-Type: application/json

Body Parameters & Attributes

2 fields
order_id string body
Required
Order number
Example: "5254700"
cancellation_reason string body
Optional
Cancel reason
Example: Outside Zone

List of HTTP Statuses Code

Status Code Status Description
200 Success, Order Cancelled successfully
200 Success, Order Picked Up Cancel Request Submitted
422 Error, Order not found or has already been cancelled or cannot be cancelled
Responses:
Order Cancelled successfully 
{
  "message": "ok , Order Cancelled"
}
Order Picked Up Cancel Request Submitted 
{
"message":"ok , Order Picked Up Cancel Request Submitted"

}
Order not found or has already been cancelled or cannot be cancelled 
{
  "error": "Order not found or has already been cancelled or cannot be cancelled."
}

Get Specific Order

Production
POST
/api/integration/{token}/orders/get
Required Scope: orders.create
Auth: URL Token

Request Headers

Accept: application/json
Content-Type: application/json

Body Parameters & Attributes

1 fields
order_id integer body
Required
Order number required
Example: 5254808

List of HTTP Statuses Code

Status Code Status Description
200 Success, HTTP 200
Responses:
HTTP 200 
{
  "data": {
    "order_id": 5254071,
    "client_order_id": "1231125",
    "customer_name": "Ahmed",
    "customer_phone": "501234567",
    "customer_lat": "24.7136",
    "customer_lng": "46.6753",
    "customer_address": "123 Main St",
    "branch_name": "Test alaraab",
    "branch_id": 9999927650791,
    "fees": "15",
    "distance": "0",
    "status_id": 22,
    "status_label": "Client Cancellation Request is being Proccessed",
    "value": "100.50",
    "tracking_url": "https://staging.alshrouqsse.org/tracking/eyJpdiI6Im1NcmxRRThzWVpWOHowWEwrQXYwQkE9PSIsInZhbHVlIjoiUzZLNVhCTUxxWERYL2w2b3UwVGtnMjF2aXlBYzdnaFU4emdXYkFQTnpXMnJsYTVYamxBWk1VSlcxREI1WVQxdiIsIm1hYyI6IjFjOWY1NmJhZjMyYmQ3NGQyY2I0OWIzMzZjODM4MmRmMGI2YmYzN2ZkNWM0MTM3MDRiNmM0YjMzMzIxOTliOGIiLCJ0YWciOiIifQ==",
    "cod": "115.5",
    "payment_type_label": "COD",
    "payment_type": 1,
    "details": "Extra sauce, no onions",
    "created_at": "2026-07-26 1:47 PM",
    "driver_accepted_time": null,
    "arrived_to_pickup_time": null,
    "picked_up_time": null,
    "arrived_to_dropoff_time": null,
    "delivered_at": null,
    "driver": null,
    "has_otp": false,
    "has_pickup_code": false,
    "pick_up_code": null,
    "otp": null,
    "invoice_url": "",
    "phone_code": null,
    "country_id": 2,
    "service_type_value": 0,
    "service_type_label": "On Demand",
    "current_status_timestamp": "2026-07-26T10:48:40.000000Z",
    "previous_status_timestamp": "2026-07-26T10:47:08.000000Z",
    "weight": "1.000",
    "eta": {
      "pickup": 0,
      "delivery": 0
    }
  }
}

Track order

Production
POST
/api/integration/{token}/orders/track-order
Required Scope: orders.create
Auth: URL Token

Request Headers

Accept: application/json
Content-Type: application/json

Body Parameters & Attributes

1 fields
order_id integer body
Required
Example: 5254808

List of HTTP Statuses Code

Status Code Status Description
200 Success, HTTP 200
Responses:
HTTP 200 
{
    "data": {
        "order_id": 5254983,
        "client_order_id": "Test-create-01",
        "branch": {
            "lat": "24.7136",
            "lng": "46.6753"
        },
        "customer": {
            "lat": "24.7136",
            "lng": "46.6753"
        },
        "driver": null,
        "eta": {
            "pickup": 0,
            "delivery": 0
        }
    }
}

Update specific order

Production
POST
/api/integration/{token}/orders/update
Required Scope: orders.create
Auth: URL Token

Request Headers

Accept: application/json
Content-Type: application/json

Body Parameters & Attributes

9 fields
order_id string body
Required
Order number
Example: 751156
details string body
Required
Order details
Example: Extra sauce, no onions
value float body
Required
Order value
Example: 100.5
payment_type integer body
Required
Payment type
Example: 1 , 2 , 3 , 4
customer_lat float body
Required
Example: 24.7136
customer_lng float body
Required
Example: 46.6753
customer_address string body
Required
Customer address
Example: 123 Main St
customer_phone string body
Required
Customer phone
Example: 501234567
customer_name string body
Required
Customer name
Example: Ahmed

List of HTTP Statuses Code

Status Code Status Description
200 Success, Order Updated successfully
Responses:
Order Updated successfully 
{
  "order_id": 5254072,
  "client_order_id": "123115",
  "customer_name": "Ahmed",
  "customer_phone": "501234567",
  "customer_lat": 24.7136,
  "customer_lng": 46.6753,
  "customer_address": "123 Main St",
  "branch_name": "Test alaraab",
  "branch_id": 9999927650791,
  "fees": "15",
  "distance": "0",
  "status_id": 23,
  "status_label": "Order Created",
  "value": "100.5",
  "tracking_url": "https://staging.alshrouqsse.org/tracking/eyJpdiI6Ik1aY0JtakgwZnI2R3FJbG9oNnBMT0E9PSIsInZhbHVlIjoiL1VMUnBmZDBpeUZKR0R5M2dUWDFBQ0RFOENZRDlRT3c1ZWhtM2lET2JLQitkaUVhWWNwU3dETmJmYkxKQmMrVSIsIm1hYyI6IjRmNjEwNjMwNjcwZTAwYWYxNzJiZmJlODMwMzA3MTM5OTdmZmNkOWIzMDY1M2U1NTdmZjRkOTRhMTYxYzkxYmIiLCJ0YWciOiIifQ==",
  "cod": "115.5",
  "payment_type_label": "COD",
  "payment_type": 1,
  "details": "Extra sauce, no onions",
  "created_at": "2026-07-26 1:49 PM",
  "driver_accepted_time": null,
  "arrived_to_pickup_time": null,
  "picked_up_time": null,
  "arrived_to_dropoff_time": null,
  "delivered_at": null,
  "driver": null,
  "has_otp": false,
  "has_pickup_code": false,
  "pick_up_code": null,
  "otp": null,
  "invoice_url": "",
  "phone_code": null,
  "country_id": 2,
  "service_type_value": 0,
  "service_type_label": "On Demand",
  "current_status_timestamp": "2026-07-26T10:49:23.000000Z",
  "previous_status_timestamp": "2026-07-26T10:49:11.000000Z",
  "weight": "1.000",
  "eta": {
    "pickup": 0,
    "delivery": 0
  }
}

Order rate

Production
POST
/api/integration/{{api_token}}/orders/get-rate
Required Scope: integration.create
Auth: URL Token

Request Headers

Accept: application/json
Content-Type: application/json

Body Parameters & Attributes

3 fields
pickup_id integer body
Required
Branch id
Example: 9999927650903
delivery_lat float body
Required
Example: 24.75
delivery_lng float body
Required
Example: 46.70

List of HTTP Statuses Code

Status Code Status Description
200 Success, Rate retrieved successfully
Responses:
Rate retrieved successfully 
{
    "status": true,
    "message": "Rate retrieved successfully",
    "data": {
        "distance": 13.11,
        "fees": 15,
        "extra_fees": 3.11,
        "total_fees": 18.11
    }
}

Cancel reason

Production
GET
/api/integration/{token}/orders/cancel-reasons
Required Scope: orders.read
Auth: URL Token

Request Headers

Accept: application/json

List of HTTP Statuses Code

Status Code Status Description
200 Success, Cancel reasons retrieved successfully
Responses:
Cancel reasons retrieved successfully 
{
  "status": true,
  "message": "Cancel reasons retrieved successfully",
  "data": [
    {
      "id": 4,
      "name": "Customer Not Responding"
    },
    {
      "id": 11,
      "name": "Branch cancel orders"
    },
    {
      "id": 12,
      "name": "RTO"
    }
  ]
}

Branches

Create new branch

Production
POST
/api/integration/{token}/branches/create
Required Scope: branches.create
Auth: URL Token

Request Headers

Accept: application/json
Content-Type: application/json

Body Parameters & Attributes

12 fields
branch_lat float body
Required
Example: 24.7136
branch_ln float body
Required
Example: 46.6753
city string body
Optional
Example: 2
ingr_branch_name string body
Required
Example: test
phone_number string body
Optional
Branch Phone number
Example: 0512345678
street string body
Optional
Street name
Example: King Fahd Road
landmark string body
Optional
Landmark
Example: Near Kingdom Tower
building string body
Optional
Building
Example: 12B
floor string body
Optional
Floor number
Example: 3
apartment string body
Optional
Apartment number
Example: 301
description string body
Optional
Description
Example: Main branch
logo_url string body
Optional
Branch logo
Example: https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png

List of HTTP Statuses Code

Status Code Status Description
200 Success, Branch created successfully
Responses:
Branch created successfully 
{
    "status": true,
    "message": "Branch created successfully",
    "data": {
        "branch": {
            "id": 9999927651212,
            "name": "test 3",
            "client_branch_name": "test",
            "displayed_name": "test",
            "logo": "https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png",
            "custom_id": null,
            "phone_number": "0512345678",
            "lat": 24.7135999999999995679900166578590869903564453125,
            "lng": 46.67530000000000001136868377216160297393798828125,
            "city": "Riyadh",
            "city_id": 2,
            "country": "Saudi Arabia",
            "country_id": 2,
            "street": "King Fahd Road",
            "landmark": "Near Kingdom Tower",
            "building": "12B",
            "floor": "3",
            "apartment": "301",
            "description": "Main branch",
            "is_active": true
        }
    }
}

Branch list

Production
GET
/api/integration/{token}/branches
Required Scope: branches.read
Auth: URL Token

Request Headers

Accept: application/json

List of HTTP Statuses Code

Status Code Status Description
200 Success, Branch retrieved successfully
Responses:
Branch retrieved successfully 
{
  "status": true,
  "message": "Branches retrieved successfully",
  "data": {
    "branches": [
     {
  "id": 9999927651208,
            "name": "test 12",
            "client_branch_name": "test",
            "displayed_name": "test",
            "logo": "https://alshrouqdelivery.b-cdn.net/https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png",
            "custom_id": "BR-001",
            "phone_number": "0512345678",
            "lat": 24.7135999999999995679900166578590869903564453125,
            "lng": 46.67530000000000001136868377216160297393798828125,
            "city": "Riyadh",
            "city_id": 2,
            "country": "Saudi Arabia",
            "country_id": 2,
            "street": "King Fahd Road",
            "landmark": "Near Kingdom Tower",
            "building": "12B",
            "floor": "3",
            "apartment": "301",
            "description": "Main branch",
            "is_active": true
},
 {
  "id": 9999927651209,
            "name": "test 13",
            "client_branch_name": "test",
            "displayed_name": "test",
            "logo": "https://alshrouqdelivery.b-cdn.net/https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png",
            "custom_id": "BR-001",
            "phone_number": "0512345678",
            "lat": 24.7135999999999995679900166578590869903564453125,
            "lng": 46.67530000000000001136868377216160297393798828125,
            "city": "Riyadh",
            "city_id": 2,
            "country": "Saudi Arabia",
            "country_id": 2,
            "street": "King Fahd Road",
            "landmark": "Near Kingdom Tower",
            "building": "12B",
            "floor": "3",
            "apartment": "301",
            "description": "Main branch",
            "is_active": true
},
 {
  "id": 99999276512010,
            "name": "test 14",
            "client_branch_name": "test",
            "displayed_name": "test",
            "logo": "https://alshrouqdelivery.b-cdn.net/https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png",
            "custom_id": "BR-001",
            "phone_number": "0512345678",
            "lat": 24.7135999999999995679900166578590869903564453125,
            "lng": 46.67530000000000001136868377216160297393798828125,
            "city": "Riyadh",
            "city_id": 2,
            "country": "Saudi Arabia",
            "country_id": 2,
            "street": "King Fahd Road",
            "landmark": "Near Kingdom Tower",
            "building": "12B",
            "floor": "3",
            "apartment": "301",
            "description": "Main branch",
            "is_active": true
},
 {
  "id": 99999276512011,
            "name": "test 15",
            "client_branch_name": "test",
            "displayed_name": "test",
            "logo": "https://alshrouqdelivery.b-cdn.net/https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png",
            "custom_id": "BR-001",
            "phone_number": "0512345678",
            "lat": 24.7135999999999995679900166578590869903564453125,
            "lng": 46.67530000000000001136868377216160297393798828125,
            "city": "Riyadh",
            "city_id": 2,
            "country": "Saudi Arabia",
            "country_id": 2,
            "street": "King Fahd Road",
            "landmark": "Near Kingdom Tower",
            "building": "12B",
            "floor": "3",
            "apartment": "301",
            "description": "Main branch",
            "is_active": true
},

    ],
    "pagination": {
      "current_page": 1,
      "last_page": 3,
      "per_page": 10,
      "total": 30,
      "next_page_url": "https://staging.alshrouqsse.org/api/integration/h0v6Xb9pwZvuTQL1CY0V3dXbfygQkO06Z277ojUYpZpqKL4CXP44HIjOmpIXRdFMH5mXOVgrmv6DXNnI/branches?page=2",
      "prev_page_url": null
    }
  }
}

Cities list

Production
POST
/api/integration/{token}/cities?country_id=2
Required Scope: cities?country_id=2.create
Auth: URL Token

Request Headers

Accept: application/json
Content-Type: application/json

List of HTTP Statuses Code

Status Code Status Description
200 Success, HTTP 200
Responses:
HTTP 200 
{
    "id": 2,
    "name": "Riyadh",
    "lat": "24.714061319485616",
    "lng": "46.67583405296055",
    "country": "Saudi Arabia",
    "spl_id": "3",
    "spl_name": "RIYADH",
    "spl_region_id": "1",
    "distance_km": null
  },
  {
    "id": 3,
    "name": "Jeddah",
    "lat": "21.529183147129466",
    "lng": "39.17986254008007",
    "country": "Saudi Arabia",
    "spl_id": "18",
    "spl_name": "JEDDAH",
    "spl_region_id": "2",
    "distance_km": null
  }
Realtime Callbacks

Outbound Webhooks

Al-Shrouq Express sends outbound JSON POST notifications to the callback URL you configure in the dashboard when order status or driver location changes. Your server must respond with HTTP 200. There is no HMAC signature; an optional Authorization header uses the token you stored on the webhook.

Order Created Webhook

Outbound
Merchant Callback
POST
https://{your-domain}/api/webhooks/HandleAlShrouqWebhook

Al-Shrouq posts this notification to each merchant's own webhook URL (every client registers a different callback in the dashboard) — not to Al-Shrouq servers and not a fixed base URL. Placeholder example: https://{your-domain}/api/webhooks/HandleAlShrouqWebhook. The Request Body is the data shape we send. Authorization = the token saved on the webhook settings. Whatever the merchant server returns is logged as-is.

Required Scope: https:.create
Auth: URL Token

Request Headers

Accept: application/json
Content-Type: application/json

Body Parameters & Attributes

17 fields
Content-Type string header
Optional
Content type we send: application/json
Example: application/json
Authorization string header
Optional
Auth key we send in the header. Value = the token field saved on your webhook settings (example: Bearer abc123). If no token is configured, this header is omitted.
Example: Bearer YOUR_WEBHOOK_TOKEN
order_id integer body
Optional
Al-Shrouq internal order ID
Example: 84997
client_order_id string body
Optional
Merchant order reference
Example: ORD-98432
status_id integer body
Optional
Order status code (see Order Statuses section)
Example: 1
status_label string body
Optional
Human-readable status label
Example: Order created
customer_name string body
Optional
Customer name
Example: Ahmed
customer_phone string body
Optional
Customer phone
Example: 0501234567
customer_lat string body
Optional
Dropoff latitude
Example: 24.7136
customer_lng string body
Optional
Dropoff longitude
Example: 46.6753
branch_id integer body
Optional
Pickup branch ID
Example: 12
fees string body
Optional
Delivery fees
Example: 13
value string body
Optional
Order value
Example: 100.00
cod string body
Optional
Cash on delivery amount
Example: 115
tracking_url string body
Optional
Live tracking URL
Example: https://alshrouqexpress.com/tracking/84997
driver object body
Optional
Driver object (often null on create)
Example: null
eta object body
Optional
ETA in minutes for pickup and delivery
Example: {"pickup":12,"delivery":28}

List of HTTP Statuses Code

Status Code Status Description
200 Success, This is only an example. Any response body returned by your server is logged in our webhook logs. We do not validate the schema and do not depend on it for processing.
Responses:
Example merchant response (logged as-is) This is only an example. Any response body returned by your server is logged in our webhook logs. We do not validate the schema and do not depend on it for processing. 
{
    "ok": Success
}

Order Statuses

List of Available Order Statuses

Status ID Status Description
1 Order Created
2 Pending Driver Acceptance
17 Driver Accept order
16 Arrive to pickup
6 Order Pickedup
8 Arrive to dropoff
9 Order Delivered
10 Order Cancelled
21 Order Cancellation is being Processed
23 Order Created (is used for internal process in Alshrouq system)
Error Standards

HTTP Status Codes & Error Handling

Complete list of standard HTTP response status codes and error handling recommendations.

Status Code Meaning Description & Recommended Action
503 System closed System closed
422 Error Validation errors , example: { "error": "The branch lat field is required when branch id is not present. (and 1 more error)" }
401 Error Unauthorized error, Invaild token, example: { "message": "Invalid token" }
401 Error Unauthorized error, unactive user, example: { "message": "Unactive user" }
422 Error Branch not found
422 Error Unactive branch
404 Error The order already exists
201 Success order created
Standard JSON Error Response Schema 422 Example 
{
  "status": false,
  "message": "Validation error in request parameters.",
  "errors": {
    "branch_id": ["The branch_id field is required when coordinates are not provided."],
    "payment_type": ["The payment_type must be either 1 (Cash) or 2 (Card Machine)."]
  }
}
Al-Shrouq Express Developer Portal v1.0 • Live
OpenAPI Spec • Postman Collection