Order lifecycle

Applies to both APIs. One state machine covers fulfilment and last-mile. A fulfilment order becomes a Quiqup shipment once it is picked, and from there reports the same values as any other order.

The statuses below are also the same for connector orders. What is not the same is the two-call create-then-ready sequence: the connector does both for you.

The two APIs report the same values under different field names.

Webhooks carry it as payload.state for both.

Last-mile. Creating an order does not send it to Quiqup operations. A pending order shows in Quiqdash, under the Pending tab, but dispatch does not see it and it will never be collected.

POST /orders                                   -> order is pending
PUT  /orders/{order_id}/ready_for_collection   -> order enters the collection run

There are three ways an order becomes ready for collection:

1. PUT /orders/{order_id}/ready_for_collection
2. ready_for_collection: true on create
3. Account-level auto-RFC (automatic ready for collection), switched on by Quiqup on request

If the flag is set but the order still has validation errors, the order stays pending.

This is the usual cause of "I got a 2xx but nothing happened": the order is in Quiqdash under Pending, and no courier comes. Checklist:

1. Was ready_for_collection called, and did it return 2xx?
2. Does GET /orders/{order_id} return the order?
3. Is the dropoff phone a valid UAE number? An invalid one is the most common reason an otherwise good order fails.
4. Is the account in the right operating area?

The same cause explains "no courier is assigned to my API orders while manual orders get one".

Fulfilment. Same idea, different field. mark_as_ready_for_collection: true on POST /api/fulfilment/orders releases the order on create. There is no separate release endpoint.

The state a GET returns and the event a webhook carries are the same transition. One table for both.

The wire field is state, not "status".

wms_on_hold and problematic appear only in the fulfilment API's status. Neither has a webhook event, so no subscription receives them. On the last-mile side a problematic order is put on_hold, and the history carries the reason Problematic order.

Handle every value, including ones you do not recognise. order.error is in the event list for compatibility: no last-mile order moves to error today. A problem found after acceptance leaves the order in the state it was in, and a booking refused at release comes back as a 422 on ready_for_collection instead. A client that switches exhaustively on a hard-coded list should still treat an unknown state as "no change I understand" rather than fail.

None of the failure states are dead ends.

A failure is a retry, not an ending. The end states are delivery_complete, returned_to_origin and cancelled.

on_hold and delivery_failed entries in the history carry a human reason string, for example Problematic order and Incorrect customer details + unreachable. return_to_origin carries return_to_origin_reason, for example Cancelled by Customer. Those are free text, not an enum.

GET /orders/{order_id}/history returns every state an order has passed through, with timestamps. GET /orders/{order_id} returns the current state only.

The response shape is declared in the contract.

You drive two transitions, and only two. PUT /orders/{order_id}/ready_for_collection moves an order out of pending, and PUT /orders/batch/set_cancelled cancels it while it is pending or ready_for_collection. Everything else is set by operations and the courier application.

Status is order-level. When one parcel of several hits an exception, the order-level status can read at_depot while a customer has already received part of the shipment. That is the usual explanation for "shows At Depot but was delivered".

Set kind on create. It cannot be changed afterwards. It is not required: an order without one is created as partner_same_day. Send it explicitly rather than relying on that. See Top-level fields.

On fulfilment the same field is called service_kind and is required. See Fulfilment orders.

Fulfilment orders can be exports too, through service_kind on the Fulfilment API.

Values you may see referenced elsewhere and should not integrate against: partner_ondemand and any 1-hour service. On-demand is discontinued.

kind on the way in is not kind on the way out. The API responses carry both service_kind, the service the order was created with, and kind, a service class that is not always the same. Send partner_store and you get back service_kind: partner_store with kind: partner_same_day. Webhooks carry service_kind and can carry kind empty. Match on service_kind.

An order past the cut-off is accepted and collected on the next cycle. It is not rejected.

A service must be enabled on your account before you can use it. Same Day is checked when the order is created: without it, POST /orders returns 422 with Same day service is not enabled for your account. The other services are not checked at create, so an order for one that is not enabled is accepted. Confirm with your account manager which services are on before you build.

kind cannot be changed after creation. A mis-serviced order has to be cancelled and re-booked, and an already-labelled parcel is returned rather than relabelled.

payment_mode and payment_amount are request fields and are described once, in Top-level fields.

Currency defaults to the country's currency: AED in the UAE.

See Retrying safely for what that means when a create times out.

A request field, described in full under billing_identifier.