Jeebly
POST Scheduled Delivery API • Version 1.0.9

Order Tracking
API Guide

Track the status of your scheduled shipment in real time. Use this API to check where your shipment is at any moment. The response delivers current package status, complete historical milestone events, driver contact details, and Proof of Delivery (POD) image URLs.

Try in API Console
Version: 1.0.9 Method: POST Timezone: UTC Format POD Image Ready
POST v1.0.9
Track Scheduled Shipment

Milestone & Event Audit Endpoint

DEMO / SANDBOX:
https://demo.jeebly.com/customer/track_shipment
PRODUCTION LIVE:
https://myjeebly.jeebly.com/customer/track_shipment
Auth Headers:X-API-KEY, client_key
Request Body:reference_number
Output:application/json (Events)
Jump to Request Body
1

What Is This API?

Use this API to check where your shipment is at any time. The response gives you the current status and a full event history showing every step the package has gone through from creation to delivery.

Each event entry provides comprehensive operational context, including timestamps in UTC, facility/hub names, driver names and telephone numbers, COD collect amounts, and links to photographic Proof of Delivery (POD) captured upon drop-off.

API Details & Environments

Property Value Action
Request URL (Demo) https://demo.jeebly.com/customer/track_shipment
Request URL (Production) https://myjeebly.jeebly.com/customer/track_shipment
HTTP Method POST —
Content-Type application/json —
Timezone Standard Notice

Note: All event timestamps returned by the Tracking API are expressed in UTC (Coordinated Universal Time) in ISO-8601 format (e.g. 2024-04-02T11:38:21Z). Please convert to Gulf Standard Time (GST, UTC+4) when presenting to end customers in the UAE.

2

Authentication Headers

Every request submitted to the Tracking API must authenticate with your merchant API security tokens. Requests with invalid or missing credentials return a 400 Bad Request with an error explanation.

Header Name Description Required
X-API-KEY Your API security key assigned to your merchant account. Yes
client_key Your Jeebly customer account key. Yes
Content-Type Must always be set to application/json. Yes
Need to obtain or inspect your merchant API keys?
Get Your Keys
3

Request Body

The tracking request payload requires exactly one field with your shipment AWB number:

Field Name Type Description Example Required
reference_number String The AWB / tracking number of the scheduled order you want to track. "JBP104044" Yes
AWB Tracking Identifier Reference

Pass the reference number returned in the response when you created the shipment via the Create Shipment API (e.g. "JBP104044" or "JB304036").

4

Sample Request

Below is a complete request example demonstrating how to poll tracking information across multiple programming languages: 

