Orders

/Orders

Orders

Create, release, read, cancel and label last-mile orders.

Operations

Create an order

Request

Creating orders

Eight things govern order creation with the ecommerce order API.

Order states
Order kinds
Payment on delivery or pre-paid
Partner Order ID
Billing Identifiers
Items
AWB Documents (Labels)
Marking an order as ready for collection

When you create a new single order, this order will be created in a pending state and will only be visible on your Quiqdash, but it is not visible for our dispatching system.

1. Order states

Every state, what it means and the webhook event it fires are listed once, in Order lifecycle. That page is the one to code against.

2. Order Kinds (Service Type):

Through this API we offer various services, depending on what service you select, different service levels apply. The current available service kinds are:

Order Kind Value	Service Description
`partner_same_day`	If orders are marked as `ready_for_collection` before the agreed cut-off time, the order will be collected and delivered on the same-day.
`partner_next_day`	Orders that are marked as `ready_for_collection` will be delivered the next day.
`partner_4hr`	Orders marked `ready_for_collection` between 08:00 and the account's 4-hour cut-off, 18:00 unless agreed otherwise, are delivered within 4 hours. Orders marked ready after the cut-off are delivered by 12:00 the next day, and orders marked ready before 08:00 by 12:00 the same day. UAE time.
`partner_return`	Use this order kind to create return orders for customers to return. Important to consider that the pickup location here is the customer's address and the dropoff location should be the location where order is returned to.
`partner_store`	Accepted on create and resolves to the same-day service class. The response echoes it as `service_kind` while `kind` reads `partner_same_day`.
`partner_export`	International shipping to GCC destinations. Also applied automatically when the destination country differs from the pickup country. Checked when the order is made ready for collection, see Export orders.

3. Payment on delivery or pre-paid

There are two fields that pertain to payment on delivery, payment_mode and payment_amount.

The payment_mode can either be:

pre_paid - This means the customer has already paid you and no money needs to be collected during the delivery
paid_on_delivery - This means the customer has not yet paid for the order and will be collecting this by card or by cash during the delivery.

As for the payment_amount this is dependent on what payment_mode is set.

If the payment mode is prepaid, then omit payment_amount, or send 0.
In case where the payment_mode = paid_on_delivery, then the payment_amount needs to be greater than 1.

The currency is defaulted to the country's currency, in the case of the UAE this is Dirham AED, ISO: AED 784.

4. Partner Order ID

This field you can use for your own internal order reference. This will also be used for invoicing purposes and allows for easy reconciliation of invoices and COD payments. This field does not enforce uniqueness. Send a unique value yourself.

5. Billing Identifiers

Billing Identifiers allow you to create orders in other accounts. This can be useful for integrations that will be used by several businesses.

A billing identifier needs to be configured by Quiqup and approved by the business. A value that is not configured for your account is accepted and ignored: the order is created, the value is echoed back, and the order belongs to you. See billing_identifier.

A billing Identifier is set by passing the below in the root of the order payload:

"billing_identifier": "Retailer123",

Example:

The integrated account integration@example.com uses API keys to connect to Quiqup's system and create orders.
While creating orders it passes the billing identifier Retailer123.
The order is then owned by retailer@example.com but the order is authored by integration@example.com Making the order visible on both their Quiqdash.

6. Items

Items should be regarded as parcel. Each item represents one parcel. So thus if an order consists of only one parcel there is only one item in the order. If the order consists of two parcels, send two entries in items, and two labels are generated.

The item object has a few important fields that you need to be aware of:

First being the name, you can put your parcel reference code or order ID in here. Alternatively you can name this: Parcel #1, and Parcel 1 of 2 if there are multiple parcels as part of this order.
Quantity should always be set to 1.
parcel_barcode. Leave it empty and Quiqup generates the barcode and prints the label. A non-empty value tells Quiqup you are printing your own label.

7. AWB Documents (Labels)

Ecommerce orders require labels to maintain and provide an accurate chain of custody for your records and ours. This is what allows us to keep a clean order history and track the parcels throughout its life cycle.

As an order can have multiple items, an order can also have multiple labels. Each item requires a label with a unique parcel-barcode so each individual parcel can be tracked. For more information on how to download our labels see the Download the AWB Document operation.

8. Marking an order as `ready_for_collection`

