On This Page ×

📋

↑

📦 ShippingEyes Ecosystem Official Website 🌐

Public API V1 — Developer Guide

Unified Integration Gateway for the ShippingEyes Ecosystem

Version 1.0 — Secure Server-to-Server Authentication — 23 Endpoints

99.9%

Platform Uptime

<120ms

Avg Response

1M+

Monthly Req

🔄 Integration Architecture

Data Integration Lifecycle

🛒

Your Ecommerce

Your store or custom integration platform

WooCommerce Shopify EasyOrders Salla Zid

🔌

Public API V1

Secure gateway with multi-layer middleware

Auth Validation Rate Limit

👁️

Shipping Eyes Technology

Enterprise-Grade Logistics ERP & Financial Intelligence Engine

Neural Routing Deep Logistics ERP Ai Engine

🛠️ Developer Sandbox Settings

🌐 API Base URL:

(All cURL, PHP, and JS examples update in real-time)

📡 Live Endpoint Preview:

                            https://your-domain.com/api/v1/public/...

📋 Public API V1 — Endpoints Summary (23 endpoints)

▼

Method	Endpoint	Scope	Description
GET	/api/v1/public/locations/countries	shipping:read	List delivery countries
GET	/api/v1/public/locations/routes	shipping:read	List all delivery routes
GET	/api/v1/public/locations/routes/country/{id}	shipping:read	List routes by country
GET	/api/v1/public/locations/cities	shipping:read	List all delivery cities
GET	/api/v1/public/locations/cities/country/{id}	shipping:read	List cities by country
GET	/api/v1/public/locations/cities/route/{id}	shipping:read	List cities by route
GET	/api/v1/public/locations/places	shipping:read	List all delivery places
GET	/api/v1/public/locations/places/city/{id}	shipping:read	List places by city
GET	/api/v1/public/locations/districts	shipping:read	List all delivery districts
GET	/api/v1/public/locations/districts/place/{id}	shipping:read	List districts by place
GET	/api/v1/public/shipping/prices	shipping:read	Get shipping prices
GET	/api/v1/public/shipping/services	shipping:read	Get shipping services
GET	/api/v1/public/shipping/config	shipping:read	Get configuration for order creation
GET	/api/v1/public/shipping/config/statuses	shipping:read	Get available order statuses
POST	/api/v1/public/orders/create	orders:create	Create new order
POST	/api/v1/public/orders/update	orders:create	Update existing order
DELETE	/api/v1/public/orders/delete/{order_id}	orders:create	Delete order
GET	/api/v1/public/orders/list/{status}	orders:read	List orders by status
GET	/api/v1/public/orders/info/{order_id}	orders:read	Get order details
POST	/api/v1/public/orders/search	orders:read	Search and Query orders (Ultra High Performance)
GET	/api/v1/public/orders/tracking/{order_id}	tracking:read	Get order tracking
POST	/api/v1/public/orders/tracking/bulk	tracking:read	Bulk order tracking
POST	/api/v1/public/orders/followups/bulk	orders:read	Bulk order followups and history

🚀 Quick Start Guide

Download Postman Collection

🌐 Base URL

Production: https://your-domain.com/api/v1/public

Development: {APP_URL}/api/v1/public

⚠️ Important: This API is for public integrations only (WooCommerce, Shopify, Custom CRMs/ERPs). It uses API Key + Secret authentication — NOT Bearer tokens. All requests must be over HTTPS.

🔑 Authentication — API Key + Secret

Every request must include two custom headers:

Header	Type	Required	Description
ShippingEyes-Api-Key	string	✅ Yes	Your public API key (starts with `se_live_` or `se_test_`)
ShippingEyes-Api-Secret	string	✅ Yes	Your private API secret (64 characters). Never expose publicly.
ShippingEyes-Api-Nonce	string	⚠️ Conditional	Mandatory for POST, PUT, DELETE. Optional for GET. A unique per-request UUID to prevent replay attacks.

📝 Complete Example — Create Order

📝 cURL Example

curl -X POST https://your-domain.com/api/v1/public/orders/create \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "ShippingEyes-Api-Key: se_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678" \
  -H "ShippingEyes-Api-Secret: your_64_char_secret_here..." \
  -d '{
    "shipping_service": "srv8gJ",
    "shipment_info": {
      "pieces": 1,
      "description": "Electronics package",
      "order_type": 1,
      "delivery_type": 1,
      "allow_opening": 0,
      "breakable": 0
    },
    "recipient": {
      "name": "Ahmed Hassan",
      "phone": "0910000000",
      "to_city": "lejRej",
      "to_place": "mep2bM",
      "address": "123 Main Street"
    },
    "financial_info": {
      "amount": 250,
      "amount_type": 1,
      "delivery_cost": 50,
      "cod": 300,
      "shipping_cost_type": 1
    }
  }'

🐘 PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://your-domain.com/api/v1/public/orders/create', [
    'headers' => [
        'ShippingEyes-Api-Key'    => 'se_live_...',
        'ShippingEyes-Api-Secret' => 'your_secret...',
        'Accept'       => 'application/json',
    ],
    'json' => [
        'shipping_service' => 'srv8gJ',
        'shipment_info' => [
            'pieces' => 1,
            'description' => 'Electronics package',
            'order_type' => 1,
            'delivery_type' => 1
        ],
        'recipient' => [
            'name' => 'Ahmed Hassan',
            'phone' => '0910000000',
            'to_city' => 'lejRej',
            'to_place' => 'mep2bM'
        ],
        'financial_info' => [
            'amount' => 250,
            'amount_type' => 1
        ]
    ]
]);

$data = json_decode($response->getBody(), true);

📦 Node.js (Fetch)

const fetch = require('node-fetch');

const createOrder = async () => {
    const response = await fetch('https://your-domain.com/api/v1/public/orders/create', {
        method: 'POST',
        headers: {
            'ShippingEyes-Api-Key': 'se_live_...',
            'ShippingEyes-Api-Secret': 'your_secret...',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        },
        body: JSON.stringify({
            shipping_service: 'srv8gJ',
            shipment_info: { pieces: 1, order_type: 1 },
            recipient: { name: 'Ahmed Hassan', phone: '0910000000', to_city: 'lejRej' },
            financial_info: { amount: 250, amount_type: 1 }
        })
    });
    const data = await response.json();
    console.log(data);
};

✅ Success Response

{
  "status": 200,
  "message": "success",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-string",
    "rate_limit": {
      "limit": 30,
      "unit": "requests per minute",
      "note": "Standard creation quota."
    }
  },
  "order_id": "ord4cN",
  "order_snum": 10042
}

📱 Required Headers for All Requests

Header	Value	Required
Content-Type	`application/json`	POST requests
Accept	`application/json`	All requests
ShippingEyes-Api-Key	Your API key	✅ Always
ShippingEyes-Api-Secret	Your API secret	✅ Always

📌 ID Format Convention

ℹ️ All IDs are encoded strings (e.g. "lejRej", "mep2bM"). Never assume IDs are numeric or sequential. Treat them as opaque strings.

🔒 Security Layers (6-Layer Middleware Stack)

#	Layer	Purpose
1	HTTPS Enforcement	Blocks all non-HTTPS requests
2	Rate Limiting	Dynamic quotas (3/5min to 60/min) based on endpoint sensitivity
3	API Key Auth	Validates key + secret + IP whitelist
4	Scope Check	Verifies endpoint permission
5	Response Filter	Strips sensitive internal fields
6	Audit Log	Logs every request for forensics

📌 Order Status Reference

Use these status keys to interpret the status_key field in responses and to filter the view-orders-list endpoint.

Key	Status Name	Description	Workflow Stage
1	New	Order created but not yet processed	Merchant Office
2	Processing	Order confirmed and being prepared	Warehouse
10	Picked Up	Package collected from merchant	In Transit
20	At Branch	Package arrived at destination branch	Local Sorting
22	Out for Delivery	Delegate is delivering to customer	Final Mile
30	Delivered	Package delivered and paid	Completed
40	Returned	Order rejected/returned to merchant	Closed
50	Cancelled	Order cancelled before pickup	Closed

🔢 Pagination Standard

All list endpoints use a standard metadata object to handle large data sets:

{
  "data": [...],
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "rate_limit": {
      "limit": 60,
      "unit": "requests per minute",
      "note": "Real-time monitoring quota. No-cache enforced."
    },
    "current_page": 1,
    "last_page": 12,
    "per_page": 20,
    "total": 235,
    "next_page_url": "...?page=2",
    "prev_page_url": null
  }
}

🔑 Authentication

Headers: ShippingEyes-Api-Key + ShippingEyes-Api-Secret

How Authentication Works

Unlike the mobile app API that uses Bearer tokens (login + password), the Public API uses pre-generated API credentials:

1. Obtain Your Credentials

Your API Key and Secret are generated by the system administrator. You receive them once:

🔑 Your Credentials (shown only once)

{
  "ShippingEyes-Api-Key":    "se_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678",
  "ShippingEyes-Api-Secret": "x9K2mP7qR4tL8wN3vB6jH1dF5gY0sA..."
}

2. Include in Every Request

📝 Headers

ShippingEyes-Api-Key: se_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678
ShippingEyes-Api-Secret: x9K2mP7qR4tL8wN3vB6jH1dF5gY0sA...

3. Authentication Errors

❌ 401 — Missing Credentials

{
  "status": "error",
  "message": "authentication_required",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-string",
    "rate_limit": {
      "limit": 60,
      "unit": "requests per minute",
      "note": "Standard authentication quota."
    }
  }
}

❌ 401 — Invalid Credentials

{
  "status": "error",
  "message": "invalid_credentials",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-string",
    "rate_limit": {
      "limit": 60,
      "unit": "requests per minute",
      "note": "Standard authentication quota."
    }
  }
}

4. Implementation Examples

Integrate ShippingEyes into your stack using these boilerplate examples:

cURL

PHP

Node.js

Python

Shell / cURL

curl -X GET "https://api.shippingeyes.com/v1/orders" \
     -H "ShippingEyes-Api-Key: YOUR_API_KEY" \
     -H "ShippingEyes-Api-Secret: YOUR_API_SECRET" \
     -H "Accept: application/json"

