On This Page ×

📋

↑

📦 ShippingEyes Ecosystem Official Website 🌐 Quick Start 🚀

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..." \
  -H "ShippingEyes-Api-Nonce: 123e4567-e89b-12d3-a456-426614174000" \
  -d '{
    "ref_num": "ORD-10055",
    "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,
      "shipping_cost_type": 1,
      "payment_type": "cash"
    }
  }'

🐘 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...',
        'ShippingEyes-Api-Nonce'  => uniqid('nonce_'),
        'Accept'       => 'application/json',
    ],
    'json' => [
        'ref_num' => 'ORD-10055', // 🛡️ Prevent duplicate orders
        '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,
            'shipping_cost_type' => 1,
            'payment_type' => 'cash'
        ]
    ]
]);

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

🐘 PHP (Native cURL)

<?php

$payload = [
    'ref_num' => 'ORD-10055', // 🛡️ Prevent duplicate orders
    '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,
        'shipping_cost_type' => 1,
        'payment_type' => 'cash'
    ]
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://your-domain.com/api/v1/public/orders/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
$nonce = uniqid('nonce_');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "ShippingEyes-Api-Key: se_live_...",
    "ShippingEyes-Api-Secret: your_secret...",
    "ShippingEyes-Api-Nonce: $nonce",
    "Content-Type: application/json",
    "Accept: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

📦 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...',
            'ShippingEyes-Api-Nonce': require('crypto').randomUUID(),
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        },
        body: JSON.stringify({
            ref_num: 'ORD-10055', // 🛡️ Prevent duplicate orders
            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, shipping_cost_type: 1, payment_type: 'cash' }
        })
    });
    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	Order Creation	Order successfully created by the merchant. Code: OC	Creation
5	Pickup Collected	Package has been collected from the merchant. Code: PUC	Pickup Operations
12	Receive In Branch	Package arrived and received at the destination branch. Code: RIB	Branch Transfer
14	Cancel	Order has been cancelled before final processing. Code: C	Exceptions
19	IN Preparation	Order is being prepared and packed for dispatch. Code: INP	Delivery Preparation
22	Out for delivery	Delegate is currently out delivering the package to the customer. Code: OFD	Final Mile
30	Delivered	Package successfully delivered to the customer. Code: D	Final Delivery Status
35	Returned	Order could not be delivered and has been returned. Code: RD	Returns Workflow

🔢 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

🚨 Security & Abuse Policy

Shipping Eyes employs advanced Web Application Firewalls (WAF) and AI-driven anomaly detection to safeguard logistics integrity. Automated data scraping, payload fuzzing, or any deliberate attempts to circumvent API limitations are strictly prohibited.

Consequences of Abuse: Any detection of malicious behavior, suspicious traffic patterns, or systemic abuse will trigger an immediate, automated, and permanent IP ban, along with the permanent revocation of your API credentials without prior notice.

How Authentication Works

The Public API utilizes Server-to-Server authentication using 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://your-domain.com/api/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://your-domain.com/api/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://your-domain.com/api/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://your-domain.com/api/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.status_updated

Real-time tracking for every step of the journey.

📦

order.status_bulk_updated

Sync mass updates instantly when multiple orders change statuses.

💬

order.followup_recorded

Stay informed when drivers or agents add notes.

💰

catalog.shipping_pricing_updated

Automatically sync prices when your shipping package updates.

⚙️

platform.configuration_updated

Instantly adapt to global platform setting changes.

🧪

webhook.test_ping

Test your endpoint integration directly from the dashboard.

🚀 Why Shipping Eyes 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.

⚡

Lightning Fast Delivery Guarantee

Notifications arrive instantly in real-time. In the absolute worst-case network scenario, the maximum delay is strictly guaranteed to be under 60 seconds.

🔐 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.

🛡️ Custom Security Headers: If your server (Firewall / API Gateway) requires specific security headers (like Authorization or x-api-key) to allow incoming traffic, you can define up to 3 Custom Headers directly from your webhook settings in the dashboard. We will automatically attach them to every webhook request sent to your endpoint.

⚠️ Note: You cannot override reserved system headers (e.g., User-Agent, Content-Type, Accept, or any ShippingEyes-* headers). Any custom header matching a reserved name will be silently ignored to preserve payload integrity.

