Skip to main content
Creating a shipment takes four fields. Everything else is either optional or derived.

​
The minimal request

Requires the shipments:write scope.
There is no quote call to make first, no branch or pickup-location code to look up, no city or address to supply, no carrier to name, and no service level to choose. Sending more than the four fields above does not get you a better shipment — it gets you a rejected request, because the payload is closed.

​
What DropHub derives

From those two coordinates alone, DropHub resolves address and city context, the route and its distance, whether the lane is covered, the price under your commercial terms, the eligible carrier, the service and its defaults, dispatch, the lifecycle starting state, SAR as the currency with prepaid as the payment mode, and the customer tracking URL. None of these are inputs, and none are configurable through this API.

​
Phone numbers

mobile is a Saudi mobile number. Three shapes are accepted: Normalization happens on the way in, so you do not need to canonicalize first. Anything that is not one of these three shapes is rejected with 422.

​
Optional fields

Add these only when the default is wrong for the order.
The default parcel is one piece, 1 kg, ambient, described as “Parcel”. Override any part of it:
pieces is 1–100. weightKg is greater than zero. description is 1–160 characters.
An exact decimal in SAR, greater than zero, to two places. Omit it entirely for prepaid orders — that is what makes an order prepaid. Sending 0 is not the way to say “no COD”; leaving the field out is.
If your account has a saved pickup location, use its code instead of a coordinate:
pickup is one or the other — a savedLocationCode, or a latitude/longitude pair. Never both.
Both bounds are required together, in UTC. Omit the whole object to let DropHub collect as soon as it can.
A request using all of them:

​
The response

Deliberately small — it carries what you cannot compute yourself and nothing more.
201 carries a Location header and an ETag. trackingUrl is the customer link, minted automatically — see Tracking.

​
Retries are already safe

reference is the idempotency key. You do not need to send an Idempotency-Key header.
Because reference is the key, reusing one order number for a genuinely different shipment is a conflict, not an update. One order number, one shipment.
The optional Idempotency-Key header (16–128 characters) exists for callers who already have a key of their own. An explicit key always wins over the derived one. See Idempotency and ETags.

​
Read one back

Requires shipments:read, and returns the same shape as the create response with a current status and version.
There is no collection endpoint and no search. Shipments are addressed by the id you were handed at creation — store it against your order. For progress, use webhooks rather than polling a list.

​
Status

Seven public statuses, and no others:
Treat status as a value to read, not a sequence to assume. DropHub’s internal dispatch states are collapsed into these seven on the way out, so a shipment may skip what looks like a step, and FAILED is an ordinary outcome rather than an error.