PHP (cURL)

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.shippingeyes.com/v1/orders");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "ShippingEyes-Api-Key: YOUR_API_KEY",
    "ShippingEyes-Api-Secret: YOUR_API_SECRET",
    "Accept: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

Node.js (axios)

const axios = require('axios');

axios.get('https://api.shippingeyes.com/v1/orders', {
    headers: {
        'ShippingEyes-Api-Key': 'YOUR_API_KEY',
        'ShippingEyes-Api-Secret': 'YOUR_API_SECRET',
        'Accept': 'application/json'
    }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

Python (requests)

import requests

url = "https://api.shippingeyes.com/v1/orders"
headers = {
    "ShippingEyes-Api-Key": "YOUR_API_KEY",
    "ShippingEyes-Api-Secret": "YOUR_API_SECRET",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

❌ 403 — IP Not Allowed

{
  "status": "error",
  "message": "ip_forbidden",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-string",
    "rate_limit": {
      "limit": 60,
      "unit": "requests per minute",
      "note": "Standard authentication quota."
    }
  }
}

❌ 429 — Quota Exceeded

{
  "status": "error",
  "message": "too_many_requests",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-string",
    "rate_limit": {
      "limit": 60,
      "unit": "requests per minute",
      "note": "Quota exceeded. Check headers for retry time."
    }
  }
}

🔐 Security Notes:

Never expose your API Secret in client-side code, Git repos, or public URLs
IP Whitelist: If configured, only requests from allowed IPs will be accepted
Auto-Disable: After multiple consecutive failed secret attempts, the key is automatically disabled
Rotation: Keys should be rotated periodically as a security best practice

🧪 Test Environment (Test Mode)

We provide a safe sandbox environment to test your integration without affecting live data or real balances.

How to use Test Mode:

Request a Test API Key from the system administrator (keys starting with se_test_).
Use the exact same endpoints and URLs as production.
When using a se_test_ key, orders are fully validated and saved, but they are flagged internally as test orders. They will not trigger dispatchers, billing, or real logistics workflows.

⚡ Webhooks & Real-time Notifications

Asynchronous Push

Webhooks allow your application to receive real-time notifications about events in the ShippingEyes ecosystem. Instead of polling the API, we push data to your server as soon as an event occurs.

📦

order.created

Sync inventory the moment an order hits our system.

🚚

order.dispatched

Notify your customers immediately when the courier leaves.

✅

order.delivered

Trigger automated reviews or loyalty points instantly.

🔄

order.updated

Real-time tracking for every step of the journey.

🚀 Marketing Edge: Why Webhooks?

Webhooks transform your integration from a "pull" system to an Active Intelligence Engine. Instead of wasting server resources asking "Is it delivered yet?", ShippingEyes shouts "It's delivered!" the millisecond it happens. This enables you to provide an Amazon-like experience to your customers with zero latency.

🔐 Security & Integrity: All webhook requests are signed with an HMAC-SHA256 signature based on your Webhook Secret. You must verify this signature to ensure the request originated from ShippingEyes.

📑 HTTP Headers

Every webhook POST request includes the following headers for identification and security:

Header	Value Example	Description
ShippingEyes-Webhook-Signature	sha256=a1b2c3...	HMAC-SHA256 signature for payload verification.
ShippingEyes-Webhook-Event	order.status_updated	The type of event being sent.
ShippingEyes-Webhook-ID	uuid-string	Unique identifier for this specific delivery attempt.
ShippingEyes-Webhook-Timestamp	1714838400	Unix timestamp of when the event was generated.

🛠️ Webhook Delivery Architecture

Our webhook engine is built for reliability and high performance:

Queue-Based: Events are dispatched to a background queue to ensure instant response times.
Retry Policy: If your server is down or returns a non-2xx status, we automatically retry the delivery multiple times using an exponential backoff strategy.
Auto-Disable: To protect our system, webhooks that repeatedly fail are automatically disabled. Ensure your endpoint is stable and returns a 2xx status promptly.

🔐 Verifying the Signature

Every webhook request includes a ShippingEyes-Webhook-Signature header. This is a sha256 hash of the raw JSON body signed with your Webhook Secret.

🐘 PHP Verification

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_SHIPPINGEYES_WEBHOOK_SIGNATURE'] ?? '';
$secret = 'your_webhook_secret_here';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (hash_equals($expected, $signature)) {
    // ✅ Valid request
    $data = json_decode($payload, true);
} else {
    // ❌ Invalid signature
    http_response_code(401);
}

📦 Node.js (Express)

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
    const signature = req.headers['shippingeyes-webhook-signature'];
    const secret = 'your_webhook_secret_here';
    const payload = JSON.stringify(req.body);

    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');

    // Timing-safe comparison
    const signatureBuffer = Buffer.from(signature || '', 'utf8');
    const expectedBuffer = Buffer.from(expected, 'utf8');

    if (signatureBuffer.length === expectedBuffer.length && 
        crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) {
        res.status(200).send('OK');
    } else {
        res.status(401).send('Unauthorized');
    }
});

📅 Event Catalog

The following events are currently supported by the ShippingEyes platform:

🔔 order.status_updated

Triggered whenever an order's status changes (e.g., from "New" to "Out for Delivery").

📦 Payload Example

{
  "event": "order.status_updated",
  "timestamp": 1714838400,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "order_snum": 10042,
    "order_status": 22,
    "status_name": "Out for Delivery",
    "updated_at": "2026-05-04 15:30:00"
  }
}

💬 order.followup_recorded

Triggered when a new followup or note is added to an order by the delivery agent or customer service.

📦 Payload Example

{
  "event": "order.followup_recorded",
  "timestamp": 1714838400,
  "uuid": "660f9500-f39c-52d5-b817-557766551111",
  "data": {
    "order_snum": 10042,
    "followup_type": "followup",
    "notes": "Customer requested delivery after 4 PM",
    "created_at": "2026-05-04 16:00:00"
  }
}

💰 catalog.shipping_pricing_updated

Triggered when shipping prices in your assigned price package are updated. Useful for syncing prices with your ecommerce store.

📦 Payload Example

{
  "event": "catalog.shipping_pricing_updated",
  "timestamp": 1714838400,
  "uuid": "770g0600-g40d-63e6-c928-668877662222",
  "data": {
    "price_package_id": "pkg9jL",
    "message": "Shipping prices have been updated",
    "updated_at": "2026-05-04T16:30:00Z"
  }
}

⚙️ platform.configuration_updated

Triggered when global shipment settings (e.g., allowed order types, closing times) are modified by the system.

📦 Payload Example

{
  "event": "platform.configuration_updated",
  "timestamp": 1714838400,
  "uuid": "880h1700-h51e-74f7-d039-779988773333",
  "data": {
    "message": "Orders creation settings have been updated",
    "updated_at": "2026-05-04T16:30:00Z"
  }
}

📍 Delivery Locations

Scope: shipping:read

📌 General Response Details (All Locations Endpoints)
Response Structure: Every successful response follows a standardized format containing a meta object with a strict rate_limit of 20 requests per 6 hours.

💡 No Data Behavior: If no records match your query, the API returns a 200 OK status with "status": "no_data" and "message": "No records found".

ℹ️ 200 — No Records Found (Example)

{
  "status": "no_data",
  "message": "No records found",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "data": []
}

GET /api/v1/public/locations/countries

Retrieve the global collection of supported delivery countries.

📐 Resource Schema: Country

Field	Type	Nullable	Description
country_id	string	❌	Unique resource identifier for the country entity.
name	string	❌	Country designation in Arabic.
name_en	string	✅	Country designation in English (where applicable).
cities_count	int	✅	Total count of associated city resources.
routes_count	int	✅	Total count of active delivery route resources.

✅ 200 — Success

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-29T18:52:36Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 20,
      "unit": "requests per 6 hours",
      "note": "Maximum protection limit. Please cache location data on your server (Recommended TTL: 20 min)."
    }
  },
  "data": [
    {
      "country_id": "cRy1xZ",
      "name": "ليبيا",
      "name_en": "Libya",
      "cities_count": 25,
      "routes_count": 5
    }
  ]
}

GET /api/v1/public/locations/routes

Retrieve the master collection of active delivery routes.

📐 Resource Schema: Route

Field	Type	Nullable	Description
route_id	string	❌	Unique resource identifier for the route entity.
name	string	❌	Route designation in Arabic.
name_en	string	✅	Route designation in English.
cities_count	int	✅	Total count of city resources mapped to this route.

✅ 200 — Success

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-here",
    "rate_limit": {
      "limit": 20,
      "unit": "requests per 6 hours",
      "note": "Maximum protection limit. Please cache location data on your server (Recommended TTL: 20 min)."
    }
  },
  "data": [
    {
      "route_id": "rtE8kL",
      "name": "خط طرابلس",
      "name_en": "Tripoli Route",
      "cities_count": 5
    }
  ]
}

GET /api/v1/public/locations/routes/country/{id}

Fetch delivery routes associated with a specific country resource.

Parameter	Type	In	Description
id	string	URL	Unique identifier for the country resource.

📐 Resource Schema: Route

Field	Type	Nullable	Description
route_id	string	❌	Unique resource identifier for the route entity.
name	string	❌	Route designation in Arabic.
name_en	string	✅	Route designation in English.
cities_count	int	✅	Total count of city resources mapped to this route.

✅ 200 — Success

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-here",
    "rate_limit": {
      "limit": 20,
      "unit": "requests per 6 hours",
      "note": "Maximum protection limit. Please cache location data on your server (Recommended TTL: 20 min)."
    }
  },
  "data": [
    {
      "route_id": "rtE8kL",
      "name": "خط طرابلس",
      "name_en": "Tripoli Route",
      "cities_count": 5
    }
  ]
}

GET /api/v1/public/locations/cities

Retrieve the global collection of supported delivery cities.

📐 Resource Schema: City

Field	Type	Nullable	Description
city_id	string	❌	Unique resource identifier for the city entity.
code	string	✅	Internal standardized city code.
name	string	❌	City designation in Arabic.
name_en	string	✅	City designation in English.
delivery_days	int	✅	Estimated temporal constraint (transit time) in days.
places_count	int	✅	Total count of zones/places associated with this city.

