{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Order lifecycle"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"order-lifecycle","__idx":0},"children":["Order lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"two-fields-two-names","__idx":1},"children":["Two fields, two names"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The two APIs report the same values under different field names."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Last-mile"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /orders/{order_id}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fulfilment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/fulfilment/orders/{id}"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks carry it as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.state"]}," for both."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-then-make-it-ready","__idx":2},"children":["Create, then make it ready"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Last-mile."]}," Creating an order does not send it to Quiqup operations. A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," order shows in Quiqdash, under the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pending"]}," tab, but dispatch does not see it and it will never be collected."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /orders                                   -> order is pending\nPUT  /orders/{order_id}/ready_for_collection   -> order enters the collection run\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are three ways an order becomes ready for collection:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /orders/{order_id}/ready_for_collection"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ready_for_collection: true"]}," on create"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Account-level auto-RFC (automatic ready for collection), switched on by Quiqup on request"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the flag is set but the order still has validation errors, the order stays pending."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the usual cause of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["\"I got a 2xx but nothing happened\""]},": the order is in Quiqdash under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pending"]},", and no courier comes. Checklist:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Was ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ready_for_collection"]}," called, and did it return 2xx?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Does ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /orders/{order_id}"]}," return the order?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Is the dropoff phone a valid UAE number? An invalid one is the most common reason an otherwise good order fails."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Is the account in the right operating area?"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same cause explains \"no courier is assigned to my API orders while manual orders get one\"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fulfilment."]}," Same idea, different field. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mark_as_ready_for_collection: true"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/fulfilment/orders"]}," releases the order on create. There is no separate release endpoint."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"order-statuses-and-their-events","__idx":3},"children":["Order statuses and their events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]}," a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," returns and the event a webhook carries are the same transition. One table for both."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The wire field is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]}]},", not \"status\"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"state"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Webhook event"},"children":["Webhook event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it means"},"children":["What it means"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Created as a draft. Quiqup ignores it until it is made ready."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ready_for_collection"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.ready_for_collection"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Known to Quiqup, joins the next collection run."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["out_for_collection"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.out_for_collection"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A courier is assigned to collect."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["collected"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.collected"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Collected, on the way to the depot."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["collection_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.collection_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Collection attempted and failed. Carries a reason."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["received_at_depot"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.received_at_depot"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Received at the depot."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["at_depot"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.at_depot"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["At the depot, awaiting scheduling or the next delivery day."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.scheduled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Scheduled for a future delivery with the customer."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in_transit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.in_transit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Moving between the Dubai and Abu Dhabi warehouses. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in_transit"]}," is the wire value; older documentation spelled it ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Transit"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["out_for_delivery"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.out_for_delivery"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Out for delivery."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivery_complete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.delivery_complete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delivered. End of life."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivery_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.delivery_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delivery failed. Carries a reason."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["return_to_origin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.return_to_origin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Will be returned to the merchant."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["out_for_return"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.out_for_return"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Being returned to the merchant."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returned_to_origin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.returned_to_origin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Returned to the merchant. End of life."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancelled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_hold"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.on_hold"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["On hold."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Subscribable, and a delivery would carry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state: error"]},", but last-mile orders do not currently enter this state. See below."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["picking_started"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.picking_started"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Picking has begun. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fulfilment only."]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wms_on_hold"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Held inside the warehouse management system. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fulfilment ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," only."]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["problematic"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Flagged as problematic by the warehouse. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fulfilment ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," only."]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wms_on_hold"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["problematic"]}," appear only in the fulfilment API's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},". Neither has a webhook event, so no subscription receives them. On the last-mile side a problematic order is put ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_hold"]},", and the history carries the reason ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Problematic order"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle every value, including ones you do not recognise."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.error"]}," is in the event list for compatibility: no last-mile order moves to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ready_for_collection"]}," instead. A client that switches exhaustively on a hard-coded list should still treat an unknown ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]}," as \"no change I understand\" rather than fail."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"where-a-failed-state-goes-next","__idx":4},"children":["Where a failed state goes next"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["None of the failure states are dead ends."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"From"},"children":["From"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Goes back to"},"children":["Goes back to"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["collection_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ready_for_collection"]},", for another attempt"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivery_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["at_depot"]},", to be rescheduled"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_hold"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Various, depending on why it was held"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wms_on_hold"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Back into picking once the warehouse clears it"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A failure is a retry, not an ending. The end states are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivery_complete"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returned_to_origin"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"reasons","__idx":5},"children":["Reasons"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_hold"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivery_failed"]}," entries in the history carry a human reason string, for example"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Problematic order"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Incorrect customer details + unreachable"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["return_to_origin"]}," carries"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["return_to_origin_reason"]},", for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Cancelled by Customer"]},". Those are free text, not an enum."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /orders/{order_id}/history"]}," returns every state an order has passed through, with timestamps. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /orders/{order_id}"]}," returns the current state only."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response shape is declared in the contract."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["You drive two transitions, and only two."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /orders/{order_id}/ready_for_collection"]}," moves an order out of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /orders/batch/set_cancelled"]}," cancels it while it is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ready_for_collection"]},". Everything else is set by operations and the courier application."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Status is order-level. When one parcel of several hits an exception, the order-level status can read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["at_depot"]}," while a customer has already received part of the shipment. That is the usual explanation for \"shows At Depot but was delivered\"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"service-types","__idx":6},"children":["Service types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]}," on create. It cannot be changed afterwards. It is not required: an order without one is created as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner_same_day"]},". Send it explicitly rather than relying on that. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/lastmile/create-an-order#top-level-fields"},"children":["Top-level fields"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On fulfilment the same field is called ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_kind"]}," and is required. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/fulfilment/orders#service-kinds"},"children":["Fulfilment orders"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"kind (last-mile)"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]}," (last-mile)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Service"},"children":["Service"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner_same_day"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Collected and delivered the same day if made ready before the agreed cut-off."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner_next_day"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delivered the next day."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner_4hr"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Made ready between 08:00 and your 4-hour cut-off, 18:00 unless agreed otherwise: delivered within 4 hours. Made ready after the cut-off: by 12:00 the next day. Made ready before 08:00: by 12:00 the same day. UAE time throughout."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner_return"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A return. Pickup is the customer's address, dropoff is the merchant's."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner_store"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Accepted on create and resolves to the same-day service class."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner_export"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["International shipping to GCC destinations, with rule-based carrier allocation. Also applied automatically when the destination country differs from the pickup country. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/lastmile/create-an-order#export-orders"},"children":["Export orders"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fulfilment orders can be exports too, through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_kind"]}," on the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/fulfilment/orders#service-kinds"},"children":["Fulfilment API"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Values you may see referenced elsewhere and should not integrate against: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner_ondemand"]}," and any 1-hour service. On-demand is discontinued."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]}," on the way in is not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]}," on the way out."]}," The API responses carry both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_kind"]},","," ","the service the order was created with, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]},", a service class that is not always the same."," ","Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner_store"]}," and you get back ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_kind: partner_store"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind: partner_same_day"]},"."," ","Webhooks carry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_kind"]}," and can carry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]}," empty. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Match on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_kind"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An order past the cut-off is accepted and collected on the next cycle. It is not rejected."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A service must be enabled on your account before you can use it."]}," Same Day is checked when the order is created: without it, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /orders"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment","__idx":7},"children":["Payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_mode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_amount"]}," are request fields and are described once, in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/lastmile/create-an-order#top-level-fields"},"children":["Top-level fields"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Currency defaults to the country's currency: AED in the UAE."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identifiers","__idx":8},"children":["Identifiers"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Identifier"},"children":["Identifier"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Who generates it"},"children":["Who generates it"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner_order_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your own reference. Used for invoicing and COD reconciliation. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Uniqueness is not enforced"]},", so send a unique value. It does not make a retry safe: send a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/lastmile/create-an-order#retrying-safely"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uuid"]}]}," for that."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order id"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Quiqup"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Returned on create. Use it in later API calls."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tracking id / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tracking_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Quiqup"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shareable and unauthenticated. Anyone with the link can open it."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Parcel barcode"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Quiqup"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send an empty string. Quiqup generates it and prints the label."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/lastmile/create-an-order#retrying-safely"},"children":["Retrying safely"]}," for what that means when a create times out."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"billing_identifier","__idx":9},"children":["billing_identifier"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A request field, described in full under ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/lastmile/create-an-order#billing_identifier"},"children":["billing_identifier"]},"."]}]},"headings":[{"value":"Order lifecycle","id":"order-lifecycle","depth":1},{"value":"Two fields, two names","id":"two-fields-two-names","depth":2},{"value":"Create, then make it ready","id":"create-then-make-it-ready","depth":2},{"value":"Order statuses and their events","id":"order-statuses-and-their-events","depth":2},{"value":"Where a failed state goes next","id":"where-a-failed-state-goes-next","depth":3},{"value":"Reasons","id":"reasons","depth":3},{"value":"Service types","id":"service-types","depth":2},{"value":"Payment","id":"payment","depth":2},{"value":"Identifiers","id":"identifiers","depth":2},{"value":"billing_identifier","id":"billing_identifier","depth":2}],"frontmatter":{"seo":{"title":"Order lifecycle"}},"lastModified":"2026-10-16T10:31:15.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/order-lifecycle","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}