📑 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.
ShippingEyes-Webhook-Version	1.0.0	The current version of the Webhook API.
User-Agent	`ShippingEyes-Webhook/1.0` (or `ShippingEyes-Webhook-Tester/1.0` for test events)	Identifies the webhook dispatcher client. Ensure your firewall allows both if restricted by User-Agent.
Content-Type	application/json	The media type of the payload format.
Accept	application/json	The media type expected in response (if any).

🛠️ Webhook Delivery Architecture

Our webhook engine is built for reliability and high performance:

Asynchronous Delivery & SLA: Events are processed asynchronously to ensure our core API remains fast.
• Transactional Events (e.g., order updates) are delivered instantly.
• Bulk Fan-out Events (e.g., catalog or configuration updates sent to many merchants) may take a few minutes to arrive during mass updates.
Retry Policy: If your server is down or returns a non-2xx status, we automatically retry the delivery up to 5 times using a strict exponential backoff strategy.
⏱️ Exact Retry Schedule:
Attempt 1: Immediately ➔ Attempt 2: After 1 minute ➔ Attempt 3: After 5 minutes ➔ Attempt 4: After 15 minutes ➔ Attempt 5: After 60 minutes
Auto-Disable & Re-enabling: To protect our system, webhooks that fail for 10 consecutive attempts are automatically disabled. If disabled, you must resolve the issue on your endpoint and manually re-enable the webhook from your Merchant Dashboard. Ensure your endpoint is stable and returns a 2xx status promptly.
Idempotency (Crucial): Because of network retries, your endpoint might occasionally receive the exact same webhook payload more than once. You MUST use the request_id provided in the meta object as an idempotency key to ensure you do not process the same event twice in your system.

🚀

🔥 Hot Feature

⚡ Customizable Rate Limiting (Throttling)

By default, we limit webhook dispatches to a maximum of 30 requests per minute to protect your server from traffic spikes. If the volume of generated events exceeds this limit, the excess events will be safely paused and queued (without failing) and delivered as soon as your rate limit window resets.

💡

Pro Tip for Merchants: You can fully control and customize this Rate Limit (from 10 up to 1000 requests/minute) directly from your Merchant Panel ➔ Webhook Settings to perfectly match your server's capacity!

⚠️ Strict Timeout:
Your server MUST process the request and return an HTTP 2xx response within 5 seconds. If it takes longer, we will drop the connection, consider it a failure, and initiate a retry.

✅ Acknowledging Receipt (Required):
To successfully acknowledge the receipt of the webhook, your server MUST return a JSON response containing {"success": true} along with an HTTP 200 (OK) status code. If this exact JSON payload is not returned, our system will consider the delivery as failed and will automatically initiate the retry sequence.

⛔ No Redirects Followed:
For security and data integrity reasons, our dispatcher will NOT follow HTTP redirects (e.g., 301, 302). You must provide the absolute, final destination URL. If your server redirects the request, the delivery will fail.

🌐 URL Security Requirements (SSRF Protection):

Your webhook URL MUST start with https://.
Localhost, private network IPs (e.g., 127.0.0.1), and unresolvable domains are strictly blocked. For local testing during development, please use a secure public tunnel service like Ngrok.

🌍 IP Whitelisting:
If your server uses a strict firewall, ensure you whitelist our static IP addresses to allow incoming webhooks. Please contact our technical support to obtain the list of our current outbound IP addresses.

🔐 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'] ?? '';
$timestamp = (int) ($_SERVER['HTTP_SHIPPINGEYES_WEBHOOK_TIMESTAMP'] ?? 0);

// Prevent Replay Attacks
if (time() - $timestamp > 300) {
    http_response_code(400);
    die('Expired');
}

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

if (hash_equals($expected, $signature)) {
    // ✅ Valid request
    $data = json_decode($payload, true);
    
    // Process your event here...

    // 🚀 Acknowledge Receipt
    header('Content-Type: application/json');
    http_response_code(200);
    echo json_encode(['success' => true]);
    exit;
} else {
    // ❌ Invalid signature
    http_response_code(401);
}

📦 Node.js (Express)