✅ 200 — Success

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-here",
    "rate_limit": {
      "limit": 20,
      "unit": "requests per 6 hours",
      "note": "Maximum protection limit. Please cache location data on your server (Recommended TTL: 20 min)."
    }
  },
  "data": [
    {
      "city_id": "lejRej",
      "code": "TRP",
      "name": "طرابلس",
      "name_en": "Tripoli",
      "delivery_days": 1,
      "places_count": 25
    }
  ]
}

GET /api/v1/public/locations/cities/country/{id}

Fetch delivery cities associated with a specific country resource.

Parameter	Type	In	Description
id	string	URL	Unique identifier for the country resource.

📐 Resource Schema: City

Field	Type	Nullable	Description
city_id	string	❌	Unique resource identifier for the city entity.
code	string	✅	Internal standardized city code.
name	string	❌	City designation in Arabic.
name_en	string	✅	City designation in English.
delivery_days	int	✅	Estimated temporal constraint (transit time) in days.
places_count	int	✅	Total count of zones/places associated with this city.

✅ 200 — Success

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-here",
    "rate_limit": {
      "limit": 20,
      "unit": "requests per 6 hours",
      "note": "Maximum protection limit. Please cache location data on your server (Recommended TTL: 20 min)."
    }
  },
  "data": [
    {
      "city_id": "lejRej",
      "code": "TRP",
      "name": "طرابلس",
      "name_en": "Tripoli",
      "delivery_days": 1,
      "places_count": 25
    }
  ]
}

GET /api/v1/public/locations/cities/route/{id}

Fetch delivery cities associated with a specific route resource.

Parameter	Type	In	Description
id	string	URL	Unique identifier for the route resource.

📐 Resource Schema: City

Field	Type	Nullable	Description
city_id	string	❌	Unique resource identifier for the city entity.
code	string	✅	Internal standardized city code.
name	string	❌	City designation in Arabic.
name_en	string	✅	City designation in English.
delivery_days	int	✅	Estimated temporal constraint (transit time) in days.
places_count	int	✅	Total count of zones/places associated with this city.

GET /api/v1/public/locations/places

Retrieve the collection of all supported delivery places/zones.

📐 Resource Schema: Zone (Place)

Field	Type	Nullable	Description
city_id	string	❌	Unique identifier for the parent city entity.
place_id	string	❌	Unique resource identifier for the delivery zone.
code	string	✅	Standardized regional zone code.
name	string	❌	Zone designation in Arabic.
name_en	string	✅	Zone designation in English.
districts_count	int	✅	Total count of micro-districts within this zone.
delivery_days	int	✅	Estimated temporal constraint (transit time) for this specific zone.

✅ 200 — Success

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-here",
    "rate_limit": {
      "limit": 20,
      "unit": "requests per 6 hours",
      "note": "Maximum protection limit. Please cache location data on your server (Recommended TTL: 20 min)."
    }
  },
  "data": [
    {
      "city_id": "lejRej",
      "place_id": "mep2bM",
      "code": "TJR",
      "name": "Tajoura",
      "name_en": "Tajoura",
      "districts_count": 8,
      "delivery_days": 1
    }
  ]
}

GET /api/v1/public/locations/places/city/{id}

Fetch delivery places associated with a specific city resource.

Parameter	Type	In	Description
id	string	URL	Unique identifier for the city resource.

📐 Resource Schema: Zone (Place)

Field	Type	Nullable	Description
city_id	string	❌	Unique identifier for the parent city entity.
place_id	string	❌	Unique resource identifier for the delivery zone.
code	string	✅	Standardized regional zone code.
name	string	❌	Zone designation in Arabic.
name_en	string	✅	Zone designation in English.
districts_count	int	✅	Total count of micro-districts within this zone.
delivery_days	int	✅	Estimated temporal constraint (transit time) for this specific zone.

✅ 200 — Success

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-here",
    "rate_limit": {
      "limit": 20,
      "unit": "requests per 6 hours",
      "note": "Maximum protection limit. Please cache location data on your server (Recommended TTL: 20 min)."
    }
  },
  "data": [
    {
      "city_id": "lejRej",
      "place_id": "mep2bM",
      "code": "TJR",
      "name": "Tajoura",
      "name_en": "Tajoura",
      "districts_count": 8,
      "delivery_days": 1
    }
  ]
}

GET /api/v1/public/locations/districts

Retrieve the master collection of delivery districts.

📐 Resource Schema: District

Field	Type	Nullable	Description
district_id	string	❌	Unique resource identifier for the district entity.
place_id	string	❌	Unique identifier for the parent zone entity.
name	string	❌	District designation in Arabic.
name_en	string	✅	District designation in English.

✅ 200 — Success

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-here",
    "rate_limit": {
      "limit": 20,
      "unit": "requests per 6 hours",
      "note": "Maximum protection limit. Please cache location data on your server (Recommended TTL: 20 min)."
    }
  },
  "data": [
    {
      "district_id": "dst5kP",
      "place_id": "mep2bM",
      "name": "Al-Nasr District",
      "name_en": "Al-Nasr District"
    }
  ]
}

GET /api/v1/public/locations/districts/place/{id}

Fetch districts associated with a specific delivery place resource.

Parameter	Type	In	Description
id	string	URL	Unique identifier for the place resource.

📐 Resource Schema: District

Field	Type	Nullable	Description
district_id	string	❌	Unique resource identifier for the district entity.
place_id	string	❌	Unique identifier for the parent zone entity.
name	string	❌	District designation in Arabic.
name_en	string	✅	District designation in English.

✅ 200 — Success

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-here",
    "rate_limit": {
      "limit": 20,
      "unit": "requests per 6 hours",
      "note": "Maximum protection limit. Please cache location data on your server (Recommended TTL: 20 min)."
    }
  },
  "data": [
    {
      "district_id": "dst5kP",
      "place_id": "mep2bM",
      "name": "Al-Nasr District",
      "name_en": "Al-Nasr District"
    }
  ]
}

⚠️ 200 — No Data Scenario (Empty Array)

If no records are found, the API returns a no_data status instead of success, but still with an HTTP 200 OK code.

✅ 200 — No Data Found

{
  "status": "no_data",
  "message": "No records found",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-29T18:52:36Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 20,
      "unit": "requests per 6 hours",
      "note": "Maximum protection limit. Please cache location data on your server (Recommended TTL: 24h)."
    }
  },
  "data": []
}

⚠️ Error Scenarios (Applicable to all Location endpoints)

❌ 401 — Unauthorized

{
  "status": "error",
  "message": "authentication_required"
}

❌ 429 — Rate Limit Exceeded

{
  "status": "error",
  "message": "Rate limit exceeded. Too many requests.",
  "meta": {
    "limit": 20,
    "window": "6 hour(s)",
    "retry_after": "21600s",
    "request_id": "uuid-here"
  }
}

❌ 500 — Server Error

{
  "status": 500,
  "message": "Internal server error"
}

🚚 Shipping Info — Prices & Services

Scope: shipping:read

💡 Expert Implementation Guidance

Shipping price data is account-specific and reflects the merchant's active price package. To ensure system performance and reduce latency, adhere to the following guidelines:

Aggressive Caching: These resources are subject to strict rate limits (10 requests per 24 hours). Implement server-side caching with a 24-hour TTL (Recommended).
Data Lifecycle: Pricing configurations are refreshed once per 24-hour cycle. Only re-fetch if a manual update is triggered or a package change notification is received.
Rate Limit: These endpoints are highly optimized and cached, subject to a limit of 10 requests per 24 hours per account.

GET /api/v1/public/shipping/prices

Retrieve account-specific shipping price configurations using encoded resource identifiers for system-ready logic.

💡 Integration Tip (Server-Side Caching):

Shipping prices are highly stable and typically change every few months. To ensure maximum performance for your checkout process, strongly recommend caching this response on your own server (e.g., in Redis or Database) for 24 hours. Avoid calling this endpoint on every customer page load.

📋 Response Field Specifications

Field	Type	Nullable	Description
package_id	string	❌	Unique resource identifier for the price package configuration.
service_id	string	❌	Shipping service identifier within the price package.
type	string	❌	Pricing scope identifier ("bycity" or "byplace").
to_city	string	❌	Destination city resource identifier.
to_places	array	✅	Collection of covered destination zones/places.
delivery_cost	decimal	❌	Standard delivery fee.
at_branch_delivery	decimal	✅	Self-Service Rate: Fee applied when `delivery_type` is `0` (Branch Pickup). 💡 Pro-tip: This is usually lower than standard delivery.
reject_cost	decimal	✅	Attempt Penalty: Fee charged if the recipient refuses the package at the door after a delivery attempt.
return_cost	decimal	✅	Reverse Logistics Fee: The total cost of returning the package to the merchant warehouse after all delivery attempts have failed.
replacement	decimal	✅	Fee for replacement-type orders.
retrieve	decimal	✅	Fee for retrieval-type orders.
to_weight	decimal	✅	Base weight threshold in KG.
price_per_kilo	decimal	✅	Additional cost per KG above base threshold.
cash_collection	decimal	✅	Fixed COD collection fee.
collection_fees	decimal	✅	Percentage-based collection fee.
collection_after_amount	decimal	✅	Upper bound of the COD range window. Percentage fees apply only when the COD amount is between `collection_from_amount` and this value.
collection_from_amount	decimal	✅	Lower bound of the COD range window. Percentage fees apply only when the COD amount is at or above this value.

📐 Shipping Cost Calculation Algorithm

To implement precise price calculation in your system, follow this standardized logic:

Selection Logic: Identify the pricing resource matching the destination. Specificity Rule: byplace configuration always overrides bycity generic pricing.
Base Fee Selection: Select the base cost field based on order_type:
- New Order → delivery_cost
  Nuance: If delivery is "At Branch", use at_branch_delivery (fallback to delivery_cost).
- Replacement → replacement
- Recovery → retrieve
- Cash Collection → cash_collection
Weight Surcharge: Calculate the Chargeable Weight as max(actual_weight, volumetric_weight).
If Chargeable Weight > to_weight:
Surcharge = (Chargeable Weight - to_weight) × price_per_kilo
COD Processing: If COD is enabled, apply cash_collection. If the COD amount falls within the [from_amount, after_amount] window, apply the collection_fees percentage.

