Shipping
Send an order to the courier
Registers the order with a courier, exactly as the dashboard's Send to courier does: the same parcel details, the same reference (the order number), the same checks. The answer is the new shipment, with its tracking_code, and the order moves to shipped.
This creates a real parcel at the courier with a live key. The courier is the one you pass in courier_id, else the one chosen at checkout, else the store's routing rules, else its default courier.
Only one send per order can run at a time, and an order already with a courier is refused: cancel its shipment first. An order whose address needs review (needs_review) is refused until the merchant confirms it.
If the courier refuses the parcel you get courier_rejected with the courier's own reason, and a failed shipment is recorded so the merchant sees the attempt. With a test key nothing leaves Ordexs: the shipment is simulated, with a TEST-… tracking code.
Path parameters
- order_idstringRequired
starts with ord_
Body
- courier_idstring
A courier account from GET /v1/delivery/rates. Leave it out to use the order's courier, the routing rules or the default.
starts with cour_
Returns
201 Created · The new shipment. Shipment
- idstringRequired
starts with shp_
- objectstringRequired
always "shipment"
- order_idstringRequired
starts with ord_
- courierobjectRequired
3 child fields
- idstring or null
The store's courier account. null for a test shipment.
- brandstring
The courier company, e.g. "zrexpress", "yalidine". "test" for a test shipment.
- account_namestring or null
The name the merchant gave the account.
- tracking_codestring or nullRequired
The courier's tracking number. null when the send failed.
- statusShipmentStatusRequired
pending(registered with the courier, not picked up yet),in_transit,delivered,returned,cancelled, orfailed(the courier refused it). New values may be added.One of
pending,in_transit,delivered,returned,cancelled,failed - stageShipmentStage or null
- stage_changed_atstring or null
ISO 8601 date-time, UTC
- status_detailstring or null
The courier's own words for its last report, in the courier's language.
- codobject
The cash on delivery, as the courier reports it.
2 child fields
- statusstring or null
delivered_unpaid: delivered, the courier has not collected yet. cash_collected: the courier holds the cash. paid: the courier paid the merchant. null when the courier does not report it.
One of
delivered_unpaid,cash_collected,paid,archived - settled_atstring or null
ISO 8601 date-time, UTC
- return_statusstring or null
suspended: on hold at the courier. return_ready: coming back, waiting for the merchant to collect it. returned_in: handed back.
One of
suspended,return_ready,returned_in - driverobject or null
2 child fields
- namestring or null
- phonestring or null
E.164 when it could be read.
- eventsarray of objects
The courier's history of the parcel, oldest first (the last 50).
3 child fields
- atstring or null
The courier's own timestamp, as it sends it.
- labelstring
- kindstring or null
- failure_messagestring or null
Why the courier refused the parcel
- validated_atstring or null
When the parcel was validated with the courier.
ISO 8601 date-time, UTC
- packed_atstring or null
When the parcel was marked packed.
ISO 8601 date-time, UTC
- last_checked_atstring or null
When Ordexs last asked the courier about it.
ISO 8601 date-time, UTC
- sent_atstring
ISO 8601 date-time, UTC
- livemodebooleanRequired
- created_atstringRequired
ISO 8601 date-time, UTC
- updated_atstringRequired
ISO 8601 date-time, UTC
Errors
Every error has the same shape. This endpoint can answer with:
- 401
authentication_required - 401
invalid_api_key - 402
plan_required - 403
insufficient_scope - 429
rate_limited - 400
invalid_request - 400
invalid_json - 400
unknown_field - 422
validation_failed - 409
idempotency_in_progress - 422
idempotency_key_reused - 404
not_found - 409
invalid_state_transition - 422
courier_not_configured - 422
courier_rejected - 503
upstream_unavailable
