Skip to content

Fulfilment API (1.0.0)

This is the API documentation for the Fulfilment API.

Download OpenAPI description
Languages
Servers
Mock server
https://developer-docs.quiqup.com/_mock/openapi/
Production
https://platform-api.quiqup.com/
Staging
https://platform-api.staging.quiqup.com/
Operations
Operations
Operations

Request

Create a Fulfilment Order

📌 Description

This endpoint allows you to create a fulfilment order. The service_kind field determines the picking & packing SLA based on your account's cut-off times and automatically selects the appropriate delivery service with the carrier.

Available Service Kinds:

  • partner_next_day → Next-day delivery (standard service), available in UAE & KSA.
  • partner_same_day → Same-day delivery, currently only available in the UAE.
  • partner_4hr → 4-hour deliveries, only available in Dubai.
  • partner_export → International shipments, carrier allocation is rule-based.

Additionally, return orders can be created by setting is_return to true.

🔹 Use Cases

  • Creating a new customer order for fulfilment.
  • Processing a return order by setting is_return: true.
  • Handling multi-item orders with various delivery options.
  • Managing payment-on-delivery orders (payment_mode: paid_on_delivery).
Security
OAuth2
Bodyapplication/json
billing_addressobject(types.AddressRequest)
billing_identifierstring(BillingIdentifier is a custom identifier for billing purposes )

Optional: Used for internal billing reference

carrierstring(Carrier specifies the delivery carrier for the order )

Optional: Used to specify which carrier should handle the delivery

currencystring(Currency is the 3-letter ISO currency code for the order (e.g., AED) )required
delivery_optionsArray of strings(DeliveryOptions specifies special delivery instructions )

Optional: Array of special delivery requirements

Items Value"customer_identification_photo"
incotermstring(Incoterm specifies the international commercial terms for the order )

Optional: Used for international shipments to define delivery terms

initial_order_idstring(InitialOrderID is required when IsReturn is true )

Required only for return orders, references the original order

is_returnboolean(IsReturn indicates if this is a return order )

Optional: Set to true for return deliveries

notesstring(Notes contains any additional delivery instructions )

Optional: Maximum 255 characters