✅ 200 — Shipping Prices

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-29T18:52:36Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
  },
  "data": [
    {
      "package_id": "pkg4eX",
      "service_id": "srv8gJ",
      "type": "bycity",
      "to_city": "lejRej",
      "to_places": [
        { "place_id": "mep2bM" }
      ],
      "delivery_cost": 25.00,
      "at_branch_delivery": 20.00,
      "reject_cost": 5.00,
      "return_cost": 10.00,
      "replacement": 15.00,
      "retrieve": 8.00,
      "to_weight": 30.00,
      "price_per_kilo": 2.50,
      "cash_collection": 25.00,
      "collection_fees": 1.50,
      "collection_after_amount": 100.00,
      "collection_from_amount": 0.00
    }
  ]
}

GET /api/v1/public/shipping/services

Retrieve the collection of shipping services enabled for your account.

📐 Resource Schema: Shipping Service

Field	Type	Nullable	Description
service_id	string	❌	Unique resource identifier for the shipping service.
name	string	❌	Service designation in Arabic.
name_en	string	✅	Service designation in English.

✅ 200 — Shipping Services

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-29T18:52:36Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": { "limit": 10, "unit": "requests per 24 hours" }
  },
  "data": [
    {
      "service_id": "srv8gJ",
      "name": "التوصيل العادي",
      "name_en": "Standard Delivery"
    }
  ]
}

GET /api/v1/public/shipping/config

Retrieve the master configuration settings for order creation. This endpoint returns default values, UI field visibility toggles, and validation requirements tailored to your specific merchant account settings.

💡 Integration Tip:

These configuration settings are semi-static. Fetch them once per day and cache them on your server-side to minimize network overhead during order placement.

📋 Response Field Specifications

Field	Type	Description
🚚 Shipping & Service Defaults
default_shipping_service	string	The default service identifier for pre-populating order creation requests (e.g., "express", "standard").
shipping_services_count	int	Total number of active shipping services currently enabled for your account.
shipping_services_list	array	Collection of all shipping service objects supported by your integration.
default_shipping_price_package	string	The primary pricing schema identifier applied to your account settings.
default_shipping_cost_type	int	Default payer policy (1: Merchant/Sender pays, 0: Recipient/Customer pays).
⚙️ Business Logic Policies
default_allow_opening_orders	int	Global package inspection policy (0: Prohibited, 1: Permitted).
enable_split_shipping_cost	bool	Indicates if the system supports cost-sharing between sender and recipient for this account.
volumetric_weight_calculation_type	int	⚖️ Volumetric Algorithm: `(Length × Width × Height) ÷ divisor = Weight (KG)` The `divisor` is this value (usually `5000` or `6000`).
📝 Validation Constraints & Requirements
required_order_description	string	Specifies the validation constraint for the 'description' parameter ("mandatory" or "optional").
required_order_recipient_name	string	Specifies the validation constraint for the recipient's full name parameter.
required_order_recipient_address	string	Specifies the validation constraint for the physical delivery address parameter.
order_entry_enable_actual_weight	bool	Indicates if the 'actual_weight' parameter is supported/enabled for order creation.
order_entry_enable_dimensions	bool	Indicates if dimensional parameters (Length, Width, Height) are supported for this account.
order_entry_enable_address	bool	Indicates if text-based address entry is enabled in the order payload.
order_entry_enable_address_marker	bool	Indicates if a distinguishing mark or landmark description is supported for the delivery address.
order_entry_enable_building_info	bool	Indicates if granular building/floor information parameters are supported.
enable_multiple_payment_methods	bool	Indicates if the system supports multiple payment methods for a single order.

📦 Embedded Shipping Services Object

Contained within the shipping_services_list array.

Field	Type	Description
service_id	string	The unique identifier for the shipping service.
name	string	Service name in Arabic.
name_en	string	Service name in English.

✅ 200 — Order Creation Configuration

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 10,
      "unit": "requests per 24 hours",
      "note": "Maximum protection limit. This data is semi-static; please cache it on your server for 24h."
    }
  },
  "data": {
    "default_shipping_service": "srv8gJ",
    "shipping_services_count": 1,
    "shipping_services_list": [
      {
        "service_id": "srv8gJ",
        "name": "التوصيل العادي",
        "name_en": "Standard Delivery"
      }
    ],
    "default_shipping_price_package": "pkg4eX",
    "default_shipping_cost_type": 1,
    "default_allow_opening_orders": 0,
    "enable_split_shipping_cost": true,
    "required_order_description": "optional",
    "volumetric_weight_calculation_type": 6000,
    "order_entry_enable_actual_weight": true,
    "order_entry_enable_dimensions": true,
    "required_order_recipient_name": "mandatory",
    "order_entry_enable_address": true,
    "required_order_recipient_address": "mandatory",
    "order_entry_enable_address_marker": true,
    "order_entry_enable_building_info": true,
    "enable_multiple_payment_methods": false
  }
}

GET /api/v1/public/shipping/config/statuses

Retrieve the comprehensive collection of system-wide order statuses, including their localized names and visual brand attributes (colors).

📐 Resource Schema: Order Status

Field	Type	Nullable	Description
key	int	❌	The numeric key identifier for the status (starting from 1). 🛡️ Integrity Note: Only verified and active operational statuses are exposed via the Public API to ensure data consistency.
name	string	❌	Localized status name in Arabic.
name_en	string	✅	Localized status name in English.
color	string	✅	Hexadecimal color code or system color name for UI representation.

🛡️ High Protection Endpoint:

This endpoint provides semi-static configuration data and is subject to strict security protocols:

Rate Limit: Maximum 2 requests per 24-hour cycle.

✅ 200 — Order Statuses List

{
  "status": "success",
  "message": "Data retrieved successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-05-02T10:45:00Z",
    "request_id": "uuid-here",
    "rate_limit": {
      "limit": 2,
      "unit": "requests per 24 hours",
      "note": "Maximum protection limit. This data is semi-static; please cache it on your server for 24h."
    }
  },
  "data": [
    {
      "key": 1,
      "name": "جديد",
      "name_en": "New",
      "color": "#3498db"
    },
    {
      "key": 10,
      "name": "تم الاستلام",
      "name_en": "Received",
      "color": "#2ecc71"
    }
  ]
}

⚠️ Error Scenarios (Applicable to all Shipping endpoints)

❌ 400 — Bad Request

{
  "status": "error",
  "message": "No shipping price package assigned to this account."
}

❌ 401 — Unauthorized

{
  "status": "error",
  "message": "authentication_required"
}

❌ 429 — Rate Limit Exceeded

{
  "status": "error",
  "message": "Rate limit exceeded. Too many requests.",
  "meta": {
    "limit": 10,
    "window": "24 hour(s)",
    "retry_after": "86400s",
    "request_id": "uuid-here"
  }
}

📦 Create & Manage Orders

Creation: 30/min Update: 10/30min Delete: 3/5min

▼

POST /api/v1/public/orders/create

Create a new shipping order with complete technical details. This endpoint supports granular control over recipient info, shipment characteristics, and financial breakdown. It uses database transactions for data integrity.

📦 Request Body (JSON)

