Quickstart

You need a client_id and client_secret for your merchant account. They are issued from the DropHub console — a credential cannot mint its successor, so there is no API for creating one.

Get a token

BASE_URL="https://api-test.drop-hub.com"

ACCESS_TOKEN=$(curl -s -X POST "$BASE_URL/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials | jq -r .access_token)

The token is a short-lived JWT. Cache it and reuse it until shortly before expires_in elapses — see Authentication.

Create a shipment

An order reference, where to collect, where to deliver, and who receives it. Nothing else is required.

curl -s -X POST "$BASE_URL/v2/external/shipments" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "reference": "ORDER-1042",
        "pickup":      { "latitude": 24.7136,   "longitude": 46.6753 },
        "destination": { "latitude": 24.774265, "longitude": 46.738586 },
        "recipient":   { "name": "Noura", "mobile": "0551234567" }
      }' > shipment.json

SHIPMENT_ID=$(jq -r .id shipment.json)

201 means created. 200 means DropHub already had this order and you are seeing the original shipment — your reference is the idempotency key.

{
  "id": "0198f7c0-7f51-7000-8000-000000000001",
  "reference": "ORDER-1042",
  "status": "CREATED",
  "trackingUrl": "/track/jhJ4hVsHM7APbKpYKg3f7w4m2fC0ZLDm7KqTKi2B1zA",
  "codAmount": null,
  "createdAt": "2026-08-27T06:00:00Z",
  "version": 1
}

trackingUrl is the customer-facing link. It is minted automatically — send it to your buyer.

Do this once, not per shipment. The signing secret is returned exactly once.

curl -s -X POST "$BASE_URL/v2/external/webhook" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://merchant.example/webhooks/drophub"}'

Omitting events subscribes you to all seven. Store signingSecret immediately — see Webhooks for how to verify a delivery.

Follow the shipment

Webhooks are the primary mechanism. Poll only when you need a snapshot on demand:

curl -s "$BASE_URL/v2/external/shipments/$SHIPMENT_ID/tracking" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

See Tracking for locationStatus and the polling interval the server asks you to honour.

Build against the sandbox at https://api-test.drop-hub.com and certify there before pointing at production. Credentials are not interchangeable between the two — see Environments.

Shipments

Parcel details, COD, saved pickups, and pickup windows.

Cancellation

When a shipment can still be called back.

Getting Started

Authentication

Shipments

Events

Request semantics

API reference

Next

Shipments

Cancellation

​Next

Shipments

Cancellation

Next