origin_addressobject(types.AddressRequest)required
origin_address.​address1string(Primary street address. )required
origin_address.​address2string(Additional address details (e.g., suite, apt number). )
origin_address.​citystring(City of the address. )required
origin_address.​coordinateobject(Geographic coordinates. )
origin_address.​countrystring(Country name. )
origin_address.​country_codestring(ISO2 Country code (required). )required
origin_address.​emailstring(Email address associated with the address for contact. )required
origin_address.​first_namestring(First name of the person associated with the address. )required
origin_address.​ksa_national_addressstring(National address code (e.g., Saudi Arabia's national address system). )
origin_address.​last_namestring(Last name of the person associated with the address. )
origin_address.​namestring(Full name used for addressing. )
origin_address.​phonestring(Phone number. )required
origin_address.​postcodestring(Postal code (could be used instead of or in addition to zip). )
origin_address.​statestring(State, if applicable (could be similar to province). )
partner_order_idstring(PartnerOrderID is your unique reference for the order )required

Required: Must be unique across all orders

payment_amountnumber(PaymentAmount is the total amount to be collected from the customer )required
payment_modestring(types.PaymentMode)required
Enum"pre_paid""paid_on_delivery"
productsArray of objects(Products is an array of products to be delivered )
service_kindstring(ServiceKind represents the type of delivery service )required
Enum"partner_next_day""partner_same_day""partner_4hr""partner_export""partner_store"
shipping_addressobject(types.AddressRequest)required
shipping_address.​address1string(Primary street address. )required
shipping_address.​address2string(Additional address details (e.g., suite, apt number). )
shipping_address.​citystring(City of the address. )required
shipping_address.​coordinateobject(Geographic coordinates. )
shipping_address.​countrystring(Country name. )
shipping_address.​country_codestring(ISO2 Country code (required). )required
shipping_address.​emailstring(Email address associated with the address for contact. )required
shipping_address.​first_namestring(First name of the person associated with the address. )required
shipping_address.​ksa_national_addressstring(National address code (e.g., Saudi Arabia's national address system). )
shipping_address.​last_namestring(Last name of the person associated with the address. )
shipping_address.​namestring(Full name used for addressing. )
shipping_address.​phonestring(Phone number. )required
shipping_address.​postcodestring(Postal code (could be used instead of or in addition to zip). )
shipping_address.​statestring(State, if applicable (could be similar to province). )
curl -i -X POST \
  https://developer-docs.quiqup.com/_mock/openapi/api/fulfilment/orders \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "billing_address": {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "coordinate": {
        "latitude": 0,
        "longitude": 0
      },
      "country": "string",
      "country_code": "string",
      "email": "string",
      "first_name": "string",
      "ksa_national_address": "string",
      "last_name": "string",
      "name": "string",
      "phone": "string",
      "postcode": "string",
      "state": "string"
    },
    "billing_identifier": "string",
    "carrier": "string",
    "currency": "string",
    "delivery_options": [
      "customer_identification_photo"
    ],
    "incoterm": "string",
    "initial_order_id": "string",
    "is_return": true,
    "notes": "string",
    "origin_address": {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "coordinate": {
        "latitude": 0,
        "longitude": 0
      },
      "country": "string",
      "country_code": "string",
      "email": "string",
      "first_name": "string",
      "ksa_national_address": "string",
      "last_name": "string",
      "name": "string",
      "phone": "string",
      "postcode": "string",
      "state": "string"
    },
    "partner_order_id": "string",
    "payment_amount": 0,
    "payment_mode": "pre_paid",
    "products": [
      {
        "quantity": 0,
        "sku": "string"
      }
    ],
    "service_kind": "partner_next_day",
    "shipping_address": {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "coordinate": {
        "latitude": 0,
        "longitude": 0
      },
      "country": "string",
      "country_code": "string",
      "email": "string",
      "first_name": "string",
      "ksa_national_address": "string",
      "last_name": "string",
      "name": "string",
      "phone": "string",
      "postcode": "string",
      "state": "string"
    }
  }'

Responses

Success response

Bodyapplication/json
billing_addressobject(types.CreateFulfilmentOrderAddressResponse)
carrierstring(Delivery carrier for the order )
created_atstring(date-time)(Timestamp when the order was created )
currencystring(3-letter ISO currency code (e.g., AED, SAR) )
delivery_optionsArray of strings(Special delivery requirements )

Possible values: leave_at_door, customer_identification_photo

Items Value"customer_identification_photo"
errorsArray of objects(Array of error messages if any issues occurred )
idstring(Unique identifier for the fulfilment order )
incotermstring(International commercial terms for the order )
initial_order_idstring(Reference to the original order ID for returns )
is_returnboolean(Indicates if this is a return order )
notesstring(Additional delivery instructions or comments )
origin_addressobject(types.CreateFulfilmentOrderAddressResponse)
parcelsArray of objects(List of parcels associated with the order )
partner_order_idstring(Your unique reference for the order )
payment_amountnumber(Total amount to be collected from the customer )
payment_modestring(types.PaymentMode)
Enum"pre_paid""paid_on_delivery"
picking_order_createdboolean(Indicates if a picking order has been created )
productsArray of objects(List of products included in the order )
service_kindstring(Type of delivery service requested )

Possible values: partner_next_day, partner_same_day, partner_4hr, partner_export, partner_store

shipping_addressobject(types.CreateFulfilmentOrderAddressResponse)
statusstring(OrderStatus represents the possible states of an order )
Enum"pending""ready_for_collection""picking_started""out_for_collection""out_for_return""at_depot""received_at_depot""in_transit""out_for_delivery""collection_failed"
status_reasonstring(Reason for the current status (e.g., why an order was cancelled) )
tracking_urlstring(URL for basic order tracking )
tracking_url_advancestring(URL for advanced order tracking with more details )
updated_atstring(date-time)(Timestamp when the order was last updated )
uuidstring(UUID of the fulfilment order )
Response
application/json
{ "billing_address": { "address1": "string", "address2": "string", "city": "string", "coordinate": {}, "country": "string", "country_code": "string", "created_at": "2019-08-24T14:15:22Z", "email": "string", "first_name": "string", "ksa_national_address": "string", "last_name": "string", "name": "string", "phone": "string", "postcode": "string", "state": "string", "updated_at": "2019-08-24T14:15:22Z" }, "carrier": "string", "created_at": "2019-08-24T14:15:22Z", "currency": "string", "delivery_options": [ "customer_identification_photo" ], "errors": [ {} ], "id": "string", "incoterm": "string", "initial_order_id": "string", "is_return": true, "notes": "string", "origin_address": { "address1": "string", "address2": "string", "city": "string", "coordinate": {}, "country": "string", "country_code": "string", "created_at": "2019-08-24T14:15:22Z", "email": "string", "first_name": "string", "ksa_national_address": "string", "last_name": "string", "name": "string", "phone": "string", "postcode": "string", "state": "string", "updated_at": "2019-08-24T14:15:22Z" }, "parcels": [ {} ], "partner_order_id": "string", "payment_amount": 0, "payment_mode": "pre_paid", "picking_order_created": true, "products": [ {} ], "service_kind": "string", "shipping_address": { "address1": "string", "address2": "string", "city": "string", "coordinate": {}, "country": "string", "country_code": "string", "created_at": "2019-08-24T14:15:22Z", "email": "string", "first_name": "string", "ksa_national_address": "string", "last_name": "string", "name": "string", "phone": "string", "postcode": "string", "state": "string", "updated_at": "2019-08-24T14:15:22Z" }, "status": "pending", "status_reason": "string", "tracking_url": "string", "tracking_url_advance": "string", "updated_at": "2019-08-24T14:15:22Z", "uuid": "string" }

Request

Get a Fulfilment Order by ID

📌 Description

This endpoint retrieves the details of an existing fulfilment order using its unique ID.

🔹 Use Cases

  • Checking the status of a previously created fulfilment order.
  • Retrieving tracking details to share with customers.
  • Confirming order information before dispatch or customer communication.
  • Verifying payment and service type for an order.
Security
OAuth2
Path
idstringrequired
curl -i -X GET \
  'https://developer-docs.quiqup.com/_mock/openapi/api/fulfilment/orders/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success response

Bodyapplication/json
billing_addressobject(types.CreateFulfilmentOrderAddressResponse)
carrierstring(Delivery carrier for the order )
created_atstring(date-time)(Timestamp when the order was created )
currencystring(3-letter ISO currency code (e.g., AED, SAR) )
delivery_optionsArray of strings(Special delivery requirements )

Possible values: leave_at_door, customer_identification_photo

Items Value"customer_identification_photo"
errorsArray of objects(Array of error messages if any issues occurred )
idstring(Unique identifier for the fulfilment order )
incotermstring(International commercial terms for the order )
initial_order_idstring(Reference to the original order ID for returns )
is_returnboolean(Indicates if this is a return order )
notesstring(Additional delivery instructions or comments )
origin_addressobject(types.CreateFulfilmentOrderAddressResponse)
parcelsArray of objects(List of parcels associated with the order )
partner_order_idstring(Your unique reference for the order )
payment_amountnumber(Total amount to be collected from the customer )
payment_modestring(types.PaymentMode)
Enum"pre_paid""paid_on_delivery"
picking_order_createdboolean(Indicates if a picking order has been created )
productsArray of objects(List of products included in the order )
service_kindstring(Type of delivery service requested )

Possible values: partner_next_day, partner_same_day, partner_4hr, partner_export, partner_store

shipping_addressobject(types.CreateFulfilmentOrderAddressResponse)
statusstring(OrderStatus represents the possible states of an order )
Enum"pending""ready_for_collection""picking_started""out_for_collection""out_for_return""at_depot""received_at_depot""in_transit""out_for_delivery""collection_failed"
status_reasonstring(Reason for the current status (e.g., why an order was cancelled) )
tracking_urlstring(URL for basic order tracking )
tracking_url_advancestring(URL for advanced order tracking with more details )
updated_atstring(date-time)(Timestamp when the order was last updated )
uuidstring(UUID of the fulfilment order )
Response
application/json
{ "billing_address": { "address1": "string", "address2": "string", "city": "string", "coordinate": {}, "country": "string", "country_code": "string", "created_at": "2019-08-24T14:15:22Z", "email": "string", "first_name": "string", "ksa_national_address": "string", "last_name": "string", "name": "string", "phone": "string", "postcode": "string", "state": "string", "updated_at": "2019-08-24T14:15:22Z" }, "carrier": "string", "created_at": "2019-08-24T14:15:22Z", "currency": "string", "delivery_options": [ "customer_identification_photo" ], "errors": [ {} ], "id": "string", "incoterm": "string", "initial_order_id": "string", "is_return": true, "notes": "string", "origin_address": { "address1": "string", "address2": "string", "city": "string", "coordinate": {}, "country": "string", "country_code": "string", "created_at": "2019-08-24T14:15:22Z", "email": "string", "first_name": "string", "ksa_national_address": "string", "last_name": "string", "name": "string", "phone": "string", "postcode": "string", "state": "string", "updated_at": "2019-08-24T14:15:22Z" }, "parcels": [ {} ], "partner_order_id": "string", "payment_amount": 0, "payment_mode": "pre_paid", "picking_order_created": true, "products": [ {} ], "service_kind": "string", "shipping_address": { "address1": "string", "address2": "string", "city": "string", "coordinate": {}, "country": "string", "country_code": "string", "created_at": "2019-08-24T14:15:22Z", "email": "string", "first_name": "string", "ksa_national_address": "string", "last_name": "string", "name": "string", "phone": "string", "postcode": "string", "state": "string", "updated_at": "2019-08-24T14:15:22Z" }, "status": "pending", "status_reason": "string", "tracking_url": "string", "tracking_url_advance": "string", "updated_at": "2019-08-24T14:15:22Z", "uuid": "string" }

Request

Update a Fulfilment Order

📌 Description

This endpoint allows you to update an existing fulfilment order. Depending on the current order status, some fields may not be modifiable.

For example:

  • If the order is already out for delivery, the shipping address cannot be changed.
  • If the order has been picked and packed, modifications to products are no longer possible.
  • Orders that are cancelled or completed cannot be updated.

🔹 Use Cases

  • Updating the shipping address before the order is dispatched.
  • Modifying payment details before dispatched.
  • Adjusting product quantities before fulfilment begins.
  • Cancelling an order if it has not yet been picked and packed.
Security
OAuth2
Path
idstringrequired
Bodyapplication/json
billing_addressobject(types.AddressRequest)required
billing_address.​address1string(Primary street address. )required
billing_address.​address2string(Additional address details (e.g., suite, apt number). )
billing_address.​citystring(City of the address. )required
billing_address.​coordinateobject(Geographic coordinates. )
billing_address.​countrystring(Country name. )
billing_address.​country_codestring(ISO2 Country code (required). )required
billing_address.​emailstring(Email address associated with the address for contact. )required
billing_address.​first_namestring(First name of the person associated with the address. )required
billing_address.​ksa_national_addressstring(National address code (e.g., Saudi Arabia's national address system). )
billing_address.​last_namestring(Last name of the person associated with the address. )
billing_address.​namestring(Full name used for addressing. )
billing_address.​phonestring(Phone number. )required
billing_address.​postcodestring(Postal code (could be used instead of or in addition to zip). )
billing_address.​statestring(State, if applicable (could be similar to province). )
carrierstring(Carrier updates the delivery carrier for the order )

Optional: Used to specify which carrier should handle the delivery

incotermstring(Incoterm updates the international commercial terms for the order )

Optional: Used for international shipments to define delivery terms

origin_addressobject(types.AddressRequest)required
origin_address.​address1string(Primary street address. )required
origin_address.​address2string(Additional address details (e.g., suite, apt number). )
origin_address.​citystring(City of the address. )required
origin_address.​coordinateobject(Geographic coordinates. )
origin_address.​countrystring(Country name. )
origin_address.​country_codestring(ISO2 Country code (required). )required
origin_address.​emailstring(Email address associated with the address for contact. )required
origin_address.​first_namestring(First name of the person associated with the address. )required
origin_address.​ksa_national_addressstring(National address code (e.g., Saudi Arabia's national address system). )
origin_address.​last_namestring(Last name of the person associated with the address. )
origin_address.​namestring(Full name used for addressing. )
origin_address.​phonestring(Phone number. )required
origin_address.​postcodestring(Postal code (could be used instead of or in addition to zip). )
origin_address.​statestring(State, if applicable (could be similar to province). )
payment_amountnumber(PaymentAmount updates the amount to be collected )required
payment_modestring(types.PaymentMode)required
Enum"pre_paid""paid_on_delivery"
productsArray of objects(Products updates the list of products to be delivered )required

For updates, products can include additional fields to override catalog values

products[].​country_of_originstring(CountryOfOrigin overrides the product's country of origin for this order )

Optional: If not provided, uses the value from the product catalog

products[].​dimensionsobject(Dimensions overrides the product's dimensions for this order )

Optional: If not provided, uses the value from the product catalog

products[].​hs_codestring(HSCode overrides the product's HS code for this order )

Optional: If not provided, uses the value from the product catalog

products[].​quantityinteger(int64)(Quantity specifies the number of units to be delivered )required

Required: Must be at least 1 Minimum value: 1

products[].​selling_pricenumber(SellingPrice overrides the product's selling price for this order )

Optional: If not provided, uses the price from the product catalog

products[].​skustring(SKU (Stock Keeping Unit) uniquely identifies the product )required

Required: Must be a valid SKU from your product catalog Maximum length: 100 characters

products[].​weightnumber(Weight overrides the product's weight for this order )

Optional: If not provided, uses the value from the product catalog

products[].​weight_unitstring(WeightUnit specifies the unit of measurement for weight )

Optional: If not provided, uses the value from the product catalog

service_kindstring(ServiceKind represents the type of delivery service )required
Enum"partner_next_day""partner_same_day""partner_4hr""partner_export""partner_store"
shipping_addressobject(types.AddressRequest)required
shipping_address.​address1string(Primary street address. )required
shipping_address.​address2string(Additional address details (e.g., suite, apt number). )
shipping_address.​citystring(City of the address. )required
shipping_address.​coordinateobject(Geographic coordinates. )
shipping_address.​countrystring(Country name. )
shipping_address.​country_codestring(ISO2 Country code (required). )required
shipping_address.​emailstring(Email address associated with the address for contact. )required
shipping_address.​first_namestring(First name of the person associated with the address. )required
shipping_address.​ksa_national_addressstring(National address code (e.g., Saudi Arabia's national address system). )
shipping_address.​last_namestring(Last name of the person associated with the address. )
shipping_address.​namestring(Full name used for addressing. )
shipping_address.​phonestring(Phone number. )required
shipping_address.​postcodestring(Postal code (could be used instead of or in addition to zip). )
shipping_address.​statestring(State, if applicable (could be similar to province). )
statusstring(Status updates the current status of the order )required
curl -i -X PATCH \
  'https://developer-docs.quiqup.com/_mock/openapi/api/fulfilment/orders/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "billing_address": {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "coordinate": {
        "latitude": 0,
        "longitude": 0
      },
      "country": "string",
      "country_code": "string",
      "email": "string",
      "first_name": "string",
      "ksa_national_address": "string",
      "last_name": "string",
      "name": "string",
      "phone": "string",
      "postcode": "string",
      "state": "string"
    },
    "carrier": "string",
    "incoterm": "string",
    "origin_address": {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "coordinate": {
        "latitude": 0,
        "longitude": 0
      },
      "country": "string",
      "country_code": "string",
      "email": "string",
      "first_name": "string",
      "ksa_national_address": "string",
      "last_name": "string",
      "name": "string",
      "phone": "string",
      "postcode": "string",
      "state": "string"
    },
    "payment_amount": 0,
    "payment_mode": "pre_paid",
    "products": [
      {
        "country_of_origin": "string",
        "dimensions": {
          "height": 0,
          "length": 0,
          "unit": "string",
          "width": 0
        },
        "hs_code": "string",
        "quantity": 0,
        "selling_price": 0,
        "sku": "string",
        "weight": 0,
        "weight_unit": "string"
      }
    ],
    "service_kind": "partner_next_day",
    "shipping_address": {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "coordinate": {
        "latitude": 0,
        "longitude": 0
      },
      "country": "string",
      "country_code": "string",
      "email": "string",
      "first_name": "string",
      "ksa_national_address": "string",
      "last_name": "string",
      "name": "string",
      "phone": "string",
      "postcode": "string",
      "state": "string"
    },
    "status": "string"
  }'

Responses

Success response

Bodyapplication/json
billing_addressobject(types.CreateFulfilmentOrderAddressResponse)
carrierstring(Delivery carrier for the order )
created_atstring(date-time)(Timestamp when the order was created )
currencystring(3-letter ISO currency code (e.g., AED, SAR) )
delivery_optionsArray of strings(Special delivery requirements )

Possible values: leave_at_door, customer_identification_photo

Items Value"customer_identification_photo"
errorsArray of objects(Array of error messages if any issues occurred )
idstring(Unique identifier for the fulfilment order )
incotermstring(International commercial terms for the order )
initial_order_idstring(Reference to the original order ID for returns )
is_returnboolean(Indicates if this is a return order )
notesstring(Additional delivery instructions or comments )
origin_addressobject(types.CreateFulfilmentOrderAddressResponse)
parcelsArray of objects(List of parcels associated with the order )
partner_order_idstring(Your unique reference for the order )
payment_amountnumber(Total amount to be collected from the customer )
payment_modestring(types.PaymentMode)
Enum"pre_paid""paid_on_delivery"
picking_order_createdboolean(Indicates if a picking order has been created )
productsArray of objects(List of products included in the order )
service_kindstring(Type of delivery service requested )

Possible values: partner_next_day, partner_same_day, partner_4hr, partner_export, partner_store

shipping_addressobject(types.CreateFulfilmentOrderAddressResponse)
statusstring(OrderStatus represents the possible states of an order )
Enum"pending""ready_for_collection""picking_started""out_for_collection""out_for_return""at_depot""received_at_depot""in_transit""out_for_delivery""collection_failed"
status_reasonstring(Reason for the current status (e.g., why an order was cancelled) )
tracking_urlstring(URL for basic order tracking )
tracking_url_advancestring(URL for advanced order tracking with more details )
updated_atstring(date-time)(Timestamp when the order was last updated )
uuidstring(UUID of the fulfilment order )
Response
application/json
{ "billing_address": { "address1": "string", "address2": "string", "city": "string", "coordinate": {}, "country": "string", "country_code": "string", "created_at": "2019-08-24T14:15:22Z", "email": "string", "first_name": "string", "ksa_national_address": "string", "last_name": "string", "name": "string", "phone": "string", "postcode": "string", "state": "string", "updated_at": "2019-08-24T14:15:22Z" }, "carrier": "string", "created_at": "2019-08-24T14:15:22Z", "currency": "string", "delivery_options": [ "customer_identification_photo" ], "errors": [ {} ], "id": "string", "incoterm": "string", "initial_order_id": "string", "is_return": true, "notes": "string", "origin_address": { "address1": "string", "address2": "string", "city": "string", "coordinate": {}, "country": "string", "country_code": "string", "created_at": "2019-08-24T14:15:22Z", "email": "string", "first_name": "string", "ksa_national_address": "string", "last_name": "string", "name": "string", "phone": "string", "postcode": "string", "state": "string", "updated_at": "2019-08-24T14:15:22Z" }, "parcels": [ {} ], "partner_order_id": "string", "payment_amount": 0, "payment_mode": "pre_paid", "picking_order_created": true, "products": [ {} ], "service_kind": "string", "shipping_address": { "address1": "string", "address2": "string", "city": "string", "coordinate": {}, "country": "string", "country_code": "string", "created_at": "2019-08-24T14:15:22Z", "email": "string", "first_name": "string", "ksa_national_address": "string", "last_name": "string", "name": "string", "phone": "string", "postcode": "string", "state": "string", "updated_at": "2019-08-24T14:15:22Z" }, "status": "pending", "status_reason": "string", "tracking_url": "string", "tracking_url_advance": "string", "updated_at": "2019-08-24T14:15:22Z", "uuid": "string" }
Operations