Field	Type	Required	Description
🔵 Shipping Service & Reference
ref_num	string	❌	Merchant's internal reference number. (Highly Recommended: Used for 30-day duplicate protection).
shipping_service	string	✅	Encoded shipping service ID. 💡 Alias: `shipment_info.service_id` is also accepted.
👤 Recipient Information
recipient.name	string	✅	Full name (max 50 chars)
recipient.phone	string	✅	Primary contact number
recipient.phone2	string	❌	Alternative phone number
recipient.whatsapp	string	❌	WhatsApp enabled number
recipient.to_city	string	✅	Encoded destination City ID
recipient.to_place	string	❌	Encoded destination Place/Zone ID. ⚙️ Logic: Defaults to `"0"` if empty, enabling generic city delivery.
recipient.to_district	string	❌	Encoded District/Neighborhood ID. 🏙️ Resource Link: Fetch valid IDs from Delivery Locations > Districts. Providing a district increases First Attempt Delivery Success (FADS) by enabling granular driver routing.
recipient.address	string	❌	Detailed delivery address
recipient.address_marker	string	❌	Address landmark (marker)
recipient.building_no	string	❌	Building/House number
recipient.role_no	string	❌	Floor number
recipient.apartment_no	string	❌	Apartment/Suite number
📦 Shipment Information
shipment_info.description	string	✅	Detailed item description (Required/Nullable based on config)
type	int	✅	Order category mapping (1-4). (Invalid values default to 1: New Order). ⚠️ Legacy field. Prefer using `shipment_info.order_type` for clarity.
shipment_info.pieces	integer	✅	Number of packages in this order. ⚠️ Constraint: Minimum `1`, Maximum `3`.
shipment_info.order_type	string \| int	✅	Type of shipment: `new_order`, `replacement`, `recovery`, or `cash_collection`. 🔢 Numeric Mapping: `1`=New, `2`=Replacement, `3`=Recovery, `4`=Cash Collection.
shipment_info.delivery_type	integer	✅	0=Branch Pickup, 1=Door Delivery (default: 1)
shipment_info.replacement_info	string	❌	Details if order_type is `replacement`
shipment_info.replacement_order	string	❌	Original order ID for replacement
shipment_info.allow_opening	integer	✅	0=Strictly No, 1=Allowed (default: 0)
shipment_info.breakable	integer	✅	0=Standard, 1=Fragile (default: 0)
shipment_info.notes	string	❌	Special instructions (max 255 chars)
📏 Dimensions & ⚖️ Weights
shipment_info.dimensions	object	❌	Package dimensions: `{length, width, height}` (cm)
shipment_info.weights.actual_weight	number	❌	Physical weight in kilograms
shipment_info.weights.total_weight	number	❌	Total weight used for pricing
shipment_info.weights.extra_weight	number	❌	Weight exceeding the base allowance
shipment_info.weights.extra_weight_cost	number	❌	Additional cost applied to extra weight
💰 Financial Information
financial_info.amount	number	✅	Base product price (Goods value)
financial_info.amount_type	integer	✅	`0`: Excludes delivery (Amount = Product only) `1`: Includes delivery (Amount = Product + Shipping)
financial_info.payment_type	string	❌	Method: `cash`, `card`, `prepaid`
financial_info.main_delivery_cost	number	❌	Original delivery cost before any merchant adjustments
financial_info.delivery_cost	number	✅	The final shipping fee calculated for this route
financial_info.shipping_cost_type	integer	✅	Payment attribution for shipping fee: `0`: Free Shipping (No cost applied) `1`: Merchant Pays (Deducted from merchant wallet) `2`: Customer Pays (Added to recipient's COD amount) `3`: Split Payment (Distributed between parties)
financial_info.customer_will_pay	number	❌	Portion of shipping fee paid by recipient (if splitting)
financial_info.sender_will_pay	number	❌	Portion of shipping fee paid by sender (if splitting)
financial_info.total	number	✅	Grand total calculation: (Amount + Delivery)
financial_info.cod	number	✅	Cash On Delivery (Total amount to collect at door)
financial_info.cash_payment	number	❌	Actual cash amount received (for logging/UI)
financial_info.cc_present	integer	❌	`0` or `1`: Credit card flag
financial_info.with_cash_difference	string	❌	`yes` or `no`
financial_info.cash_difference_type	string	❌	`collection` (extra) or `payment` (refund)
financial_info.collection_amount	number	❌	Specific extra amount to collect
financial_info.payment_amount	number	❌	Specific amount to be refunded

🔍 Key Validation Rules

shipping_service: Must be a valid encoded string, not "0".
recipient.phone: Strict format and length validation.
shipment_info.pieces: Must be between 1 and 3.
shipment_info.order_type: Must be one of: new_order, replacement, recovery, cash_collection.
financial_info.amount_type: 0 (price only) or 1 (price + delivery).

⚙️ Business Logic Notes

🔹 Order Status: All orders are initialized with Status 1 (Created).
🔹 Tracking: An initial tracking record is automatically generated upon success.
🔹 Atomic Guarantee: If any part of the order fails validation, the entire operation is cancelled for safety.
🔹 Data Normalization: Missing optional fields (like phone2, whatsapp, or address) are automatically converted to empty strings "" instead of null.
🔹 Automatic Defaulting: Fields like to_place are automatically set to 0 if not provided.

📝 Complete Request Example

{
  "shipping_service": "dKp3nX",
  "ref_num": "MER-2025-001",
  "recipient": {
    "name": "Mohammed Ali",
    "phone": "+21890000000",
    "phone2": "+21890111111",
    "whatsapp": "+21890000000",
    "to_city": "dKp3nZ",
    "to_place": "dKp3nY",
    "to_district": "dKp3nK",
    "address": "123 Customer Street, Tripoli",
    "address_marker": "Near Grand Mosque",
    "building_no": "12",
    "role_no": "2",
    "apartment_no": "B4"
  },
  "shipment_info": {
    "description": "Electronics package (High Value)",
    "pieces": 1,
    "order_type": "new_order",
    "delivery_type": 1,
    "replacement_info": "",
    "replacement_order": "",
    "allow_opening": 1,
    "breakable": 0,
    "notes": "Handle with extreme care",
    "dimensions": {
      "length": "30",
      "width": "20",
      "height": "10"
    },
    "weights": {
      "actual_weight": "1.5",
      "volumetric_weight": "1.2",
      "total_weight": 1.5,
      "allowed_weight": 2.0,
      "extra_weight": 0,
      "extra_weight_cost": 0
    }
  },
  "financial_info": {
    "amount": 250,
    "amount_type": 1,
    "payment_type": "cash",
    "main_delivery_cost": 50,
    "delivery_cost": 50,
    "cash_payment": "0",
    "shipping_cost_type": 1,
    "customer_will_pay": "0",
    "sender_will_pay": "0",
    "total": 300,
    "cod": 300,
    "cc_present": "no",
    "with_cash_difference": "no",
    "cash_difference_type": "",
    "collection_amount": 0,
    "payment_amount": 0
  }
}

✅ Success Response (200 Success)

{
  "status": "success",
  "message": "order_created_successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 30,
      "unit": "requests per minute",
      "note": "Standard creation quota."
    }
  },
  "data": {
    "order_id": "ord4cN",
    "order_snum": 10042
  }
}

📌 Response Fields:

order_id: Unique encoded identifier (Use this for all subsequent API calls like update/delete/tracking).
order_snum: Sequential system number (Used for display, labels, and human-readable tracking).

⚙️ Business Logic Notes:

🔹 Initial Status: All orders are automatically created with Status 1 (Order Created).
🔹 Auto-Tracking: The system generates an initial tracking event immediately upon successful creation.

❌ Possible Error Responses

❌ 422 — Validation Failed

{
  "status": "error",
  "message": "validation_errors",
  "errors": {
    "recipient.phone": [
      "The recipient.phone field is required."
    ],
    "shipment_info.pieces": [
      "The shipment_info.pieces may not be greater than 3."
    ]
  },
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

❌ 500 — Internal Server Error

{
  "status": "error",
  "message": "internal_server_error",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 30,
      "unit": "requests per minute",
      "note": "Standard creation quota."
    },
    "hint": "An unexpected error occurred. Please try again or contact support if the issue persists."
  }
}

❌ 401 — Unauthorized

{
  "status": "error",
  "message": "Unauthenticated",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 30,
      "unit": "requests per minute",
      "note": "Standard creation quota."
    },
    "hint": "Missing or invalid API Key/Secret in custom headers (ShippingEyes-Api-Key / ShippingEyes-Api-Secret)."
  }
}

💡 200 — Duplicate Order Detected

Note: The system returns a 200 status for duplicates to allow seamless integration. Developers should check the message field for order_exists_duplicate.

{
  "status": "success",
  "message": "order_exists_duplicate",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "data": {
    "exists_orders": [
      {
        "order_id": "ord4cN",
        "snum": 10042,
        "ref_num": "MER-2025-001"
      }
    ]
  }
}

❌ 423 — Order Locked

{
  "status": "error",
  "message": "Order is currently being processed. Please wait.",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

❌ 403 — Status Not Allowed

{
  "status": "error",
  "message": "status_not_allowed",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
  }
}

POST /api/v1/public/orders/update

Update an existing order's information. This endpoint requires the order_id and validates that the order is in an editable lifecycle stage.

⚙️ Update Eligibility Rules

🔹 Allowed Statuses: Modifications are only permitted if the order status_key is 1 (Pending).
🔹 Locked State: If an order is currently being processed by a dispatcher, it will return a 423 Locked error.

📦 Request Body (JSON)

Field	Type	Required	Description
🔑 Order Identification
order_id	string	✅	Unique encoded ID of the order to update (Mandatory)
(Inherits all fields from Create Order schema)

⚠️ Critical Edit Restrictions

🔹 Status Lock: Updates are strictly permitted only for orders with status_key: 1 (Pending).
🔹 Scope Validation: The API verifies that the order_id belongs to your merchant account before applying any changes.
🔹 Validation: All updated data undergoes the same validation rules as new order creation.

✅ 200 — Order Updated

{
  "status": "success",
  "message": "order_updated_successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T02:40:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 10,
      "unit": "requests per 30 minutes",
      "note": "Strict update quota for data consistency."
    }
  },
  "data": {
    "order_id": "ord4cN",
    "order_snum": 10042
  }
}

❌ 403 — Status Restricted

{
  "status": "error",
  "message": "Order status is restricted from updates.",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T09:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 10,
      "unit": "requests per 30 minutes",
      "note": "Strict update quota for data consistency."
    }
  },
  "errors": {
    "status_key": 22,
    "status_name": "Out for Delivery"
  }
}

❌ 423 — Order Locked

{
  "status": "error",
  "message": "Order is currently being updated. Please wait.",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T09:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 10,
      "unit": "requests per 30 minutes",
      "note": "Strict update quota for data consistency."
    }
  }
}

DELETE /api/v1/public/orders/delete/{order_id}

Delete an order by its unique identifier. This action is irreversible and restricted based on the order's current lifecycle stage.

Parameter	Type	In	Description
order_id	string	URL	The unique encoded identifier of the order.

⚙️ Mandatory Deletion Rules

🔹 Status Eligibility: You can only delete orders with status_key: 1 (Pending). Orders in any status > 1 cannot be deleted via this endpoint.
🔹 Security & Ownership: The API strictly validates that the order belongs to your authenticated merchant account.
🔹 Audit Trail: Deleted orders are logged in the system activity for forensic and auditing purposes.
🔹 Delete Quota: To prevent mass-deletion attacks, you are limited to 3 deletions every 5 minutes. Exceeding this will return a 429 Rate Limit error.

❌ 404 — Order Not Found

{
  "status": "error",
  "message": "order_not_found",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

✅ 200 — Order Deleted

{
  "status": "success",
  "message": "deleted_successfully",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 3,
      "unit": "requests per 5 minutes",
      "note": "Strict security-first deletion quota."
    }
  },
  "data": {
    "deleted_order_id": "lejRej",
    "order_snum": 12345,
    "reference_number": "REF-9988",
    "recipient_phone": "0912345678"
  }
}

❌ 404 — Order Not Found

{
  "status": "error",
  "message": "order_not_found",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T02:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 3,
      "unit": "requests per 5 minutes",
      "note": "Strict security-first deletion quota."
    },
    "hint": "The order was not found, does not belong to your account, or its status is not 'Pending'."
  }
}

❌ 400 — Deletion Failed

{
  "status": "error",
  "message": "cannot_delete_order",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T02:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
      "limit": 3,
      "unit": "requests per 5 minutes",
      "note": "Strict security-first deletion quota."
    },
    "hint": "A system error occurred while attempting to delete the record."
  }
}

📖 List & Search Orders

Scope: orders:read / tracking:read

GET /api/v1/public/orders/list/{status}

List your orders filtered by status, with pagination support.

💡 Developer Note:

This endpoint is intended for manual synchronization only. For real-time updates without restrictions, please enable the Webhooks system.

🔍 Parameters

Parameter	Type	In	Description
status	string	URL	Filter by status key. Use `all` for everything, or a numeric key: • `1`: Created • `10`: Picked Up • `22`: Out for Delivery • `30`: Delivered • `40`: Returned
page	integer	Query	Page number for pagination (default: 1)
page_limit	integer	Query	Results per page (default: 30, max: 75)
date_from	string	Query	Optional: Start date filter (YYYY-MM-DD)
date_to	string	Query	Optional: End date filter (YYYY-MM-DD)

