{ "components": { "responses": {}, "schemas": { "AddParcelToOrderRequest": { "description": "POST body for adding parcel to an order", "example": { "name": "item1" }, "properties": { "name": { "description": "Item's name", "maxLength": 255, "minLength": 1, "nullable": false, "type": "string" } }, "required": [ "name" ], "title": "AddParcelToOrderRequest", "type": "object" }, "ApiError": { "description": "Error envelope. `api_error` is the structured form; the top-level `error`, `error_detail`, `errors` and `error_details` repeat it for older clients.", "example": { "api_error": { "attribute_errors": [ { "detail": "[order][references] a unique reference with the same label and value already exists for this account" } ], "code": "duplicate_order_reference", "description": "A unique order reference already exists for this account.", "http_status_code": 422, "human": "[order][references] a unique reference with the same label and value already exists for this account", "id": 1010, "message": "[order][references] a unique reference with the same label and value already exists for this account" }, "error": "[order][references] a unique reference with the same label and value already exists for this account", "error_detail": "[order][references] a unique reference with the same label and value already exists for this account", "error_details": [ { "detail": "[order][references] a unique reference with the same label and value already exists for this account" } ], "errors": [ { "detail": "[order][references] a unique reference with the same label and value already exists for this account" } ] }, "properties": { "api_error": { "$ref": "#/components/schemas/ApiErrorBody" }, "error": { "description": "Same as `api_error.message`.", "type": "string" }, "error_detail": { "description": "One-line summary of the error kind.", "type": "string" }, "error_details": { "description": "Same as `errors`.", "items": { "$ref": "#/components/schemas/ApiErrorDetail" }, "type": "array" }, "errors": { "items": { "$ref": "#/components/schemas/ApiErrorDetail" }, "type": "array" } }, "required": [ "api_error", "error", "errors" ], "title": "ApiError", "type": "object" }, "ApiErrorBody": { "description": "The structured part of the error.", "properties": { "attribute_errors": { "items": { "$ref": "#/components/schemas/ApiErrorDetail" }, "type": "array" }, "code": { "description": "Error kind, e.g. `generic_user`.", "type": "string" }, "description": { "description": "What to check in your request.", "type": "string" }, "http_status_code": { "description": "The status this error kind nominally maps to. It can differ from the HTTP status of the response; branch on the HTTP status, not on this field.", "type": "integer" }, "human": { "description": "Longer explanation of the error kind.", "type": "string" }, "id": { "description": "Stable numeric identifier of the error kind, e.g. 1010.", "type": "integer" }, "message": { "description": "Short summary, safe to show to a user.", "type": "string" } }, "required": [ "id", "code", "message", "http_status_code", "attribute_errors" ], "title": "ApiErrorBody", "type": "object" }, "ApiErrorDetail": { "properties": { "detail": { "description": "One problem, in plain language.", "type": "string" } }, "required": [ "detail" ], "title": "ApiErrorDetail", "type": "object" }, "BatchProjectionPending": { "description": "The change was recorded; these orders could not be read back in time.", "example": { "order_ids": [ 10000001 ], "status": "pending_projection" }, "properties": { "order_ids": { "items": { "type": "integer" }, "type": "array" }, "status": { "enum": [ "pending_projection" ], "type": "string" } }, "required": [ "order_ids", "status" ], "title": "BatchProjectionPending", "type": "object" }, "CancelOrdersRequest": { "example": { "order_ids": [ 10000001, 10000002 ], "reason": "Customer changed their mind" }, "properties": { "order_ids": { "description": "Ids of your orders to cancel (`order.id`).", "items": { "type": "integer" }, "minItems": 1, "type": "array" }, "reason": { "description": "Why the orders are cancelled, kept with the cancellation.", "type": "string" } }, "required": [ "order_ids" ], "title": "CancelOrdersRequest", "type": "object" }, "ErrorMessage": { "description": "A plain error body: a single error string, sent by some errors and by the authentication check.", "example": { "error": "Can not remove last parcel from an order." }, "properties": { "error": { "description": "What went wrong, in plain language.", "type": "string" } }, "required": [ "error" ], "title": "ErrorMessage", "type": "object" }, "FieldErrors": { "description": "Request parameters that failed validation, keyed by parameter name.", "example": { "errors": { "id": [ "is invalid" ] } }, "properties": { "errors": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, "message": { "description": "Sent by some endpoints, always `Unprocessable entity`.", "type": "string" } }, "required": [ "errors" ], "title": "FieldErrors", "type": "object" }, "Item": { "description": "A parcel. One label is printed per item.", "properties": { "dimensions": { "description": "Centimetres.", "nullable": true, "properties": { "height": { "nullable": true, "type": "number" }, "length": { "nullable": true, "type": "number" }, "width": { "nullable": true, "type": "number" } }, "type": "object" }, "id": { "description": "Parcel id, sent as a string. The id to pass when removing the parcel.", "type": "string" }, "name": { "nullable": true, "type": "string" }, "parcel_barcode": { "description": "The barcode on the label, e.g. `10000001-1`.", "type": "string" }, "parcel_barcode_generated_by": { "description": "`quiqup` when Quiqup generated the barcode, `partner` when you sent it.", "type": "string" }, "quantity": { "type": "integer" }, "weight": { "description": "Kilograms, as a string.", "nullable": true, "type": "string" } }, "title": "Item", "type": "object" }, "NewParcel": { "description": "The parcel just added, returned on its own rather than inside the order.", "properties": { "allowed_eans": { "description": "Always empty", "items": { "type": "string" }, "type": "array" }, "checked": { "description": "Always false", "type": "boolean" }, "checked_at": { "description": "Always null", "nullable": true, "type": "string" }, "ean": { "description": "Always null", "nullable": true, "type": "string" }, "gid": { "description": "Global ID of the order the parcel belongs to", "type": "string" }, "id": { "description": "Parcel ID", "type": "integer" }, "metadata": { "description": "Always empty", "type": "object" }, "name": { "description": "Parcel name, as sent", "type": "string" }, "notes": { "description": "Always null", "nullable": true, "type": "string" }, "parcel_barcode": { "description": "Barcode printed on the label", "type": "string" }, "parcel_barcode_generated_by": { "description": "Who generated the barcode", "type": "string" }, "price": { "description": "Always \"0.0\"", "type": "string" }, "quantity": { "description": "Always 1", "type": "integer" }, "state": { "description": "Always null", "nullable": true, "type": "string" }, "total_cost": { "description": "Always \"0.0\"", "type": "string" } }, "title": "NewParcel", "type": "object" }, "Order": { "description": "An order. The response carries more fields than these: the others are used by Quiqup's\nown tools and can change without notice, so do not rely on them. Timestamps are in UAE\ntime (`+04:00`).\n", "properties": { "allowed_payment_types": { "description": "How the customer may pay on delivery.", "items": { "enum": [ "cash", "card" ], "type": "string" }, "type": "array" }, "billing_identifier": { "description": "The `billing_identifier` sent at creation, if any.", "nullable": true, "type": "string" }, "brand_name": { "description": "The name of the account the order belongs to.", "nullable": true, "type": "string" }, "collection_attempts": { "nullable": true, "type": "integer" }, "collection_time": { "description": "The collection window.", "nullable": true, "properties": { "collection_after": { "format": "date-time", "nullable": true, "type": "string" }, "collection_before": { "format": "date-time", "nullable": true, "type": "string" } }, "type": "object" }, "created_at": { "format": "date-time", "type": "string" }, "delivery_attempts": { "type": "integer" }, "delivery_failure_reason": { "description": "Set once a delivery attempt fails.", "nullable": true, "type": "string" }, "delivery_time": { "description": "The delivery window.", "nullable": true, "properties": { "delivery_after": { "format": "date-time", "nullable": true, "type": "string" }, "delivery_before": { "format": "date-time", "nullable": true, "type": "string" } }, "type": "object" }, "destination": { "description": "Where the order is delivered.", "properties": { "address": { "properties": { "address1": { "type": "string" }, "address2": { "nullable": true, "type": "string" }, "apartment_number": { "nullable": true, "type": "string" }, "building_name": { "nullable": true, "type": "string" }, "city": { "description": "The city, or `town` when no city was sent.", "nullable": true, "type": "string" }, "coordinates": { "description": "The point Quiqup delivers to or collects from.", "nullable": true, "properties": { "lat": { "description": "Latitude", "type": "number" }, "lng": { "description": "Longitude", "type": "number" } }, "type": "object" }, "country": { "nullable": true, "type": "string" }, "id": { "description": "Address id, sent as a string.", "type": "string" }, "ksa_national_address": { "description": "Saudi national address, on Saudi orders.", "nullable": true, "type": "string" }, "postcode": { "nullable": true, "type": "string" }, "town": { "nullable": true, "type": "string" } }, "type": "object" }, "arrived_at": { "description": "Always null.", "format": "date-time", "nullable": true, "type": "string" }, "checked": { "nullable": true, "type": "boolean" }, "contact_email": { "nullable": true, "type": "string" }, "contact_name": { "nullable": true, "type": "string" }, "contact_phone": { "nullable": true, "type": "string" }, "finished_at": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "Waypoint id, sent as a string.", "type": "string" }, "notes": { "nullable": true, "type": "string" }, "signature": { "properties": { "url": { "description": "Signature image, if any.", "nullable": true, "type": "string" } }, "type": "object" }, "tracking_token": { "nullable": true, "type": "string" }, "tracking_url": { "description": "Tracking page for this leg of the delivery.", "nullable": true, "type": "string" }, "zone": { "description": "Quiqup's delivery zone for the address.", "properties": { "parent": { "nullable": true, "type": "string" }, "parent_group": { "nullable": true, "type": "string" }, "sector": { "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "display_items_info": { "nullable": true, "type": "boolean" }, "forward_order_id": { "description": "On a return order, the id of the order it returns.", "nullable": true, "type": "integer" }, "forward_partner_order_id": { "description": "On a return order, the `partner_order_id` of the order it returns.", "nullable": true, "type": "string" }, "id": { "description": "The order id. Use it in every other order route.", "type": "integer" }, "item_quantity_count": { "description": "Number of parcels.", "type": "integer" }, "items": { "description": "The parcels.", "items": { "$ref": "#/components/schemas/Item" }, "type": "array" }, "kind": { "description": "The service class. Read the service from `service_kind`.", "type": "string" }, "origin": { "description": "Where the order is collected.", "properties": { "address": { "properties": { "address1": { "type": "string" }, "address2": { "nullable": true, "type": "string" }, "apartment_number": { "nullable": true, "type": "string" }, "building_name": { "nullable": true, "type": "string" }, "city": { "description": "The city, or `town` when no city was sent.", "nullable": true, "type": "string" }, "coordinates": { "description": "The point Quiqup delivers to or collects from.", "nullable": true, "properties": { "lat": { "description": "Latitude", "type": "number" }, "lng": { "description": "Longitude", "type": "number" } }, "type": "object" }, "country": { "nullable": true, "type": "string" }, "id": { "description": "Address id, sent as a string.", "type": "string" }, "ksa_national_address": { "description": "Saudi national address, on Saudi orders.", "nullable": true, "type": "string" }, "postcode": { "nullable": true, "type": "string" }, "town": { "nullable": true, "type": "string" } }, "type": "object" }, "arrived_at": { "description": "Always null.", "format": "date-time", "nullable": true, "type": "string" }, "checked": { "nullable": true, "type": "boolean" }, "contact_email": { "nullable": true, "type": "string" }, "contact_name": { "nullable": true, "type": "string" }, "contact_phone": { "nullable": true, "type": "string" }, "finished_at": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "Waypoint id, sent as a string.", "type": "string" }, "notes": { "nullable": true, "type": "string" }, "signature": { "properties": { "url": { "description": "Signature image, if any.", "nullable": true, "type": "string" } }, "type": "object" }, "tracking_token": { "nullable": true, "type": "string" }, "tracking_url": { "description": "Tracking page for this leg of the delivery.", "nullable": true, "type": "string" }, "zone": { "description": "Quiqup's delivery zone for the address.", "properties": { "parent": { "nullable": true, "type": "string" }, "parent_group": { "nullable": true, "type": "string" }, "sector": { "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "partner_order_id": { "description": "Your own reference for the order.", "nullable": true, "type": "string" }, "payment_amount": { "description": "Amount to collect, as a decimal string, e.g. `\"0.0\"`.", "type": "string" }, "payment_mode": { "description": "`pre_paid` or `paid_on_delivery` (older orders can carry a retired mode).", "type": "string" }, "products": { "description": "The goods, as sent at creation.", "items": { "$ref": "#/components/schemas/Product" }, "nullable": true, "type": "array" }, "reason": { "description": "On a return order, the reason sent at creation.", "nullable": true, "type": "string" }, "region_name": { "description": "e.g. `Dubai`.", "nullable": true, "type": "string" }, "required_documents": { "description": "Proof the courier collects at delivery, e.g. `otp`.", "items": { "type": "string" }, "type": "array" }, "return_order_id": { "description": "On an order with a return, the id of the return order.", "nullable": true, "type": "integer" }, "return_partner_order_id": { "description": "On an order with a return, the `partner_order_id` of the return order.", "nullable": true, "type": "string" }, "scheduled_for": { "description": "The requested collection time, when one was sent.", "format": "date-time", "nullable": true, "type": "string" }, "service_kind": { "description": "The service the order was created with, e.g. `partner_same_day`.", "nullable": true, "type": "string" }, "sku_info": { "nullable": true, "type": "string" }, "state": { "description": "e.g. `pending`, `ready_for_collection`, `delivery_complete`. Every state is listed at https://developer-docs.quiqup.com/docs/order-lifecycle.", "type": "string" }, "state_updated_at": { "description": "When the order entered its current state.", "format": "date-time", "nullable": true, "type": "string" }, "submitted_at": { "description": "When the order was created.", "format": "date-time", "nullable": true, "type": "string" }, "tracking_url": { "description": "The tracking page to share with your customer.", "nullable": true, "type": "string" }, "user": { "properties": { "email": { "description": "User email", "type": "string" }, "fullname": { "description": "User full name", "nullable": true, "type": "string" }, "id": { "description": "User ID", "type": "integer" } }, "type": "object" }, "uuid": { "description": "The `uuid` you sent, or one Quiqup generated.", "format": "uuid", "type": "string" }, "weight_kg": { "nullable": true, "type": "number" } }, "title": "Order", "type": "object" }, "OrderListAddress": { "properties": { "address1": { "type": "string" }, "address2": { "nullable": true, "type": "string" }, "apartment_number": { "nullable": true, "type": "string" }, "building_name": { "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string" }, "coordinates": { "nullable": true, "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } }, "type": "object" }, "country": { "description": "ISO 3166-1 alpha-2 code, e.g. `AE`. Can be null on non-UAE addresses.", "nullable": true, "type": "string" }, "postcode": { "nullable": true, "type": "string" }, "town": { "description": "Area, e.g. `Business Bay`.", "nullable": true, "type": "string" } }, "title": "OrderListAddress", "type": "object" }, "OrderListItem": { "description": "A parcel. One label is printed per item.", "properties": { "dimensions": { "description": "Centimetres.", "nullable": true, "properties": { "height": { "type": "number" }, "length": { "type": "number" }, "width": { "type": "number" } }, "type": "object" }, "name": { "nullable": true, "type": "string" }, "parcel_barcode": { "description": "The barcode on the label, e.g. `10000001-1`.", "nullable": true, "type": "string" }, "quantity": { "type": "integer" }, "weight": { "description": "Kilograms, as a decimal string, e.g. `\"5.0\"`.", "nullable": true, "type": "string" } }, "title": "OrderListItem", "type": "object" }, "OrderListOrder": { "description": "One order in a list. Each result carries more fields than these: the others are\nused by Quiqup's own tools and can change without notice, so do not rely on them.\nTimestamps are in UAE time (`+04:00`).\n", "properties": { "carrier": { "description": "e.g. `Quiqup`.", "nullable": true, "type": "string" }, "collection_attempts": { "nullable": true, "type": "integer" }, "collection_time": { "nullable": true, "properties": { "collection_after": { "format": "date-time", "nullable": true, "type": "string" }, "collection_before": { "format": "date-time", "nullable": true, "type": "string" } }, "type": "object" }, "created_at": { "format": "date-time", "type": "string" }, "delivery_attempts": { "nullable": true, "type": "integer" }, "delivery_failure_reason": { "nullable": true, "type": "string" }, "delivery_time": { "nullable": true, "properties": { "delivery_after": { "format": "date-time", "nullable": true, "type": "string" }, "delivery_before": { "format": "date-time", "nullable": true, "type": "string" } }, "type": "object" }, "destination": { "$ref": "#/components/schemas/OrderListWaypoint" }, "forward_order_id": { "description": "On a return order, the id of the order it returns.", "nullable": true, "type": "integer" }, "id": { "description": "The order id, as used in `GET /orders/{id}` and the other order routes.", "type": "integer" }, "item_quantity_count": { "nullable": true, "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/OrderListItem" }, "type": "array" }, "origin": { "$ref": "#/components/schemas/OrderListWaypoint" }, "partner_order_id": { "description": "Your own reference for the order.", "nullable": true, "type": "string" }, "payment_amount": { "description": "Amount to collect, as a decimal string, e.g. `\"0.0\"`.", "nullable": true, "type": "string" }, "payment_mode": { "description": "`pre_paid`, `cash_on_delivery`, `card_on_delivery` or `paid_on_delivery`.", "nullable": true, "type": "string" }, "return_order_id": { "description": "On an order with a return, the id of the return order.", "nullable": true, "type": "integer" }, "service_kind": { "description": "e.g. `partner_same_day`, `partner_next_day`.", "type": "string" }, "shipment_number": { "nullable": true, "type": "string" }, "state": { "description": "e.g. `pending`, `delivery_complete`.", "type": "string" }, "state_updated_at": { "format": "date-time", "nullable": true, "type": "string" }, "submitted_at": { "format": "date-time", "nullable": true, "type": "string" }, "tracking_url": { "nullable": true, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "uuid": { "format": "uuid", "type": "string" }, "weight_kg": { "nullable": true, "type": "number" } }, "title": "OrderListOrder", "type": "object" }, "OrderListResponse": { "description": "One page of orders.", "example": { "current_page": 1, "per_page": 1, "results": [ { "carrier": "Quiqup", "created_at": "2026-10-06T16:46:56.000+04:00", "delivery_attempts": 1, "delivery_time": { "delivery_after": "2026-10-06T16:47:13.000+04:00", "delivery_before": "2026-10-07T23:00:00.000+04:00" }, "destination": { "address": { "address1": "1st Road", "coordinates": { "lat": 25.2048, "lng": 55.2708 }, "country": "AE", "town": "Business Bay" }, "contact_name": "Customer name", "contact_phone": "+971500000000" }, "id": 10000001, "item_quantity_count": 1, "items": [ { "dimensions": { "height": 10, "length": 10, "width": 10 }, "name": "Parcel", "parcel_barcode": "10000001-1", "quantity": 1, "weight": "5.0" } ], "partner_order_id": "PARTNER-ORDER-ID", "payment_amount": "0.0", "payment_mode": "pre_paid", "service_kind": "partner_same_day", "shipment_number": "10000001-1", "state": "delivery_complete", "state_updated_at": "2026-10-06T16:55:11.000+04:00", "submitted_at": "2026-10-06T16:46:56.000+04:00", "updated_at": "2026-10-06T16:55:11.000+04:00", "uuid": "00000000-0000-4000-8000-000000000001" } ], "total": 143, "total_pages": 143 }, "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/OrderListOrder" }, "type": "array" }, "total": { "description": "How many orders match. An estimate in some cases, see the operation description.", "type": "integer" }, "total_pages": { "type": "integer" } }, "required": [ "current_page", "per_page", "total", "total_pages", "results" ], "title": "OrderListResponse", "type": "object" }, "OrderListWaypoint": { "description": "Where the order is collected (`origin`) or delivered (`destination`).", "properties": { "address": { "$ref": "#/components/schemas/OrderListAddress" }, "contact_email": { "nullable": true, "type": "string" }, "contact_name": { "nullable": true, "type": "string" }, "contact_phone": { "nullable": true, "type": "string" }, "notes": { "nullable": true, "type": "string" }, "tracking_url": { "description": "Tracking page for this leg of the delivery.", "nullable": true, "type": "string" } }, "title": "OrderListWaypoint", "type": "object" }, "OrderRequest": { "description": "Request params for a single order", "example": { "destination": { "address": { "address1": "1st Road", "address2": "104G", "country": "UAE", "town": "Dubai" }, "contact_email": "customer@example.com", "contact_name": "Customer name", "contact_phone": "+971599999999", "notes": "" }, "items": [ { "name": "Parcel 1", "parcel_barcode": "", "quantity": 1 } ], "kind": "partner_same_day", "origin": { "address": { "address1": "1st Road", "address2": "104G", "country": "UAE", "town": "Dubai" }, "contact_name": "Warehouse contact", "contact_phone": "+971500000000" }, "partner_order_id": "PARTNER-ORDER-ID", "payment_mode": "pre_paid", "products": [ { "barcode": "1234654-kt", "country_of_origin": "CN", "description": "Running shoe red", "height": 12, "hs_code": "64041100", "length": 30, "quantity": 1, "selling_price": 58.3, "sku": "SKU-RUN-001", "weight": 0.8, "width": 20 } ] }, "properties": { "billing_identifier": { "description": "Creates the order in another account that Quiqup has linked to yours. Omit it unless Quiqup set one up for you: a value not linked to your account is ignored, with no error, and the order is created in your own account.", "nullable": true, "type": "string" }, "destination": { "$ref": "#/components/schemas/OrderRequestAddress" }, "disallowed_payment_types": { "$ref": "#/components/schemas/OrderRequestDisallowedPaymentTypes" }, "items": { "description": "The parcels, one entry per box or bag. A label is printed per item. The goods inside go in `products`.", "items": { "$ref": "#/components/schemas/OrderRequestItem" }, "minItems": 1, "type": "array" }, "kind": { "$ref": "#/components/schemas/OrderRequestKind" }, "metadata": { "$ref": "#/components/schemas/OrderRequestMetadata" }, "notes": { "$ref": "#/components/schemas/OrderRequestNotes" }, "origin": { "$ref": "#/components/schemas/OrderRequestAddress" }, "partner_order_id": { "description": "Your own reference, shown in Quiqdash and used to reconcile invoices and cash collected. Not checked for uniqueness: send a unique value.", "type": "string" }, "payment_amount": { "$ref": "#/components/schemas/OrderRequestPaymentAmountValue" }, "payment_mode": { "description": "`pre_paid` (the default: nothing to collect) or `paid_on_delivery` (the courier collects `payment_amount`). `cash_on_delivery` and `card_on_delivery` are retired: still accepted, but do not build on them.", "enum": [ "pre_paid", "cash_on_delivery", "card_on_delivery", "paid_on_delivery" ], "type": "string" }, "products": { "description": "The goods being shipped. Optional on domestic orders; required on export orders, where `hs_code`, `country_of_origin`, `weight` and `selling_price` clear customs.", "items": { "$ref": "#/components/schemas/OrderRequestProduct" }, "type": "array" }, "ready_for_collection": { "description": "Send `true` to release the order in the same call, instead of calling `PUT /orders/{id}/ready_for_collection`. The response can still show `pending`, and if the release fails the order is created anyway and stays `pending`: check `state` with `GET /orders/{id}`.", "nullable": true, "type": "boolean" }, "reason": { "description": "Why the parcel is coming back. Required when `kind` is `partner_return`.", "nullable": true, "type": "string" }, "registration_numbers": { "description": "Registration numbers for customs declarations (e.g. MIRSAL2). Optional.", "items": { "$ref": "#/components/schemas/OrderRequestRegistrationNumber" }, "nullable": true, "type": "array" }, "required_documents": { "$ref": "#/components/schemas/OrderRequestRequiredDocuments" }, "scheduled_for": { "description": "For a `partner_4hr` order, the earliest time Quiqup should collect it: an ISO 8601 date-time in UTC, e.g. `2026-11-02T06:00:00Z`. On a Last-mile account the order is released for collection when it is created; on a Fulfilment account it stays pending until it is released. It is not collected before this time. It must not be in the past and must fall between 04:00 and 14:59 UTC (08:00 to 18:59 Dubai time); otherwise the order is rejected with 400 and `[order][scheduled_for] is incorrect`. Send it with the `Z` suffix: the hour is checked as written, so the hour of `10:00:00+04:00` is checked as 10:00 UTC. Only checked when `kind` is `partner_4hr`; omit it to have the order collected as soon as possible.", "example": "2026-11-02T06:00:00Z", "nullable": true, "type": "string" }, "service_kind": { "$ref": "#/components/schemas/OrderRequestKind" }, "uuid": { "description": "Your idempotency key: generate one per order and resend the same value on a retry. Resending a `uuid` your account already used returns the original order with 200, unchanged (the new body is ignored), and no second order is created. A malformed `uuid`, or one another account used, is rejected with 422. Omit it and Quiqup generates one.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "origin", "destination", "items" ], "title": "OrderRequest", "type": "object" }, "OrderRequestAddress": { "description": "A pickup (`origin`) or delivery (`destination`) point and its contact.", "properties": { "address": { "properties": { "address1": { "description": "Building and street, e.g. `Example Tower, 1st Road`.", "maxLength": 320, "minLength": 1, "type": "string" }, "address2": { "description": "Area or unit, e.g. `Business Bay` or `Office 104`.", "nullable": true, "type": "string" }, "apartment_number": { "description": "Apartment number", "nullable": true, "type": "string" }, "building_name": { "description": "Building name", "nullable": true, "type": "string" }, "city": { "description": "City the address is located in", "nullable": true, "type": "string" }, "coordinates": { "$ref": "#/components/schemas/OrderRequestAddressCoordinates" }, "coords": { "description": "The point as exactly two numbers, longitude FIRST: `[lng, lat]`, e.g. `[55.2708, 25.2048]`. Any other length is ignored and the address is located from its text.", "example": [ 55.2708, 25.2048 ], "nullable": true, "type": "array" }, "country": { "description": "The country, e.g. `AE` or `UAE`. An order (other than a return) whose destination country differs from its pickup country is made an export.", "nullable": true, "type": "string" }, "ksa_national_address": { "description": "KSA National Address", "nullable": true, "type": "string" }, "notes": { "$ref": "#/components/schemas/OrderRequestNotes" }, "postcode": { "description": "ZIP or postal code the address is located in", "nullable": true, "type": "string" }, "town": { "description": "Town or city, e.g. `Dubai`.", "nullable": true, "type": "string" } }, "required": [ "address1" ], "title": "Address", "type": "object" }, "contact_email": { "description": "The customer's email. Needed on export orders.", "type": "string" }, "contact_name": { "description": "Who the courier asks for.", "type": "string" }, "contact_phone": { "description": "With the country code, e.g. `+971500000000`.", "type": "string" }, "emirate": { "description": "Emirate", "nullable": true, "type": "string" }, "notes": { "$ref": "#/components/schemas/OrderRequestNotes" } }, "required": [ "contact_name", "contact_phone", "address" ], "title": "OrderRequestAddress", "type": "object" }, "OrderRequestAddressCoordinates": { "description": "The point, as `{lat, lng}`. Same as `coords`; send one or the other. Without a valid point Quiqup locates the address from its text.", "nullable": true, "properties": { "lat": { "$ref": "#/components/schemas/OrderRequestAnyValue" }, "lng": { "$ref": "#/components/schemas/OrderRequestAnyValue" } }, "required": [ "lat", "lng" ], "title": "OrderRequestAddressCoordinates", "type": "object" }, "OrderRequestAnyValue": { "anyOf": [ { "nullable": true, "type": "string" }, { "nullable": true, "type": "number" } ], "nullable": true, "title": "OrderRequestAnyValue", "type": "object" }, "OrderRequestDisallowedPaymentTypes": { "description": "Payment methods to refuse on a `paid_on_delivery` order, e.g. `[\"cash\"]` to accept card only. The order's `allowed_payment_types` is what is left.", "items": { "$ref": "#/components/schemas/OrderRequestDisallowedPaymentTypesValues" }, "nullable": true, "title": "OrderRequestDisallowedPaymentTypes", "type": "array" }, "OrderRequestDisallowedPaymentTypesValues": { "description": "A way the customer may not pay on delivery.", "enum": [ "cash", "card" ], "title": "OrderRequestDisallowedPaymentTypesValues", "type": "string" }, "OrderRequestItem": { "description": "One parcel: one box or bag, with its own label.", "properties": { "metadata": { "properties": {}, "title": "ItemMetadata", "type": "object" }, "name": { "description": "A label for the parcel, e.g. `Parcel 1`. Keep it short. Defaults to the barcode.", "type": "string" }, "parcel_barcode": { "description": "Leave it empty and Quiqup generates the barcode (`{order id}-1`, `-2`, ...) and prints it on the label. Send one only if you print your own labels; two parcels of an order cannot share one.", "nullable": true, "type": "string" }, "quantity": { "description": "Send 1. One entry is one parcel, not a count of boxes.", "type": "integer" } }, "title": "OrderRequestItem", "type": "object" }, "OrderRequestItemsInfo": { "properties": { "quantity": { "description": "Quantity", "type": "integer" }, "sku": { "description": "SKU", "type": "string" } }, "title": "OrderRequestItemsInfo", "type": "object" }, "OrderRequestKind": { "description": "The service. Omit it and your account's default service is used, normally `partner_same_day`. The services and their delivery promises are described at https://developer-docs.quiqup.com/docs/lastmile/create-an-order. An account can only use the services agreed with Quiqup.", "enum": [ "partner_next_day", "partner_same_day", "partner_return", "partner_standard", "partner_on_demand", "partner_4hr", "partner_store", "partner_fulfillment", "partner_q_commerce", "partner_export" ], "title": "OrderRequestKind", "type": "string" }, "OrderRequestMetadata": { "nullable": true, "properties": { "items_info": { "description": "Items Info Metadata", "items": { "$ref": "#/components/schemas/OrderRequestItemsInfo" }, "type": "array" } }, "title": "OrderRequestMetadata", "type": "object" }, "OrderRequestNotes": { "description": "Free-text notes for the courier.", "nullable": true, "title": "OrderRequestNotes", "type": "string" }, "OrderRequestPaymentAmountValue": { "anyOf": [ { "nullable": false, "type": "string" }, { "nullable": false, "type": "number" } ], "nullable": false, "title": "OrderRequestPaymentAmountValue", "type": "object" }, "OrderRequestProduct": { "description": "Request params for a single product", "properties": { "barcode": { "description": "The product's own barcode (EAN, UPC, GTIN), not the parcel's `parcel_barcode`.", "nullable": true, "type": "string" }, "country_of_origin": { "description": "ISO 3166-1 alpha-2 code, e.g. `CN`. Required on export orders.", "nullable": true, "type": "string" }, "dangerous_goods": { "description": "The product dangerous goods", "nullable": true, "type": "boolean" }, "description": { "description": "The product name. Keep it short: 18 characters is safe for every export carrier.", "nullable": true, "type": "string" }, "height": { "description": "Centimetres.", "nullable": true, "type": "number" }, "hs_code": { "description": "Harmonised System code. Required on export orders.", "nullable": true, "type": "string" }, "length": { "description": "Centimetres.", "nullable": true, "type": "number" }, "quantity": { "description": "How many of this product are in the shipment.", "nullable": true, "type": "integer" }, "selling_price": { "description": "Unit price, used as the customs value. Required on export orders.", "nullable": true, "type": "number" }, "sku": { "description": "Your stock code.", "nullable": true, "type": "string" }, "weight": { "description": "Kilograms. Required on export orders.", "nullable": true, "type": "number" }, "width": { "description": "Centimetres.", "nullable": true, "type": "number" } }, "title": "OrderRequestProduct", "type": "object" }, "OrderRequestRegistrationNumber": { "description": "Registration number for customs declarations (e.g., MIRSAL2)", "properties": { "issuer_country_code": { "description": "ISO country code of the issuer (e.g., AE)", "nullable": true, "type": "string" }, "type_code": { "description": "The type code of the registration number (e.g., MIRSAL2)", "nullable": true, "type": "string" }, "value": { "description": "The registration number value", "nullable": true, "type": "string" } }, "title": "OrderRequestRegistrationNumber", "type": "object" }, "OrderRequestRequiredDocuments": { "description": "Leave it out or send `[]`. The proof of delivery your account is set up to require is added to every order automatically.", "items": { "$ref": "#/components/schemas/OrderRequestRequiredDocumentsValues" }, "nullable": true, "title": "OrderRequestRequiredDocuments", "type": "array" }, "OrderRequestRequiredDocumentsValues": { "enum": [ "customer_identification_photo" ], "title": "OrderRequestRequiredDocumentsValues", "type": "string" }, "OrderResponse": { "description": "One order, wrapped in `order`.", "example": { "order": { "allowed_payment_types": [ "cash", "card" ], "billing_identifier": null, "brand_name": "Example Brand", "collection_attempts": 0, "collection_time": { "collection_after": "2026-10-06T16:47:00.000+04:00", "collection_before": "2026-10-06T18:47:00.000+04:00" }, "created_at": "2026-10-06T16:46:56.000+04:00", "delivery_attempts": 0, "delivery_time": { "delivery_after": "2026-10-06T16:46:56.000+04:00", "delivery_before": "2026-10-07T23:00:00.000+04:00" }, "destination": { "address": { "address1": "1st Road", "address2": "104G", "coordinates": { "lat": 25.2048, "lng": 55.2708 }, "country": "UAE", "id": "2000002", "town": "Dubai" }, "contact_email": "customer@example.com", "contact_name": "Customer name", "contact_phone": "+971500000000", "id": "3000002", "tracking_url": "https://track-ae.quiqup.com/00000000000000000000000000000002", "zone": { "sector": "Business Bay" } }, "id": 10000001, "item_quantity_count": 1, "items": [ { "id": "4000001", "name": "Parcel 1", "parcel_barcode": "10000001-1", "parcel_barcode_generated_by": "quiqup", "quantity": 1 } ], "kind": "partner_same_day", "origin": { "address": { "address1": "Example Warehouse, Street 1", "address2": "Al Quoz Industrial Area 4", "coordinates": { "lat": 25.135, "lng": 55.23 }, "country": "UAE", "id": "2000001", "town": "Dubai" }, "contact_name": "Warehouse contact", "contact_phone": "+971500000000", "id": "3000001", "tracking_url": "https://track-ae.quiqup.com/00000000000000000000000000000001" }, "partner_order_id": "PARTNER-ORDER-ID", "payment_amount": "0.0", "payment_mode": "pre_paid", "region_name": "Dubai", "required_documents": [], "service_kind": "partner_same_day", "state": "pending", "state_updated_at": "2026-10-06T16:46:56.000+04:00", "submitted_at": "2026-10-06T16:46:56.000+04:00", "tracking_url": "https://track-parcel.quiqup.com/00000000-0000-4000-8000-000000000001", "user": { "email": "merchant@example.com", "fullname": "Example Merchant", "id": 15 }, "uuid": "00000000-0000-4000-8000-000000000001" } }, "properties": { "order": { "$ref": "#/components/schemas/Order" } }, "required": [ "order" ], "title": "OrderResponse", "type": "object" }, "OrderWebhookEvent": { "description": "The payload Quiqup POSTs to your webhook endpoint when an order changes state.\n\nRegistration, signature verification, timeouts, retries, replay and the receiver rules are documented once, in [Webhooks](/docs/webhooks). Read that page before building a receiver.", "properties": { "action": { "description": "Always `update`.", "type": "string" }, "payload": { "properties": { "allowed_payment_types": { "items": { "type": "string" }, "type": "array" }, "billing_identifier": { "description": "Set only when the order was created with one. Otherwise empty or `null`.", "nullable": true, "type": "string" }, "brand_name": { "type": "string" }, "business_contact_id": { "type": "string" }, "business_partner_id": { "description": "The id of the account that owns the order. Use it to route events when one receiver serves several accounts.", "type": "string" }, "cancelled_at": { "format": "date-time", "nullable": true, "type": "string" }, "client_order_id": { "description": "The order id again, the same value as `id`.", "type": "integer" }, "collection_after": { "format": "date-time", "nullable": true, "type": "string" }, "collection_attempts": { "type": "integer" }, "collection_before": { "format": "date-time", "nullable": true, "type": "string" }, "core_api_user_id": { "type": "integer" }, "courier_id": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "delivered_at": { "format": "date-time", "nullable": true, "type": "string" }, "delivery_after": { "format": "date-time", "nullable": true, "type": "string" }, "delivery_attempts": { "type": "integer" }, "delivery_before": { "format": "date-time", "nullable": true, "type": "string" }, "delivery_failure_reason": { "description": "Empty or `null` until a delivery fails.", "nullable": true, "type": "string" }, "destination": { "$ref": "#/components/schemas/OrderWebhookWaypoint" }, "display_items_info": { "type": "boolean" }, "external_order_id": { "type": "string" }, "failed_at": { "format": "date-time", "nullable": true, "type": "string" }, "fragile": { "type": "boolean" }, "id": { "type": "integer" }, "item_quantity_count": { "type": "integer" }, "items": { "items": { "properties": { "id": { "description": "A string, as on the create and `GET` responses.", "type": "string" }, "name": { "type": "string" }, "parcel_barcode": { "type": "string" }, "parcel_barcode_generated_by": { "type": "string" }, "quantity": { "type": "integer" }, "sku": { "type": "string" }, "weight": { "type": "number" } }, "type": "object" }, "type": "array" }, "kind": { "description": "Can arrive empty in a webhook. Read the service from `service_kind`.", "type": "string" }, "metadata": { "type": "object" }, "mission_id": { "type": "string" }, "notes": { "nullable": true, "type": "string" }, "origin": { "$ref": "#/components/schemas/OrderWebhookWaypoint" }, "otp_code": { "type": "string" }, "partner_order_id": { "description": "Your reference. Empty for orders created in Quiqdash.", "type": "string" }, "payment_amount": { "description": "A number here, where the API responses send it as a string.", "type": "number" }, "payment_mode": { "type": "string" }, "region": { "type": "string" }, "region_name": { "type": "string" }, "required_documents": { "items": { "type": "string" }, "type": "array" }, "scheduled_for": { "format": "date-time", "nullable": true, "type": "string" }, "service_kind": { "description": "The service the order was created with, the `kind` sent to Create an order.", "type": "string" }, "sku_info": { "nullable": true, "type": "string" }, "state": { "type": "string" }, "state_updated_at": { "description": "When the state changed, in UTC with a `Z` and fractional seconds. Order events by this field.", "format": "date-time", "type": "string" }, "submitted_at": { "format": "date-time", "type": "string" }, "total_amount": { "type": "number" }, "tracking_url": { "type": "string" }, "uuid": { "type": "string" }, "weight": { "type": "number" }, "weight_unit": { "type": "string" } }, "type": "object" }, "sent_at": { "description": "When Quiqup dispatched the delivery, in UTC with a `Z`, to the second. Not when the state changed.", "format": "date-time", "type": "string" }, "type": { "description": "Always `order`. The event name is not in the body; switch on `payload.state`.", "type": "string" } }, "type": "object" }, "OrderWebhookWaypoint": { "description": "The `origin` or `destination` of an `OrderWebhookEvent`. Narrower than the waypoint on `GET /orders/{order_id}`.", "properties": { "address": { "properties": { "address1": { "type": "string" }, "address2": { "nullable": true, "type": "string" }, "apartment_number": { "nullable": true, "type": "string" }, "building_name": { "nullable": true, "type": "string" }, "coordinates": { "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } }, "type": "object" }, "country": { "type": "string" }, "id": { "type": "integer" }, "town": { "nullable": true, "type": "string" } }, "type": "object" }, "arrived_at": { "format": "date-time", "nullable": true, "type": "string" }, "contact_name": { "type": "string" }, "contact_phone": { "type": "string" }, "finished_at": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "type": "integer" }, "notes": { "nullable": true, "type": "string" }, "signature": { "properties": { "url": { "nullable": true, "type": "string" } }, "type": "object" }, "tracking_token": { "type": "string" }, "tracking_url": { "type": "string" } }, "type": "object" }, "Product": { "properties": { "barcode": { "description": "Product barcode (EAN, UPC, GTIN)", "type": "string" }, "country_of_origin": { "description": "The product country of origin", "type": "string" }, "dangerous_goods": { "description": "The product dangerous goods", "type": "boolean" }, "description": { "description": "The product description", "type": "string" }, "height": { "description": "The product height", "type": "number" }, "hs_code": { "description": "The product HS code", "type": "string" }, "length": { "description": "The product length", "type": "number" }, "quantity": { "description": "The product quantity", "type": "integer" }, "selling_price": { "description": "The product selling price", "type": "number" }, "sku": { "description": "The product SKU", "type": "string" }, "weight": { "description": "The product weight", "type": "number" }, "width": { "description": "The product width", "type": "number" } }, "title": "Product", "type": "object" }, "ProjectionPending": { "description": "The change was recorded; the order could not be read back in time.", "example": { "order_id": "10000001", "status": "pending_projection" }, "properties": { "order_id": { "description": "The order id from the path.", "type": "string" }, "status": { "enum": [ "pending_projection" ], "type": "string" } }, "required": [ "order_id", "status" ], "title": "ProjectionPending", "type": "object" }, "Unauthorized": { "description": "The token was rejected. Always this exact body, never the `ApiError` envelope.", "example": { "error": "unauthorized" }, "properties": { "error": { "enum": [ "unauthorized" ], "type": "string" } }, "required": [ "error" ], "title": "Unauthorized", "type": "object" } }, "securitySchemes": { "bearerToken": { "description": "A Bearer token generated in Quiqdash under Organization > API keys. The usual path.", "scheme": "bearer", "type": "http" }, "oauthToken": { "description": "Client credentials, issued by Quiqup on request. Only needed by platforms whose setup screens require a Client ID and Client Secret.\n\nThe token URL follows the environment: `https://api.staging.quiqup.com/oauth/token` on staging, `https://api-ae.quiqup.com/oauth/token` on production.", "flows": { "clientCredentials": { "scopes": {}, "tokenUrl": "https://api.staging.quiqup.com/oauth/token" } }, "type": "oauth2" } } }, "info": { "contact": { "email": "apisupport@quiqup.com" }, "description": "Create and manage Last-mile orders on `api-ae.quiqup.com`.\n\nThe order operations in this reference are generated from the API's own code, so they always describe what the API accepts and returns. For a walkthrough, see [Create an order](/docs/lastmile/create-an-order).\n\nTwo responses are not JSON: the label download returns a PDF, and the webhook is a request Quiqup sends to you, shown as a callback on Create an order. See [Webhooks](/docs/webhooks).", "license": { "name": "Proprietary", "url": "https://quiqup.com/terms" }, "title": "Last-mile Orders API", "version": "1.0.0" }, "openapi": "3.0.0", "paths": { "/order_label/{order_ids}": { "get": { "description": "Returns the AWB label for one order, or for several in one PDF. Save it, print it and\nattach it to the parcel: couriers and warehouse staff scan its barcode at every step.\nYou can download it before or after the order is ready for collection.\n\nSend one id, `/order_label/10000001`, or several separated by commas,\n`/order_label/10000001,10000002`. A batch returns a single PDF with every order's\nlabels, one page per parcel.\n\nThe response is always a PDF, never JSON, so write it to a file rather than parsing it.", "operationId": "download-the-awb-label", "parameters": [ { "description": "One order id, `order.id` in the create response, or several separated by commas.", "example": "10000001,10000002", "in": "path", "name": "order_ids", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "format": "binary", "type": "string" } } }, "description": "The labels, as one PDF. `Content-Disposition` names the file `.pdf` for a\nsingle order and `s.pdf` for a batch.\n\nAn id that does not match one of your orders can still answer `200` with\n`Content-Type: application/pdf` and an empty body. Check the content length before\nwriting the response to a file.", "headers": { "Content-Disposition": { "description": "`attachment; filename=10000001.pdf`, or `attachment; filename=s2026-01-15.pdf` for a batch.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthenticated", "details": null, "message": "invalid auth param" }, "schema": { "properties": { "code": { "enum": [ "unauthenticated" ], "type": "string" }, "details": { "nullable": true, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } }, "description": "The token is missing, expired or not valid. This path is served by a different service\nfrom the other order operations, so the body has this shape, not `{\"error\": \"unauthorized\"}`." }, "500": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "The label could not be generated. The body is a plain-text message." } }, "security": [ { "bearerToken": [] }, { "oauthToken": [] } ], "summary": "Download the AWB label", "tags": [ "Orders" ] } }, "/orders": { "get": { "callbacks": {}, "description": "Returns one page of the orders submitted between `from` and `to`, newest first. You see\nthe orders of your account and of the other users on the same business account.\n\n**Pending orders are left out unless you ask for them.** With no `filters[state]`, the\nlist holds every state except `pending`, and every other filter, `filters[partner_order_id]`\nincluded, applies on top of that. To find an order you may have created but not released\n(for example after a create that timed out), name `pending` in `filters[state]`, e.g.\n`filters[state]=pending,ready_for_collection&filters[partner_order_id]=PARTNER-ORDER-ID`, and\npick the result whose `partner_order_id` is exactly yours.\n\n**`total` and `total_pages` are not always exact.** When you filter only by dates, or by\ndates and state, they come from a precomputed count that can be off, and read `total: 1`\nwhen nothing matches. Adding any other filter makes them exact. To read everything,\nrequest pages until `results` holds fewer than `per_page` orders.\n\n`from`, `to`, `page` and `per_page` must be valid: a missing one returns 422, but a date\nor number that does not parse returns 500.\n", "operationId": "list-orders", "parameters": [ { "description": "First day, `YYYY-MM-DD` (`DD-MM-YYYY` also works). Orders are matched on when they were submitted, in UAE time (UTC+4), and both days are included.", "example": "2026-10-01", "in": "query", "name": "from", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "Last day, included. Same format as `from`.", "example": "2026-10-08", "in": "query", "name": "to", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "Page number, from 1.", "example": 1, "in": "query", "name": "page", "required": true, "schema": { "minimum": 1, "type": "integer" } }, { "description": "Orders per page.", "example": 50, "in": "query", "name": "per_page", "required": true, "schema": { "minimum": 1, "type": "integer" } }, { "description": "Comma-separated order states, e.g. `ready_for_collection,out_for_delivery`. Defaults to every state except `pending`. An unknown or wrongly-cased state matches nothing.", "in": "query", "name": "filters[state]", "required": false, "schema": { "type": "string" } }, { "description": "One reference of your own. Matches any order whose `partner_order_id` contains it, ignoring case, so `SHOP-1` also matches `SHOP-10`: check `partner_order_id` in the results when you need one exact order. Subject to the state default above, so add `pending` to `filters[state]` to find pending orders.", "in": "query", "name": "filters[partner_order_id]", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated order ids. Values that are not order ids are ignored.", "in": "query", "name": "filters[order_id]", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated service kinds, e.g. `partner_same_day,partner_next_day`.", "in": "query", "name": "filters[service_kind]", "required": false, "schema": { "type": "string" } }, { "description": "Sort order. Defaults to newest submitted first.", "in": "query", "name": "order_by", "required": false, "schema": { "enum": [ "created_at_asc", "state_updated_at_asc", "state_updated_at_desc", "delivery_before_asc", "delivery_before_desc", "delivery_attempts_asc", "delivery_attempts_desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" } } }, "description": "One page of orders." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } }, "description": "The token is missing, expired or not valid." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldErrors" } } }, "description": "`from`, `to`, `page` or `per_page` is missing." } }, "security": [ { "bearerToken": [] }, { "oauthToken": [] } ], "summary": "List orders", "tags": [ "Orders" ] }, "post": { "callbacks": { "orderStateChange": { "https://your-endpoint.example.com/quiqup-webhook": { "post": { "description": "Quiqup POSTs this to the URL you registered in **Quiqdash > Integrations > Webhooks**. There is no per-order callback URL.\n\nThe payload shape is the `OrderWebhookEvent` schema. Everything else about receiving it is in [Webhooks](/docs/webhooks).", "operationId": "order-webhook-event", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx. The body is ignored." } }, "summary": "Order state change" } } } }, "description": "Creates an order in the `pending` state. A pending order shows in Quiqdash but is not\ndispatched: mark it `ready_for_collection` (`PUT /orders/{id}/ready_for_collection`) once\nthe parcel can be collected, or send `ready_for_collection: true` here to skip that step.\n\n`kind` is the service, e.g. `partner_next_day`, `partner_same_day`, `partner_4hr`,\n`partner_return` or `partner_export` (the request schema lists every value). `items` are\nthe parcels Quiqup carries, one label per item; `products` are the goods inside them.\n\nSend a `uuid` so a retry does not create a second order: resending the same `uuid` from the\nsame account returns the original order with 200 and no second order is created. A `uuid`\nthat is not a valid UUID, or that belongs to another account, is rejected with 422.\n\nThe full guide, with every field and a worked example, is at\nhttps://developer-docs.quiqup.com/docs/lastmile/create-an-order, and the order states at\nhttps://developer-docs.quiqup.com/docs/order-lifecycle.\n", "operationId": "create-an-order", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" } } }, "description": "Order Request params", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } }, "description": "Idempotent replay: an order with this `uuid` already exists for your account. That order is returned unchanged, and no second order is created." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } }, "description": "The order was created." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The order could not be submitted, e.g. the account cannot place orders with its current payment setup, two `items` share a `parcel_barcode`, a `partner_return` has no `reason`, or `scheduled_for` is not a valid time." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } }, "description": "The token is missing, expired or not valid." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The request was rejected: it failed validation, repeats an order reference, uses a service the account does not have, or supplies a `uuid` that is malformed or belongs to another account." } }, "security": [ { "bearerToken": [] }, { "oauthToken": [] } ], "summary": "Create an order", "tags": [ "Orders" ] } }, "/orders/batch/set_cancelled": { "put": { "callbacks": {}, "description": "Cancels one or more of your orders. A last-mile order can be cancelled while it is `pending`\nor `ready_for_collection`; a fulfilment order only while it is `pending`. Once a courier has\nbeen assigned to collect or deliver it, the call is refused and the order has to be cancelled\nby Quiqup support.\n\nThe state and courier checks cover the whole batch: if any order fails them, nothing is\ncancelled. A 422 from the state check lists the order ids that failed it; a 422 from the\ncourier check is one message for the whole batch, without ids. Any other 422 can follow a\npartial cancellation, so\nread the orders back with `GET /orders/{id}` to see which were cancelled.\n", "operationId": "cancel-pending-orders", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrdersRequest" } } }, "description": "The orders to cancel.", "required": false }, "responses": { "201": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Order" }, "type": "array" } } }, "description": "The cancelled orders, as a bare array (not wrapped)." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchProjectionPending" } } }, "description": "The cancellation was recorded but the orders could not be read back in time. Do not retry: read them with `GET /orders/{id}` instead. Also sent with the header `x-projection-pending: true`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } }, "description": "The token is missing, expired or not valid." }, "422": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/ErrorMessage" } ] } } }, "description": "An order is in a state that cannot be cancelled or already has a courier assigned (nothing was cancelled), or the cancellation itself failed. Sent as the `ApiError` envelope, except an unexpected failure, which is an `error` message." } }, "security": [ { "bearerToken": [] }, { "oauthToken": [] } ], "summary": "Cancel orders", "tags": [ "Orders" ] } }, "/orders/{client_order_id}/parcels": { "post": { "callbacks": {}, "description": "Adds one parcel to a `pending` order and returns the new parcel on its own, not the whole\norder. A label is generated per parcel. Once the order has left `pending` the call is\nrejected with 422.\n", "operationId": "add-a-parcel-to-a-pending-order", "parameters": [ { "description": "The order id, `order.id` in the create response.", "in": "path", "name": "client_order_id", "required": true, "schema": { "example": 10000001, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddParcelToOrderRequest" } } }, "description": "The parcel to add.", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewParcel" } } }, "description": "The parcel that was added." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } }, "description": "The token is missing, expired or not valid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } }, "description": "The order does not exist or was not created by your account." }, "422": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/ErrorMessage" } ] } } }, "description": "`name` is missing or longer than 255 characters (the `ApiError` envelope), or the order is no longer `pending` (an `error` message)." } }, "security": [ { "bearerToken": [] }, { "oauthToken": [] } ], "summary": "Add a parcel to a pending order", "tags": [ "Orders" ] } }, "/orders/{client_order_id}/parcels/{core_api_item_id}": { "delete": { "callbacks": {}, "description": "Removes one parcel from a `pending` order. An order must keep at least one parcel, so\nremoving the last one is rejected with 422. Takes no request body.\n", "operationId": "remove-a-parcel-from-a-pending-order", "parameters": [ { "description": "The order id, `order.id` in the create response.", "in": "path", "name": "client_order_id", "required": true, "schema": { "example": 10000001, "type": "integer" } }, { "description": "The parcel id: `order.items[].id` on the order (sent there as a string), or `id` in the add-a-parcel response.", "in": "path", "name": "core_api_item_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "text/plain": { "schema": { "example": "true", "type": "string" } } }, "description": "The parcel was removed. The body is the literal `true`, sent with no Content-Type header." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } }, "description": "The token is missing, expired or not valid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } }, "description": "The order does not exist or was not created by your account." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } }, "description": "The order is no longer `pending`, it has only this parcel left, or no parcel on it matches `core_api_item_id`." } }, "security": [ { "bearerToken": [] }, { "oauthToken": [] } ], "summary": "Remove a parcel from a pending order", "tags": [ "Orders" ] } }, "/orders/{id}": { "get": { "callbacks": {}, "description": "Returns one order, wrapped in `order`. You can read the orders your account created; any\nother id, including one that does not exist, returns 403.\n", "operationId": "retrieve-an-order", "parameters": [ { "description": "The order id, `order.id` in the create response.", "in": "path", "name": "id", "required": true, "schema": { "example": 10000001, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } }, "description": "The order." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } }, "description": "The token is missing, expired or not valid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } }, "description": "The order does not exist or was not created by your account." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldErrors" } } }, "description": "`id` is not a valid order id." } }, "security": [ { "bearerToken": [] }, { "oauthToken": [] } ], "summary": "Retrieve an order", "tags": [ "Orders" ] } }, "/orders/{id}/ready_for_collection": { "put": { "callbacks": {}, "description": "Releases a `pending` order to Quiqup: from now on it is planned for collection. Call it once\nthe parcel is packed and labelled. Orders left `pending` are never collected. You can skip\nthis call by sending `ready_for_collection: true` when you create the order.\n\nRead `state` in the response rather than assuming the order moved: in some cases the call is\naccepted while the order stays where it is until Quiqup has finished checking it, and it then\nmoves on by itself.\n\nThis call books the shipment, so a booking problem (on an export order, for example a missing\ncustoms detail) is reported here with 422 and the order stays `pending`. See\nhttps://developer-docs.quiqup.com/docs/lastmile/create-an-order and the order states at\nhttps://developer-docs.quiqup.com/docs/order-lifecycle.\n", "operationId": "mark-ready-for-collection", "parameters": [ { "description": "The order id, `order.id` in the create response.", "in": "path", "name": "id", "required": true, "schema": { "example": 10000001, "type": "integer" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } }, "description": "The order, wrapped in `order`." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectionPending" } } }, "description": "The release was recorded but the order could not be read back in time. Do not retry: read the order with `GET /orders/{id}` instead. Also sent with the header `x-projection-pending: true`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } }, "description": "The token is missing, expired or not valid." }, "422": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/ErrorMessage" } ] } } }, "description": "The order was not released. Its state does not allow it, the account cannot place orders with its payment setup, or a Saudi address has no valid national address (the `ApiError` envelope); or the id is not one of your orders, the account is blocked, or the shipment could not be booked (an `error` message)." } }, "security": [ { "bearerToken": [] }, { "oauthToken": [] } ], "summary": "Mark an order ready for collection", "tags": [ "Orders" ] } } }, "security": [], "servers": [ { "description": "Production", "url": "https://api-ae.quiqup.com" }, { "description": "Staging", "url": "https://api.staging.quiqup.com" } ], "tags": [] }