Mark the order ready for collection once it is picked and packed. The label can be downloaded before or after that call. Orders that remain pending are ignored by Quiqup. For full details please see the Mark Ready for Collection operation

Security

bearerToken or oauthToken

Content-Typestringrequired

Bodyapplication/jsonrequired

kindstring

The service. Defaults to partner_same_day when omitted. Fixed at creation: it cannot be changed afterwards.

notesstring

payment_amountnumber

Omit or send 0 when pre_paid. Above 1 when paid_on_delivery. Decimals are accepted.

payment_modestring

Defaults to pre_paid when omitted, with payment_amount 0.0. cash_on_delivery and card_on_delivery are retired as a matter of policy but are still accepted by the API; do not build against them.

Enum:"pre_paid""paid_on_delivery"

billing_identifierstring

A billing account, not a pickup location. Omit it unless Quiqup set one up for you. A value that is not linked to your account is accepted and echoed back, and the order is created in your own account, so a typo is never reported. Check brand_name on the response.

scheduled_forany

metadataany

uuidstring, (uuid)

Your idempotency key. Generate one per order and resend the same value on a retry. A repeat from the same account returns the original order with HTTP 200 and creates nothing. A malformed value, or one another account already used, is rejected with 422.

partner_order_idstring

required_documentsArray of any

Only the empty array is accepted today. Any entry, a string or an object, is rejected with [required_documents][0][order] is invalid. Send [], or leave the field out.

originobjectrequired

destinationobjectrequired

itemsArray of objects, non-emptyrequired

The parcels. One entry per physical box, bag or stash box. A label is generated per item, so each box can be tracked separately. The goods inside go in products, not here.

productsArray of objects

The goods being shipped. Optional for UAE orders, where it mainly gives support visibility of what is in the box. Required for export orders: hs_code, country_of_origin, weight and selling_price are what clear customs.

Products are not parcels. See items for the physical boxes. A label is generated per item, never per product.

disallowed_payment_typesArray of strings

Suppress a collection method on a paid_on_delivery order, for example ["cash"] to force card.

ready_for_collectionboolean

Set true to release the order without the separate call. Applied asynchronously: the create response still reports state: pending, and the order moves to ready_for_collection a moment later. Do not read the release back off the create response.

curl -i -X POST \
  https://api.staging.quiqup.com/orders \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "partner_same_day",
    "payment_mode": "pre_paid",
    "partner_order_id": "PARTNER-ORDER-ID",
    "origin": {
      "contact_name": "Warehouse contact",
      "contact_phone": "+971500000000",
      "address": {
        "address1": "Example Warehouse, Street 1",
        "address2": "Al Quoz Industrial Area 4",
        "country": "UAE",
        "town": "Dubai"
      }
    },
    "destination": {
      "contact_name": "Customer name",
      "contact_phone": "+971599999999",
      "contact_email": "customer@example.com",
      "notes": "",
      "address": {
        "address1": "1st Road",
        "address2": "104G",
        "country": "UAE",
        "town": "Dubai"
      }
    },
    "products": [
      {
        "sku": "SKU-RUN-001",
        "quantity": 1,
        "description": "Running shoe red",
        "barcode": "1234654-kt",
        "selling_price": 58.3,
        "hs_code": "64041100",
        "country_of_origin": "CN",
        "weight": 0.8,
        "height": 12,
        "width": 20,
        "length": 30
      }
    ],
    "items": [
      {
        "name": "Parcel 1",
        "quantity": 1,
        "parcel_barcode": ""
      }
    ]
  }'

Responses

An order with this uuid already exists for your account. That order is returned unchanged, in the same shape as the 201 response, and nothing was created.

Response

No content

Callbacks

Order state change

post

Orders

Create an order

Request

Creating orders

1. Order states

2. Order Kinds (Service Type):

3. Payment on delivery or pre-paid

4. Partner Order ID

5. Billing Identifiers

Example:

6. Items

7. AWB Documents (Labels)

8. Marking an order as `ready_for_collection`

Headers

Responses

Callbacks

Was this helpful?

Orders

Create an order

Request

Creating orders

1. Order states

2. Order Kinds (Service Type):

3. Payment on delivery or pre-paid

4. Partner Order ID

5. Billing Identifiers

Example:

6. Items

7. AWB Documents (Labels)

8. Marking an order as ready_for_collection

Headers

Responses

Callbacks

Was this helpful?

8. Marking an order as `ready_for_collection`