📐 Resource Schema: Order Data

Field	Type	Description
order_id	string	Unique encoded identifier for the order resource.
snum	int	Sequential internal serial number.
ref_num	string	The custom merchant reference number (nullable).
status	object	Current order status: `name` (string): Arabic label of the status. `key` (int): The unique status identifier.
shipment	object	Logistics details: `type` (object): `{name, key}` e.g., New Order. `delivery_type` (object): `{name, key}` e.g., Regular. `pieces` (int): Number of items (Default: 1). `description` (string): Contents description.
recipient	object	Customer information: `name` (string): Full name. `phone` (string): Primary contact number. `address` (string): Detailed street address. `location` (object): `{city: string, place: string}`.
financial	object	Monetary & Payment details: `amount` (float): Total order value. `amount_type` (object): `{name, key}` (e.g., Includes Delivery). `delivery_cost` (float): Shipping fee. `delivery_cost_type` (object): `{name, key}`. `cod` (float): Cash on Delivery amount to be collected. `replacement_details` (object): Nullable details for exchange/retrieve orders: • `with_cash_difference` (int): 0/1. • `cash_difference_type` (string). • `payment_amount` (float). • `collection_amount` (float).
tracking_count	int	Total count of tracking events in the timeline.
created_at	string	Creation timestamp in ISO 8601 format.

✅ 200 — Orders List

{
  "status": 200,
  "message": "success",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-string",
    "current_page": 1,
    "last_page": 3,
    "per_page": 30,
    "total": 45,
    "count": 1,
    "rate_limit": {
      "limit": 15,
      "unit": "requests per hour",
      "note": "Real-time monitoring quota. No-cache enforced."
    }
  },
  "data": [
    {
      "order_id": "ord4cN",
      "snum": 1001,
      "ref_num": "MER-2025-001",
      "status": {
        "name": "تم إنشاء الطلب",
        "key": 1
      },
      "shipment": {
        "type": {
          "name": "طلب جديد",
          "key": 1
        },
        "delivery_type": {
          "name": "توصيل عادي",
          "key": 1
        },
        "pieces": 1,
        "description": "Electronics package"
      },
      "recipient": {
        "name": "Ahmed Hassan",
        "phone": "+21890000000",
        "address": "Tripoli, Libya",
        "location": {
          "city": "طرابلس",
          "place": "الأندلس"
        }
      },
      "financial": {
        "amount": 250,
        "amount_type": {
          "name": "شامل التوصيل",
          "key": 1
        },
        "delivery_cost": 50,
        "delivery_cost_type": {
          "name": "ثابت",
          "key": 1
        },
        "cod": 300,
        "replacement_details": {
          "with_cash_difference": null,
          "cash_difference_type": null,
          "payment_amount": null,
          "collection_amount": null
        }
      },
      "tracking_count": 1,
      "created_at": "2026-04-30T10:45:00Z"
    }
  ]
}

GET /api/v1/public/orders/info/{order_id}

Retrieve forensic-grade details for a specific order. This endpoint utilizes a high-performance Super Query architecture, fetching all metadata and history in exactly 3 database queries (the main query uses optimized JOINs to resolve all related entities in a single pass).

⏱️ Rate Limiting: To ensure system stability, this endpoint is limited to 1 request per minute per API Key.

💡 Developer Note:

Since order data already exists on your platform, frequent fetching is unnecessary. This strict limit is enforced to ensure maximum system stability and performance. For real-time updates, please use the Webhooks system.

Parameter	Type	In	Description
order_id	string	URL	Encoded order identifier (e.g., `e1jrj3`)

📐 Response Data Architecture

Object	Description
`status`	Current state with localized `name` and numeric `key` for logical processing.
`shipment`	Technical specs: Service ID, dimensions, pieces, and volumetric weight flags.
`recipient`	Forensic location hierarchy: Country, City, Place, and District (each with `name` and `id`).
`financial`	Transaction audit: Total amount, COD, Cost Sharing (Sender/Customer), and Net Payout.
`branch`	Logistics attribution: Both `creation` branch and `current` handling branch.
`tracking`	Immutable timeline of every status transition and logistics event.
`followups`	Forensic history of call center attempts, driver notes, and delivery exceptions.

📦 Shipment Schema

Field	Type	Description
`type`	object	Localized order type (e.g., Package, Document).
`service`	object	Assigned service name and its encoded ID.
`allow_opening`	object	Permissions for customer to inspect package before payment.
`weights`	object	Detailed breakdown: `actual`, `volumetric`, and `is_volumetric_applied` (boolean). 💡 Note: If `is_volumetric_applied` is `true`, the delivery cost is calculated based on dimensions rather than actual weight.
`dimensions`	object	Physical size in CM (Length, Width, Height).
`replacement_data`	object	Links to previous order IDs if this is a replacement request.

👤 Recipient & Location Schema

Field	Type	Description
`name` / `phone`	string	Primary contact information.
`location`	object	Strict 4-level hierarchy: `country`, `city`, `place`, `district`.
`address_details`	object	Granular data: Building No, Floor, Apartment, and Landmark.

🛡️ Forensic Security Note: The delegate object is conditionally returned. Contact details are only visible when the order status strictly exceeds 20 (e.g., Status 22: Out for Delivery). At-branch stages (Status ≤ 20) return null.

💰 Financial & Audit Schema

Field	Type	Description
`total_amount`	float	The base value of the goods.
`delivery_cost`	object	Breakdown of base cost + extra weight surcharges.
`cost_sharing`	object	Forensic split: How much the `sender` pays vs the `customer`.
`cod_to_collect`	float	The final amount the driver must collect at the door.
`net_payout`	float	Expected Merchant Net Revenue. The final calculated amount to be credited to the merchant's wallet after all logistics fees are adjusted. ⚖️ Critical for ERP: Use this field for automatic financial reconciliation and ledger balancing.
`retrieve_replacement_details`	object	Audit trail for cash differences and collection amounts in replacement workflows.

✅ 200 — Forensic Order Details

{
  "status": 200,
  "message": "success",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-05-01T15:30:00Z",
    "request_id": "uuid-v4-string",
    "rate_limit": {
      "limit": 1,
      "unit": "requests per minute",
      "note": "Real-time data. No-cache enforced for data integrity."
    }
  },
  "data": {
    "order_id": "e1jrj3",
    "snum": 176278,
    "ref_num": "REF-12345",
    "status": {
      "name": "Out for Delivery",
      "key": 22
    },
    "shipment": {
      "type": { "name": "Package", "key": "package" },
      "source": "api",
      "service": { "name": "Home Delivery", "id": "srv8gJ" },
      "delivery_type": { "name": "Standard", "key": 1 },
      "pieces": 1,
      "description": "Electronics",
      "notes": "Fragile",
      "allow_opening": { "name": "no", "key": 0 },
      "breakable": { "name": "yes", "key": 1 },
      "dimensions": { "unit": "cm", "length": 20.0, "width": 15.0, "height": 10.0 },
      "weights": {
        "unit": "kg",
        "actual": 1.5,
        "volumetric": 0.6,
        "allowed": 5.0,
        "extra": 0.0,
        "total": 1.5,
        "extra_cost": 0.0,
        "is_volumetric_applied": false
      },
      "confirmed": 1,
      "is_fulfillment_order": false,
      "replacement_data": { "info": null, "order": null }
    },
    "recipient": {
      "name": "Bahaa Eldin",
      "phone": "0910000000",
      "phone2": null,
      "address": "Republic Street",
      "address_details": {
        "landmark": "Near Blue Mosque",
        "building_no": "15",
        "floor_no": "2",
        "apartment_no": "5",
        "dropoff_map": null
      },
      "location": {
        "country": { "name": "Libya", "id": "cRy1xZ" },
        "city": { "name": "Tripoli", "id": "lejRej" },
        "place": { "name": "Hay Al-Andalus", "id": "mep2bM" },
        "district": { "name": "Zone 4", "id": "dis9kL" }
      }
    },
    "financial": {
      "total_amount": 1000.0,
      "amount_type": { "name": "Excluding Delivery", "key": 0 },
      "delivery_cost": {
        "base": 15.0,
        "extra_weight": 0.0,
        "total": 15.0,
        "type": { "name": "Standard", "key": 1 }
      },
      "cost_sharing": {
        "customer_will_pay": 0.0,
        "sender_will_pay": 1000.0
      },
      "cod_to_collect": 0.0,
      "net_payout": 1000.0,
      "payment_type": { "name": "Prepaid", "key": "prepaid" },
      "cash_payment": 1000.0,
      "retrieve_replacement_details": {
        "with_cash_difference": false,
        "cash_difference_type": { "name": null, "key": null },
        "payment_amount": null,
        "collection_amount": null
      }
    },
    "branch": {
      "creation": "Main Branch",
      "current": "Delivery Hub"
    },
    "delegate": {
      "name": "Ahmed Driver",
      "phone": "0920000000"
    },
    "tracking": {
      "count": 1,
      "history": [
        {
          "status": { "name": "Out for Delivery", "key": 22 },
          "created_at": "2026-05-01T11:00:00Z"
        }
      ]
    },
    "followups": {
      "count": 1,
      "history": [
        {
          "followup_type": "call",
          "reason_text": "No Answer",
          "notes": "Customer did not pick up",
          "created_at": "2026-05-01T12:00:00Z"
        }
      ]
    },
    "created_at": "2026-05-01T10:00:00Z"
  }
}

❌ 400 — Invalid Order ID

{
  "status": 400,
  "message": "invalid_order_id",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-05-01T15:30:00Z",
    "request_id": "uuid-v4-string",
  }
}

❌ 404 — Order Not Found

{
  "status": 404,
  "message": "order_not_found",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-05-01T15:30:00Z",
    "request_id": "uuid-v4-string",
  }
}

POST /api/v1/public/orders/search

Search and Query Merchant Orders with Ultra High Performance. Supports complex filtering, date ranges, and pagination.