// ⚠️ IMPORTANT: This route must be placed BEFORE any global app.use(express.json())
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
    const signature = req.headers['shippingeyes-webhook-signature'] || '';
    const timestamp = parseInt(req.headers['shippingeyes-webhook-timestamp'] || '0', 10);
    const secret = 'your_webhook_secret_here';

    // Prevent Replay Attacks
    if (Date.now() / 1000 - timestamp > 300) {
        return res.status(400).send('Expired');
    }

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

    try {
        const calculatedBuffer = Buffer.from(expected, 'hex');
        const providedBuffer = Buffer.from(signature.replace('sha256=', ''), 'hex');

        // MUST check length before timingSafeEqual to prevent Node.js crashes!
        if (calculatedBuffer.length !== providedBuffer.length || 
            !crypto.timingSafeEqual(calculatedBuffer, providedBuffer)) {
            throw new Error('Invalid signature');
        }
    } catch (error) {
        return res.status(401).send('Unauthorized');
    }

    // ✅ Valid request. Safely parse the Buffer to JSON.
    const payload = JSON.parse(req.body.toString());
    console.log('Event:', payload.meta.event);
    
    // Process your event here...

    // 🚀 Acknowledge Receipt
    res.status(200).json({ success: true });
});

📅 Event Catalog

The following events are currently supported by the ShippingEyes platform:

🏓 ping

A system event sent when you test your webhook endpoint from the Merchant Dashboard. Use this to verify your signature validation logic.

📦 Payload Example

{
  "status": 200,
  "message": "webhook_event",
  "meta": {
    "api_version": "1.0.0",
    "event": "ping",
    "timestamp": "2026-05-04T15:30:00Z",
    "request_id": "990i2800-i62f-8508-e14a-880099884444"
  },
  "data": {
    "message": "This is a test ping from ShippingEyes Webhook Tester.",
    "test": true
  }
}

🔔 order.status_updated

Triggered whenever an order's status changes (e.g., from "New" to "Out for Delivery").
Note: The delegate object is only included in the payload when the order status is 21 (To Delegate), 22 (Out for delivery), 23 (Postponed with delegate), or 34 (Returned With Delegate). Always check if it exists before accessing its properties to avoid Null Reference errors.
💡 Pro Tip (Data Types & Mapping): order_snum can be a String or Integer. order_status is always an Integer. We highly recommend using the integer order_status (e.g., 22) to map statuses in your database instead of relying on the localized status_name string.

📦 Payload Example

{
  "status": 200,
  "message": "webhook_event",
  "meta": {
    "api_version": "1.0.0",
    "event": "order.status_updated",
    "timestamp": "2026-05-04T15:30:00Z",
    "request_id": "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",
    "delegate": {
      "name": "Adam",
      "phone": "0900000000"
    }
  }
}

📦 order.status_bulk_updated

Triggered whenever multiple orders' statuses are updated simultaneously in bulk.
Note: The delegate object is only included in the payload when the order status is 21 (To Delegate), 22 (Out for delivery), 23 (Postponed with delegate), or 34 (Returned With Delegate). Always check if it exists before accessing its properties to avoid Null Reference errors.
💡 Pro Tip (Data Types): orders_snums is an Array of Strings/Integers. order_status is always an Integer.

📦 Payload Example

{
  "status": 200,
  "message": "webhook_event",
  "meta": {
    "api_version": "1.0.0",
    "event": "order.status_bulk_updated",
    "timestamp": "2026-05-04T15:30:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440001"
  },
  "data": {
    "order_status": 22,
    "status_name": "Out for delivery",
    "orders_snums": [
      "SHP-10042",
      "SHP-10043"
    ],
    "updated_at": "2026-05-04 15:30:00",
    "delegate": {
      "name": "Adam",
      "phone": "0900000000"
    }
  }
}

💬 order.followup_recorded

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

📦 Payload Example

