Create one shipment from a merchant reference and two location pins

curl --request POST \
  --url https://api-test.drop-hub.com/v2/external/shipments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reference": "ORDER-1042",
  "pickup": {
    "latitude": 24.7136,
    "longitude": 46.6753
  },
  "destination": {
    "latitude": 24.774265,
    "longitude": 46.738586
  },
  "recipient": {
    "name": "Noura",
    "mobile": "0551234567"
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "status": "CREATED",
  "trackingUrl": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "version": 1,
  "codAmount": 1
}

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "status": "CREATED",
  "trackingUrl": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "version": 1,
  "codAmount": 1
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/authentication-required",
  "title": "Authentication required",
  "status": 401,
  "detail": "Authentication is required for this resource.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "AUTHENTICATION_REQUIRED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

POST

external

shipments

curl --request POST \
  --url https://api-test.drop-hub.com/v2/external/shipments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reference": "ORDER-1042",
  "pickup": {
    "latitude": 24.7136,
    "longitude": 46.6753
  },
  "destination": {
    "latitude": 24.774265,
    "longitude": 46.738586
  },
  "recipient": {
    "name": "Noura",
    "mobile": "0551234567"
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "status": "CREATED",
  "trackingUrl": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "version": 1,
  "codAmount": 1
}

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "status": "CREATED",
  "trackingUrl": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "version": 1,
  "codAmount": 1
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/authentication-required",
  "title": "Authentication required",
  "status": 401,
  "detail": "Authentication is required for this resource.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "AUTHENTICATION_REQUIRED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

{
  "type": "https://api.drop-hub.com/problems/access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "Access to this resource is denied.",
  "instance": "/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
  "code": "ACCESS_DENIED",
  "timestamp": "2026-08-22T18:30:00Z",
  "correlationId": "018f2d8a-1f00-7000-8000-000000000207",
  "requestId": "018f2d8a-1f00-7000-8000-000000000208"
}

Authorizations

Authorization

string

header

required

OAuth 2.0 client-credentials flow for external machine-to-machine integrations.

Headers

Idempotency-Key

string

Optional. Retry safety is handled for you: when this header is absent DropHub derives the key from the reference you already send — the order number on a shipment create, the shipment id on a cancel — scoped to your merchant account. Two calls naming the same order are treated as one submission and the second returns the original result. Send your own key only if you want to control the replay window yourself; an explicit key always wins.

Required string length: 16 - 128

Example:

"merchant-order-20260822-0001"

Body

application/json

reference

string

required

Merchant order/reference number and default idempotency key.

Required string length: 1 - 128

pickup

object

required

Use either a saved pickup code or a coordinate pin.

Option 1
Option 2

Show child attributes

destination

object

required

Show child attributes

recipient

object

required

Show child attributes

parcel

object

Show child attributes

codAmount

number<decimal>

Omit for prepaid shipments; currency is SAR.

Must be a multiple of 0.01

pickupWindow

object

Show child attributes

Response

Minimal partner-safe shipment

string<uuid>

required

reference

string

required

status

enum<string>

required

Available options:

CREATED,

ASSIGNED,

PICKED_UP,

OUT_FOR_DELIVERY,

DELIVERED,

FAILED,

CANCELLED

trackingUrl

string<uri-reference>

required

createdAt

string<date-time>

required

version

integer<int64>

required

Required range: x >= 0

codAmount

number<decimal> | null

Required range: x >= 0

⌘I

Getting Started

Authentication

Shipments

Events

Request semantics

API reference

Create one shipment from a merchant reference and two location pins

Authorizations

Headers

Body

Response