⚠️ Performance & Security: This endpoint is optimized for speed and has a strict rate limit of 5 requests per hour to ensure system stability.

💡 Developer Note:

This endpoint is for emergency manual lookups only. Redundant searching is prohibited for system stability. For complex data retrieval, please use the Webhooks system.

📐 Request Parameters (JSON Body)

Parameter	Type	Required	Description
search_data	string	✅ Yes	The query string (min 2, max 100 chars). 🛡️ Security & Performance: A minimum of 2 characters is required to prevent exhaustive database scanning and ensure optimal response times.
search_type	enum	✅ Yes	Column to search: `snum`, `ref_num`, `name`, `phone`, `phone2`, `address`, `address_marker`, `description`, `amount`. 🚀 Micro-Optimization Note: Searching by `amount` or `snum` automatically forces the `matched` (exact) condition. This bypasses heavy `LIKE` operations on indexed numeric columns, ensuring sub-millisecond query execution even with millions of records.
search_condition	enum	✅ Yes	Matching logic: `start_with`, `end_with`, `contains`, `matched`.
date_from	date	No	Filter by creation date (YYYY-MM-DD).
date_to	date	No	Filter by creation date (YYYY-MM-DD). Must be >= date_from.
page_number	int	No	Pagination index (starts from 1). Default is 1. Returns 30 results per page.

📐 Resource Schema: Order Data

Field	Type	Description
order_id	string	Unique encoded identifier for the order resource.
snum	int	Sequential internal serial number.
ref_num	string	The custom merchant reference number (nullable).
status	object	Current order status: `name` (string): Arabic label of the status. `key` (int): The unique status identifier.
shipment	object	Logistics details: `type` (object): `{name, key}` e.g., New Order. `delivery_type` (object): `{name, key}` e.g., Regular. `pieces` (int): Number of items (Default: 1). `description` (string): Contents description.
recipient	object	Customer information: `name` (string): Full name. `phone` (string): Primary contact number. `address` (string): Detailed street address. `location` (object): `{city: string, place: string}`.
financial	object	Monetary & Payment details: `amount` (float): Total order value. `amount_type` (object): `{name, key}` (e.g., Includes Delivery). `delivery_cost` (float): Shipping fee. `delivery_cost_type` (object): `{name, key}`. `cod` (float): Cash on Delivery amount to be collected. `replacement_details` (object): Nullable details for exchange orders: • `with_cash_difference` (int): 0/1. • `cash_difference_type` (string). • `payment_amount` (float). • `collection_amount` (float).
tracking_count	int	Total count of tracking events in the timeline.
created_at	string	Creation timestamp in ISO 8601 format.

📋 Response Structure (Standardized Schema)

✅ 200 — Search Results

{
  "status": 200,
  "message": "success",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-string",
    "current_page": 1,
    "last_page": 1,
    "per_page": 30,
    "total": 1,
    "count": 1,
    "rate_limit": {
      "limit": 5,
      "unit": "requests per hour",
      "note": "Strict search limit for security. No-cache enforced."
    }
  },
  "data": [
    {
      "order_id": "ord4cN",
      "snum": 10042,
      "ref_num": "REF-998877",
      "status": {
        "name": "Out for Delivery",
        "key": 22
      },
      "shipment": {
        "type": { "name": "Delivery", "key": 1 },
        "delivery_type": { "name": "Standard", "key": 1 },
        "pieces": 1,
        "description": "Electronics package"
      },
      "recipient": {
        "name": "Ahmed Hassan",
        "phone": "0910000000",
        "address": "123 Main Street",
        "location": {
          "city": "Tripoli",
          "place": "Tajoura"
        }
      },
      "financial": {
        "amount": 250,
        "amount_type": { "name": "Includes delivery", "key": 1 },
        "delivery_cost": 50,
        "delivery_cost_type": { "name": "Prepaid", "key": 1 },
        "cod": 300,
        "replacement_details": {
          "with_cash_difference": null,
          "cash_difference_type": null,
          "payment_amount": null,
          "collection_amount": null
        }
      },
      "tracking_count": 5,
      "created_at": "2026-04-30T10:45:00Z"
    }
  ]
}

❌ 422 — Validation Error

{
  "status": 422,
  "message": "validation_errors",
  "errors": {
    "search_type": ["Invalid search type selected."],
    "date_to": ["date_to must be equal to or after date_from."]
  }
}

GET /api/v1/public/orders/tracking/{order_id}

Get the tracking timeline of an order.

Parameter	Type	In	Description
order_id	string	URL	Encoded order ID

📐 Resource Schema: Tracking Event

Field	Type	Nullable	Description
status_key	integer	❌	The numeric identifier of the order status.
status_name	string	❌	The localized name of the status (e.g., "Picked Up").
date	string	❌	Event date formatted as `YYYY-MM-DD`.
time	string	❌	Event time formatted as `HH:MM AM/PM`.
timestamp	string	❌	Full ISO 8601 timestamp for sorting and precise tracking.

✅ 200 — Success Response

{
  "status": 200,
  "message": "success",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-string"
  },
  "data": {
    "order_id": "ord4cN",
    "snum": 1001,
    "ref_num": "REF-2025-001",
    "status_key": 22,
    "status_name": "Out for Delivery",
    "created_at": "2026-04-15T10:30:00Z",
    "tracking_count": 1,
    "tracking_history": [
      {
        "status_key": 22,
        "status_name": "Out for Delivery",
        "date": "2026-04-30",
        "time": "10:30 AM",
        "timestamp": "2026-04-30T10:30:00Z"
      }
    ],
    "rate_limit": {
      "limit": 5,
      "unit": "requests per 5 minutes",
      "note": "Strict limit for single order tracking. Use Bulk API for multiple orders."
    }
  }
}

❌ 422 — Invalid Identifier

{
  "status": 422,
  "message": "validation_errors",
  "errors": {
    "order_id": ["The provided order_id is invalid or incorrectly formatted."]
  }
}

❌ 404 — Order Not Found

{
  "status": 404,
  "message": "order_not_found",
  "note": "Order not found or access denied for this merchant account."
}

POST /api/v1/public/orders/tracking/bulk

Get tracking timelines for multiple orders in a single request. Highly recommended for syncing public systems with Shipping Eyes.

🔍 Request Parameters

Field	Type	Required	Description
tracking_type	string	✅ Yes	The type of identifier provided: `order_numbers` (snum), `reference_numbers` (merchant ref), or `order_id_list` (hashed ID).
orders	array	✅ Yes	A list of identifiers (strings or numbers). Max: 150 per request. Each identifier max 50 chars.

📐 Resource Schema: Tracking Event (History)

Field	Type	Nullable	Description
status_key	integer	❌	Status identifier.
status_name	string	❌	Human-readable status name.
date	string	❌	Event date (YYYY-MM-DD).
time	string	❌	Event time (HH:MM AM/PM).
timestamp	string	❌	ISO 8601 timestamp.

🛠 Technical Implementation Details:

Key Mapping: The data object in the response uses the requested identifiers as keys. If a key is missing from the data object, it indicates the order does not exist or access is restricted.
Hashed ID Integrity: When using order_id_list, the API performs a strict integrity check. If any ID in the array is malformed or invalid, a 422 Validation Error is returned for the entire batch.
Not Found Behavior: Individual orders that fail lookup return a not_found status object within the primary response map, as shown in the example below.
Payload Optimization: To ensure high performance, the tracking_history array in the bulk endpoint is limited to the latest 5 status changes per order. For full history, use the single tracking endpoint.
Batch Processing: Responses include a meta object with total_requested, found_count, and not_found_count for quick statistics.

📝 Request Example (order_numbers)

{
  "tracking_type": "order_numbers",
  "orders": ["1001", "1002"]
}

✅ 200 — Bulk Tracking Success

{
  "status": 200,
  "message": "success",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:00:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "total_requested": 2,
    "found_count": 1,
    "not_found_count": 1,
    "tracking_type": "order_numbers",
    "rate_limit": {
      "limit": 15,
      "unit": "requests per 24 hours",
      "note": "Daily quota for bulk monitoring."
    }
  },
  "data": {
    "1001": {
      "order_id": "ord4cN",
      "snum": 1001,
      "ref_num": "REF-2025-001",
      "status_key": 22,
      "status_name": "Out for Delivery",
      "created_at": "2026-04-30 10:00:00",
      "tracking_history": [
        {
          "status_key": 30,
          "status_name": "Delivered",
          "date": "2026-04-30",
          "time": "10:30 AM",
          "timestamp": "2026-04-30T10:30:00Z"
        }
      ]
    },
    "1002": {
      "status": "not_found",
      "message": "Order not found or does not belong to this merchant"
    }
  }
}

❌ 422 — Validation Error

{
  "status": 422,
  "message": "validation_errors",
  "errors": {
    "tracking_type": ["The selected tracking_type is invalid."],
    "orders": ["Maximum 150 orders allowed per request."]
  },
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-string",
    "rate_limit": {
      "limit": 15,
      "unit": "requests per 24 hours",
      "note": "Daily quota for bulk monitoring. Use individual calls for single order deep dives."
    }
  }
}

❌ 422 — Hashed ID Integrity Error

{
  "status": 422,
  "message": "validation_errors",
  "errors": {
    "orders": ["Invalid order ID detected in list."]
  },
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-string",
    "rate_limit": {
      "limit": 15,
      "unit": "requests per 24 hours",
      "note": "Daily quota for bulk monitoring. Use individual calls for single order deep dives."
    }
  }
}

🛡️ Usage Quota & Rate Limits

To ensure system stability, the following limits apply to the Bulk Tracking API:

🔹 Daily Quota: 15 requests per day per API Key.
🔹 Batch Size: Maximum 150 identifiers per single request.
🔹 Efficiency: Use this endpoint to sync multiple orders instead of individual calls.

💬 Order Followups

Scope: orders:read

POST /api/v1/public/orders/followups/bulk

Retrieve the latest followups (notes and actions) for up to 100 orders in a single request.

📥 Request Body (JSON)

Field	Type	Required	Description
tracking_type	string	✅ Yes	`order_numbers`, `reference_numbers`, or `order_id_list`.
orders	array	✅ Yes	List of identifiers. Max: 100 per request.

🛠 Technical Details & Performance:

Batch Size Constraint: This endpoint is limited to 100 orders per request (compared to 150 in tracking). This ensures high performance given that followup data contains rich text notes and multiple descriptive actions which increase the response payload size.
History Depth: Only the latest 5 followups per order are returned in this bulk endpoint.
Dictionary Structure: Response is keyed by your requested identifier for $O(1)$ client-side access.
Privacy: To protect internal staff, no employee names or internal IDs are exposed in the followup history.

📐 Resource Schema: Followup Data

Field	Type	Description
followup_type	string	The type of the followup (e.g. followup, returned, refused).
reason_text	string	Localized name of the reason (defaults to `NotSet`).
notes	string	The actual content of the followup.
created_at	string	ISO 8601 timestamp of when the followup was created.

📌 Followup Type Reference (followup_type)

followup_type	Description
`followup`	Order followup or feedback.
`returned`	Order Status: Returned.
`refused`	Order Status: Refused.

✅ 200 — Success Response

{
  "status": 200,
  "message": "success",
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-04-30T10:45:00Z",
    "request_id": "uuid-string",
    "total_requested": 1,
    "found_count": 1,
    "not_found_count": 0,
    "tracking_type": "order_numbers",
    "rate_limit": {
      "limit": 15,
      "unit": "requests per 24 hours",
      "note": "Daily quota for bulk monitoring."
    }
  },
  "data": {
    "1001": {
      "order_id": "ordHash",
      "snum": 1001,
      "ref_num": "REF-123",
      "status_key": 22,
      "status_name": "Out for Delivery",
      "created_at": "2026-04-30 10:00:00",
      "followups": [
        {
          "followup_type": "followup",
          "reason_text": "Customer not answering",
          "notes": "Called three times with no response",
          "created_at": "2026-04-30T10:00:00Z"
        }
      ]
    }
  }
}

❌ 422 — Validation Error (Invalid ID)

{
  "status": 422,
  "message": "validation_errors",
  "errors": {
    "orders": [
      "Invalid order ID detected in list."
    ]
  }
}

🛡️ Daily Quotas

🔹 Bulk Get: 15 requests per day per API Key.

📖 Error Dictionary

Comprehensive Guide

Every error response follows the same structure: {"status": int, "message": "error_key", "errors": []}. Below is a dictionary of possible error keys.

🔐 authentication_required

The request is missing the ShippingEyes-Api-Key or ShippingEyes-Api-Secret headers.

🚫 invalid_key

The provided API key does not exist or is disabled.

🔑 invalid_secret

The secret does not match the provided API key.

🌐 ip_forbidden

Your server IP address is not whitelisted for this API key.

🛡️ insufficient_permissions

The API key does not have the required scope (e.g. orders:create) for this endpoint.

⚠️ merchant_inactive

Account Configuration Error: Merchant profile is inactive or missing. Returns a 403 Forbidden.

📝 validation_errors

The request body failed validation. Check the errors array for specific field issues.

🔍 order_not_found

The requested order_id does not exist or does not belong to your account.

⏱️ rate_limit_exceeded

You have exceeded the allowed requests per minute (60/min).

🆔 duplicate_ref_num

An order with the same ref_num already exists in your account.

🛡️ nonce_required

Write operations (POST/PUT/DELETE) require the ShippingEyes-Api-Nonce header.

🛡️ nonce_already_used

The provided Nonce has already been used in the last 10 minutes.

DEBUG

🛠️ Troubleshooting Guide

Facing issues with your integration? Check these common scenarios and their quick fixes.

❌ Problem: 401 Unauthorized

Likely Cause: Incorrect API Key/Secret or IP not whitelisted.

Ensure there are no leading/trailing spaces in your headers.
Check if your server's Public IP matches the one whitelisted in the dashboard.
Verify you are using the correct credentials for the environment (Live vs Test).

⚠️ Problem: 422 Validation Error

Likely Cause: Missing required fields or invalid data types.

Check the errors array in the response body for field-specific details.
Ensure phone numbers follow the international format (e.g., +218...).
Verify that sender_city_id and receiver_city_id exist in the Locations list.

⏱️ Problem: Connection Timeout

Likely Cause: Firewall blocking outgoing requests or slow network.

Ensure your server allows outgoing traffic on port 443 (HTTPS).
Set your client timeout to at least 30 seconds for bulk operations.
Check status.shippingeyes.com for any ongoing maintenance.

✅ Best Practices for Integrations

Recommended

🛡️ Security & Secret Management

Never expose your ShippingEyes-Api-SecretA 64-character private key used to sign requests. Never share this with anyone. in frontend code, mobile apps, or public repositories. All API calls should be made from your Backend Server (Server-to-Server) to keep your credentials secure.

🔄 Mandatory Nonces for Write Operations

To ensure high security, the ShippingEyes-Api-NonceA unique, one-time-use string (like a UUID) to prevent replay attacks and duplicate orders. is mandatory for POST, PUT, and DELETE operations. Requests without a Nonce will be rejected with a 401 nonce_required error.

💾 Cache Location Data

Delivery cities and places change infrequently. We recommend fetching /api/v1/public/locations/cities once a day and caching it on your server to speed up your checkout process.

📈 Handle Rate Limits Gracefully

If you receive a 429 Too Many Requests error, implement an Exponential BackoffA strategy of doubling the wait time between retries to avoid overwhelming the server. strategy.

🏷️ Atomic ID Persistence

Always store the order_idAn opaque, URL-safe encoded string (e.g., 'lejRej') that uniquely identifies a record. (encoded string) returned by our system in your database.

🛡️ Permissions & Scopes

Access Control

Every API Key is assigned specific permissions (scopes). Attempting to access an endpoint without the required scope returns a 403 Forbidden error.

Scope	Access Granted To
`orders:read`	List, search, view order details, and followups history
`orders:create`	Create, update, and delete orders
`tracking:read`	View order tracking timelines and bulk tracking data
`shipping:read`	View shipping prices, services, and delivery locations

⏱️ Rate Limiting

Quota Enforcement

To ensure system stability, the Public API enforces rate limits per API Key and IP address.

Order Operations

Create: 30 req / min

Update: 10 req / 30 min

Delete: 3 req / 5 min

Tracking Module

Single: 5 req / 5 min

Bulk: 15 req / 24 hrs

Locations Module

20 req / 6 hrs

(Recommended TTL: 20 min)

Shipping & Pricing

10 req / 24 hrs

(Semi-static data)

Order Querying

Info: 1 req / min

List: 15 req / hr

Search: 5 req / hr

(High performance endpoints)

Capacity status is returned in the response headers:

Header Metadata (Quotas)

ShippingEyes-RateLimit-Limit: 60
ShippingEyes-RateLimit-Remaining: 59
ShippingEyes-Retry-After: 45 (Only on 429)

❌ 429 — Rate Limit Exceeded

{
  "status": "error",
  "message": "Rate limit exceeded. Too many requests.",
  "meta": {
    "api_version": "1.0.0",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "rate_limit": {
        "limit": 60,
        "window": "1 minute(s)",
        "retry_after": "45s"
    },
    "note": "Check the rate_limit object for your current quota and retry after the specified window."
  }
}

SECURE

Security & Compliance

ShippingEyes is engineered with a forensic-grade security architecture designed to protect sensitive logistics and financial data for enterprise-level operations.

🛡️

Data Encryption

All data in transit is protected via TLS 1.3 encryption. Data at rest is secured using AES-256 military-grade encryption standards, ensuring that sensitive shipment and financial records remain inaccessible to unauthorized parties.

🔒

Access Control

We employ Server-to-Server Authentication. Access is strictly controlled via granular API Keys. Keys can be revoked instantly, and our system enforces a strict IP Whitelisting capability to ensure requests only originate from authorized servers.

🕵️

Forensic Auditing

Every single API request is timestamped and logged with a unique request_id. This provides a complete Audit Trail for compliance and forensic analysis, allowing for deep tracing of data mutations and system interactions.

📜

Enterprise Compliance

Our architecture is built with GDPR-readiness in mind, ensuring data privacy and right-to-be-forgotten protocols are easily implementable. We adhere to high-availability standards to ensure your integration is always operational.

💡 Security Note: Never share your API Secret. ShippingEyes staff will never ask for your secret keys. If you suspect a compromise, revoke your key immediately from the Dashboard.

GUARANTEED

📈 SLA & Performance Commitment

We understand that our API is a critical component of your business operations. ShippingEyes is committed to providing enterprise-grade reliability and performance.

🌐

99.9% Uptime SLA

Our infrastructure is distributed across multiple availability zones to ensure maximum resilience. We guarantee a monthly uptime of 99.9%, backed by our service level agreement.

⚡

High-Speed Execution

We target a sub-150ms average response time for all core API endpoints. Our global edge network ensures low latency for your servers, regardless of their physical location.

🎧

Priority Support

Enterprise partners receive priority access to our core engineering team. We commit to a <4 hour response time for P1 (critical) integration issues.

THE EDGE

⚖️ ShippingEyes vs. Legacy Systems

Why choose ShippingEyes? We've modernized the entire logistics pipeline to eliminate the friction found in traditional shipping platforms.

Feature	Legacy Platforms	ShippingEyes API
Data Sync	Manual Polling / CSV Uploads	Real-time Webhooks (Push)
Security	Shared Passwords / Unencrypted	AES-256 + IP Whitelisting
Financials	Estimated / Delayed Billing	Forensic Real-time Accounting
Latency	1-2 Seconds Average	Sub-150ms Guaranteed
Integration	Weeks / Months	Same-Day Deployment

FUTURE

🚀 Ecosystem Roadmap

Our Vision for 2026

We are constantly expanding the ShippingEyes ecosystem. Here is what we are building next to help your merchants integrate faster than ever.

June 2026

🛍️

Shopify App

One-click installation for all Shopify merchants with auto-syncing.

July 2026

🇸🇦

Salla & Zid Apps

Direct integration for Saudi & Gulf merchants through official App Store plugins.

August 2026

🛒

WooCommerce

Native WordPress plugin for seamless order fulfillment and tracking.

October 2026

🔌

Magento 2

Enterprise-grade extension for complex E-commerce workflows.

"Our goal is to make ShippingEyes the backbone of logistics technology in the region."