{
  "status": 200,
  "message": "webhook_event",
  "meta": {
    "api_version": "1.0.0",
    "event": "order.followup_recorded",
    "timestamp": "2026-05-04T16:00:00Z",
    "request_id": "660f9500-f39c-52d5-b817-557766551111"
  },
  "data": {
    "order_snum": 10042,
    "followup_type": "followup",
    "reason_name": "Customer request",
    "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

{
  "status": 200,
  "message": "webhook_event",
  "meta": {
    "api_version": "1.0.0",
    "event": "catalog.shipping_pricing_updated",
    "timestamp": "2026-05-04T16:30:00Z",
    "request_id": "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

{
  "status": 200,
  "message": "webhook_event",
  "meta": {
    "api_version": "1.0.0",
    "event": "platform.configuration_updated",
    "timestamp": "2026-05-04T16:30:00Z",
    "request_id": "880h1700-h51e-74f7-d039-779988773333"
  },
  "data": {
    "message": "Orders creation settings have been updated",
    "updated_at": "2026-05-04T16:30:00Z"
  }
}

👤 Delegate Webhook Statuses

The delegate object (containing the driver's name and phone number) is only included in the webhook payload when the order's status matches one of the following integer codes:

Integer Code	Status Name (English)
21	To Delegate 👤 Includes Delegate Info
22	Out for delivery 👤 Includes Delegate Info
23	postponed with delegate 👤 Includes Delegate Info
34	Returned With Delegate 👤 Includes Delegate Info

📍 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.
enable_delivery_inclusion_toggle	bool	Controls whether the `amount_type` parameter is active. When `true`, the client may send `amount_type = 1` (amount includes delivery) or `0` (excludes delivery). When `false`, the server enforces `amount_type = 0` regardless of the value sent — the order amount always excludes delivery cost.
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,
    "enable_delivery_inclusion_toggle": false,
    "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 complete list 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 ensures strict data integrity during processing.

🧹 Auto-Sanitization Notice: Please note that all submitted text fields (like names, addresses, and descriptions) run through our AI Sanitizer. Emojis (e.g., 🚚, 📍, 😀) and unapproved HTML are strictly stripped, and excessive punctuation (like // or ,,) is automatically cleaned. Read our Global Sanitization Policy here.

🛡️ Strict Location Validation: Shipping Eyes applies high-speed, in-memory validation on destination IDs before processing the order. If an inactive or invalid to_city or to_place is provided, the API request is instantly rejected with a 422 Unprocessable Entity error to protect logistics integrity.

{
  "status": "error",
  "message": "invalid_city",
  "errors": {
    "recipient.to_city": [
      "The provided \"to_city\" does not match any active city in Shipping Eyes system."
    ]
  },
  "meta": {
    "api_version": "1.0.0",
    "timestamp": "2026-06-13T10:45:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Note: A similar error with message invalid_place is returned for an invalid area, and invalid_place_for_city if the area does not belong to the selected city.

📦 Request Body (JSON)

Filter:

Field	Type	Required	Description
🔵 Shipping Service & Reference
ref_num	string	❌	Merchant's internal reference number (min 3, max 20 chars). (Highly Recommended: Used for duplicate protection).
shipping_service	string	✅	Encoded shipping service ID. 💡 Alias: `shipment_info.service_id` is also accepted.
👤 Recipient Information
recipient.name	string	✅	Full name (min 3, 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 🛡️ Strict Validation: Must be a valid active ID. See invalid_city error.
recipient.to_place	string	❌	Encoded destination Place/Zone ID. ⚙️ Logic: Defaults to `"0"` if empty, enabling generic city delivery. 🛡️ Strict Validation: Must be a valid active ID. See invalid_place error. 🔗 Relation Validation: Must geographically belong to `to_city`. See invalid_place_for_city error.
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 (min 3, max 200 chars)
recipient.address_marker	string	❌	Address landmark/marker (min 6, max 100 chars)
recipient.building_no	string	❌	Building/House number (min 1, max 10 chars)
recipient.role_no	string	❌	Floor number (min 1, max 10 chars)
recipient.apartment_no	string	❌	Apartment/Suite number (min 1, max 10 chars)
📦 Shipment Information
shipment_info.description	string	✅	Detailed item description (min 2, max 150 chars). Required/Nullable based on account config.
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	⚠️ Conditional	Required if `order_type` is `replacement` (min 2, max 150 chars).
shipment_info.replacement_order	string	❌	Original order number 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 (min 3, max 150 chars)
📏 Dimensions & ⚖️ Weights
shipment_info.dimensions	object	❌	Package dimensions: `{length, width, height}` (cm)
shipment_info.weights.actual_weight	number	❌	Physical weight in kilograms. ⚠️ Constraint: Must be `>= 0`.
shipment_info.weights.total_weight	number	🔄 Auto	Total weight used for pricing. 🔄 Server-Calculated — computed as max(actual, volumetric).
shipment_info.weights.extra_weight	number	🔄 Auto	Weight exceeding the base allowance. 🔄 Server-Calculated — computed automatically.
shipment_info.weights.extra_weight_cost	number	🔄 Auto	Additional cost for extra weight. 🔄 Server-Calculated — computed from price per kilo.
💰 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	✅ Yes	Method: `cash`, `card`, `prepaid`
financial_info.main_delivery_cost	number	🔄 Auto	Base delivery cost. 🔄 Server-Calculated — fetched from merchant's price package.
financial_info.delivery_cost	number	🔄 Auto	Final shipping fee. 🔄 Server-Calculated — base cost + extra weight cost.
financial_info.shipping_cost_type	integer	✅	Payment attribution for shipping fee: `0`: Customer Pays (Added to recipient's COD amount) `1`: Merchant Pays (Deducted from merchant wallet) `3`: Split Payment (Distributed between parties) ⚠️ Will return 422 Validation Error if Split Cost is disabled in system config.
financial_info.customer_will_pay	number	⚠️	Recipient's share of shipping fee. ⚠️ Required if `shipping_cost_type` is `3` (Split Cost). Defines how much the customer pays.
financial_info.sender_will_pay	number	🔄 Auto	Sender's share of shipping fee (split). 🔄 Server-Calculated.
financial_info.total	number	🔄 Auto	Grand total (Amount + Delivery). 🔄 Server-Calculated.
financial_info.cod	number	🔄 Auto	Cash On Delivery amount to collect at door. 🔄 Server-Calculated.
financial_info.with_cash_difference	string	⚠️ Conditional	Required if `order_type` is `replacement` or `recovery`. Values: `yes` or `no`.
financial_info.cash_difference_type	string	⚠️ Conditional	Required if `with_cash_difference` = `yes`. Values: `collection` (extra) or `payment` (refund).
financial_info.collection_amount	number	❌	Specific extra amount to collect
financial_info.payment_amount	number	⚠️ Conditional	Required if `cash_difference_type` = `payment` (must not be 0). Amount to refund to recipient.

🔍 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 null instead of empty strings "".
🔹 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,
    "allow_opening": 1,
    "breakable": 0,
    "notes": "Handle with extreme care",
    "dimensions": {
      "length": "30",
      "width": "20",
      "height": "10"
    },
    "weights": {
      "actual_weight": "1.5"
    }
  },
  "financial_info": {
    "amount": 250,
    "amount_type": 1,
    "payment_type": "cash",
    "shipping_cost_type": 1
  }
}

✅ 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)."
  }
}

⚠️ 409 — Conflict (Duplicate Order)

Note: The system returns a 409 Conflict status when a duplicate order is detected within the last 10 days. Developers should check the message field for order_exists_duplicate.

{
  "status": "error",
  "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.

🛡️ Strict Location Validation: Updating the recipient's city or place is subject to the same strict high-performance validation as order creation. Providing an inactive or invalid to_city or to_place will instantly reject the request with a 422 Unprocessable Entity 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 highly optimized architecture to resolve all related entities efficiently.

⏱️ 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.

💡 Pro Tip: Webhooks are Highly Recommended!
We strongly recommend using Webhooks instead of continuous polling. Webhooks allow you to receive real-time tracking updates instantly when an event occurs, which significantly reduces server load and accelerates the synchronization process.

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

Full Reference

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.

📍 invalid_city

The provided to_city does not match any active city. Returns a 422 Unprocessable Entity.
💡 Solution: Fetch active IDs from the Locations Module.

🏘️ invalid_place

The provided to_place does not match any active place. Returns a 422 Unprocessable Entity.
💡 Solution: Fetch active IDs from the Locations Module.

🔗 invalid_place_for_city

The provided to_place does not belong to the selected to_city. Returns a 422 Unprocessable Entity.
💡 Solution: Ensure the place you provide is geographically linked to the city.

📝 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.

🧹 Global Data Sanitization Policy

To ensure strict compatibility with courier thermal printers and security, our API automatically applies a Universal Sanitization Policy to all submitted strings. Please note:

🚫 Zero HTML Tolerance: All submitted fields (including notes and descriptions) are strictly stripped of HTML tags. Do not send formatted text like <b> or <ul> as it will be destroyed to plain text.
🚫 Emoji Stripping: Emojis (e.g., 🚚, 📍, 😀) cause fatal encoding errors on courier thermal printers. Our engine forcefully strips all emojis. Please do not send them.
🧹 Smart Formatting: Redundant punctuation (like //, ,,, /*) is normalized into clean separators (e.g., - ).
✂️ Edge Trimming: Trailing spaces or punctuation marks at the beginning or end of strings are automatically trimmed.

🛡️ 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 runs on a forensic-grade security stack built for enterprise logistics and financial data.

🛡️

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

Our API is a critical part of your stack. We deliver enterprise-grade uptime 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

Official WordPress plugin for direct 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."