curl --location 'https://demo.jeebly.com/customer/track_shipment' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'client_key: YOUR_CLIENT_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "reference_number": "JBP104044"
}'
{
  "reference_number": "JBP104044"
}
const myHeaders = new Headers();
myHeaders.append("X-API-KEY", "YOUR_API_KEY");
myHeaders.append("client_key", "YOUR_CLIENT_KEY");
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({
  "reference_number": "JBP104044"
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://demo.jeebly.com/customer/track_shipment", requestOptions)
  .then((response) => response.json())
  .then((result) => {
    if (result.success === "true" && result.Tracking) {
      console.log("Current Status:", result.Tracking.last_status);
      console.log("Latest Event:", result.Tracking.events[0]);
    } else {
      console.error("Tracking Error:", result.message);
    }
  })
  .catch((error) => console.error("Network error:", error));
import requests
import json

url = "https://demo.jeebly.com/customer/track_shipment"

payload = json.dumps({
  "reference_number": "JBP104044"
})

headers = {
  'X-API-KEY': 'YOUR_API_KEY',
  'client_key': 'YOUR_CLIENT_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
data = response.json()

if response.status_code == 200 and data.get("success") == "true":
    tracking = data.get("Tracking", {})
    print(f"AWB: {tracking.get('reference_no')} | Status: {tracking.get('last_status')}")
    for ev in tracking.get("events", []):
        print(f" - [{ev.get('event_date_time')}] {ev.get('status')}: {ev.get('desc')}")
else:
    print("Tracking failed:", data.get("message"))
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.jeebly.com/customer/track_shipment',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(['reference_number' => 'JBP104044']),
  CURLOPT_HTTPHEADER => array(
    'X-API-KEY: YOUR_API_KEY',
    'client_key: YOUR_CLIENT_KEY',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

$result = json_decode($response, true);
if ($httpCode === 200 && ($result['success'] ?? '') === 'true') {
    $tracking = $result['Tracking'];
    echo "AWB: " . $tracking['reference_no'] . " | Status: " . $tracking['last_status'] . PHP_EOL;
} else {
    echo "Tracking Error: " . ($result['message'] ?? 'Unable to retrieve tracking info');
}
Test this live tracking query directly in the interactive console:
Test in API Console
5

Success Response (200 OK) & Tracking Schema

When tracking information is retrieved successfully, the API returns an HTTP 200 OK status code with a Tracking object containing package metadata and an array of all milestone updates ordered from most recent to oldest:

200 OK application/json • Full Response Payload 
{
  "success": "true",
  "Tracking": {
    "reference_no": "JBP104044",
    "customer_reference_number": "",
    "last_status": "Delivered",
    "pickup_date": "2024-04-03",
    "booking_date": "2024-04-02",
    "booking_time": "15:36",
    "events": [
      {
        "status": "Delivered",
        "desc": "Consignment is delivered",
        "hub_name": "Jeebly Warehouse",
        "event_date_time": "2024-04-02T11:38:21Z",
        "cod_amount": "0",
        "shipper_phone": "+971 123456789",
        "recipient_phone": "+9712345678",
        "rider_code": "JI01267",
        "rider_name": "John Dae",
        "pod_image": "https://shipsy-demo.s3.amazonaws.com/jeebly/poc/2024-04-02/delivery/poc_xccnst_1712057918050",
        "signature_image": null,
        "failure_reason": null
      },
      {
        "status": "Out For Delivery",
        "desc": "Consignment is out for delivery",
        "hub_name": "Jeebly Warehouse",
        "event_date_time": "2024-04-02T11:37:44Z",
        "cod_amount": "0",
        "shipper_phone": "+971 123456789",
        "recipient_phone": "+9711234567",
        "rider_code": "",
        "rider_name": "",
        "pod_image": null,
        "signature_image": null,
        "failure_reason": null
      },
      {
        "status": "Inscan At Hub",
        "desc": "Consignment has been inscanned at hub",
        "hub_name": "Jeebly Warehouse",
        "event_date_time": "2024-04-02T11:37:20Z",
        "cod_amount": "0",
        "shipper_phone": "+971123456789",
        "recipient_phone": "+9713456789",
        "rider_code": "",
        "rider_name": "",
        "pod_image": null,
        "signature_image": null,
        "failure_reason": null
      },
      {
        "status": "Pickup Completed",
        "desc": "Consignment has been picked up",
        "hub_name": "Jeebly Warehouse",
        "event_date_time": "2024-04-02T11:36:48Z",
        "cod_amount": "0",
        "shipper_phone": "+97123456789",
        "recipient_phone": "+9713456789",
        "rider_code": "",
        "rider_name": "",
        "pod_image": null,
        "signature_image": null,
        "failure_reason": null
      },
      {
        "status": "Pickup Scheduled",
        "desc": "Consignment Softdata Uploaded",
        "hub_name": "Jeebly Warehouse",
        "event_date_time": "2024-04-02T11:36:31Z",
        "cod_amount": "0",
        "shipper_phone": "+9713 456 7890",
        "recipient_phone": "+9713456789",
        "rider_code": "",
        "rider_name": "",
        "pod_image": null,
        "signature_image": null,
        "failure_reason": null
      },
      {
        "status": "Pickup Scheduled",
        "desc": "Consignment pickup_scheduled",
        "hub_name": "Jeebly Warehouse",
        "event_date_time": "2024-04-02T11:36:31Z",
        "cod_amount": "0",
        "shipper_phone": "+9713 456 7890",
        "recipient_phone": "+9713456789",
        "rider_code": "",
        "rider_name": "",
        "pod_image": null,
        "signature_image": null,
        "failure_reason": null
      }
    ]
  }
}
Current Status: Delivered
AWB: JBP104044
Updated in UTC
Delivered
2024-04-02 11:38:21 UTC

Consignment is delivered by John Dae (Rider JI01267). Hub: Jeebly Warehouse.

View Proof of Delivery (POD) Image →
Out For Delivery
2024-04-02 11:37:44 UTC

Consignment is out for delivery with courier.

Inscan At Hub
2024-04-02 11:37:20 UTC

Consignment has been inscanned at hub (Jeebly Warehouse).

Pickup Completed
2024-04-02 11:36:48 UTC

Consignment has been picked up from shipper.

Pickup Scheduled
2024-04-02 11:36:31 UTC

Consignment Softdata Uploaded & pickup scheduled.

Top-Level Tracking Object Fields Explained

Field Description Type / Example
reference_no The Jeebly tracking number (AWB number). String "JBP104044"
customer_reference_number Your store order/reference number (Only if this was provided at the time the shipment was created). String "ORD-99214"
last_status The most recent status of the shipment (e.g. "Delivered", "Out For Delivery"). String "Delivered"
pickup_date The date the package was (or will be) picked up. String (YYYY-MM-DD) "2024-04-03"
booking_date The date the order was created in the system. String (YYYY-MM-DD) "2024-04-02"
booking_time The time the order was created. String (HH:mm) "15:36"
events A list of all status updates, from most recent to oldest. Array of Objects

Event Array Object Schema

Event Field Type Description Example
status String Primary milestone identifier. "Delivered"
desc String Human-readable description of milestone activity. "Consignment is delivered"
hub_name String Facility or warehouse where event was registered. "Jeebly Warehouse"
event_date_time String (UTC) Exact event timestamp in ISO-8601 UTC format. "2024-04-02T11:38:21Z"
cod_amount String Cash On Delivery collection value at this step. "0"
shipper_phone String Contact phone number of pickup sender. "+971 123456789"
recipient_phone String Contact phone number of receiver. "+9712345678"
rider_code String Courier rider identifier assigned to delivery leg. "JI01267"
rider_name String Name of the active courier driver. "John Dae"
pod_image String (URL) / null Direct URL to the Proof of Delivery photo on Amazon S3. "https://shipsy-demo.s3.../poc_..."
signature_image String / null Digital signature image data if collected upon delivery. null
failure_reason String / null Operational rejection or delivery exception code if attempt failed. null
6

Error Responses (400 Bad Request)

A 400 Bad Request response is returned when the tracking request cannot be processed due to invalid formatting, incorrect API keys, or an unrecognized AWB reference number:

400 1. If the format is wrong
Malformed JSON or syntax error 
{
  "success": "false",
  "message": "Invalid JSON format"
}
400 2. If the API Key is not valid
X-API-KEY wrong, revoked, or missing 
{
  "success": "false",
  "message": "Invalid API Token"
}
400 3. If the customer Key is not valid
client_key wrong or missing 
{
  "success": "false",
  "message": "Invalid Customer Key"
}
400 4. If the consignment is invalid
reference_number not found in database 
{
  "success": "false",
  "message": "Invalid Shipment Number"
}
7

Troubleshooting & Resolution Matrix

Use this table to diagnose and resolve errors when tracking a scheduled order:

Error Message What It Means How to Fix It
Invalid JSON format The request body is not valid JSON. Check the format of your request, closing braces, and quotation marks around "reference_number".
Invalid API Token Your API key is wrong, revoked, or missing. Check your X-API-KEY header value and ensure no extra whitespaces were copied.
Invalid Customer Key Your client key is wrong or missing. Check your client_key header and confirm it matches your Jeebly merchant account.
Invalid Shipment Number The AWB tracking number you entered does not exist in the system. Double-check the reference number from your order creation response. Make sure you are not passing an internal store ID.
Coordinated Universal Time (UTC) Standard

Note: All event timestamps in the tracking response are provided in UTC (Coordinated Universal Time). When rendering milestone tracking timelines to customers in the UAE, add +4 hours for GST (Gulf Standard Time).

8

Milestone Lifecycle & POD Verification

Consignments transition through standardized lifecycle milestones as they move through the Jeebly logistics network:

1. Pickup Scheduled

Consignment softdata uploaded. The shipment is booked in the dispatch queue.

2. Pickup Completed

Courier rider arrived at shipper premises and scanned the package barcode into custody.

3. Out For Delivery

Sorted at hub and loaded onto delivery rider vehicle for final-mile drop-off.

4. Delivered

Consignment handed over. Proof of Delivery (POD) photo and timestamp recorded.

Accessing Proof of Delivery (POD) Photos

When the final status is Delivered, the pod_image field contains a direct secure URL to the photograph taken by the courier rider at the consignee address. You can embed this link directly in your customer support portal or store order history.

Table of Contents
Interactive Console Back to top