post

/orders

Creating orders

There are a few things to consider when creating orders with the ecommerce order API.

  1. Order status
  2. Order kinds
  3. Payment on delivery or pre-paid
  4. Partner Order ID
  5. Billing Identifiers
  6. Items
  7. AWB Documents (Labels)
  8. Marking an order as ready for collection

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

1. Order states:

Order State Description
pending The order has been created in a draft state and has not been yet confirmed by the client that it can be collected, Quiqup will ignore this order until it is submitted
ready_for_collection Order created and is known in Quiqup’s system and will be added to the next collection run
collected Quiqup has collected the order from the pickup location and the order is on the way to our depot
received_at_depot The order has been received at the depot
out_for_delivery The order is out for delivery
delivery_complete Order has successfully been delivered, this is an end of life cycle state.
delivery_failed The delivery of the order has failed. This has several reasons. See table below.
return_to_origin The order will be returned to the retailer
returned_to_origin The order has been returned to the retailer, this is an end of life cycle state.
cancelled The delivery of the order has been cancelled
on_hold The delivery of the order has been put on hold
at_depot The order is at the depot and awaiting to be scheduled with customer or will be delivered during the next delivery day
scheduled The order has been scheduled for delivery with the customer in the future

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 deliverd on the same-day.
Partner_next_day Orders that are marked as ready_for_collection will be delivered the next day.
Partner_4hr Orders mark as ready_for_collection between 8am and 6pm will be collected and delivered within 4hrs, orders that are marked as ready_for_collection after 6p, will receive a 4hr deliver at 12pm the next day.
Partner_return Use this order kind to create return orders for customers to return. Important to consider that the pickup location here should pickup location of the customer and the dropoff location should be the location where order is returned to.
Partner_store Use this for store deliveries to allow your customer to collect from store.

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:

  1. prepaid - This means the customer has already paid you and no money needs to be collected during the delivery
  2. 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.

  1. If the payment mode is prepaid, then the payment amount needs to be 0 or *NULL*.
  2. In case where the payment_mode = paid_on_delivery, then the payment_amount needs to be greater then 1.

The currency is defaulted to the countries 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 interal order reference. This will also be used for invoicing purposes and allows for easy reconcilation of invoices and COD payments. This field does not enforce uniqueness, however this is certainly recommended.

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 business.

A billing identifier needs to be configured by Quiqup and approved by the business.

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

"billing_identifier": "Retailer123",

Example:

  1. The integrated account integration@quiqup.com uses API keys to connect to Quiqup’s system and create orders.
  2. While creating orders it passes the billing identifier Retailer123.
  3. The order is then owned by retailer@123.com but the order is authored by test@quiqup.com Making the order visible on both their Quiqup Portals.

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 there are two parcels as part of the order.

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

  1. First being the name, you can put your parcel refernce code or order ID in here. Alternative you can name this: Parcel #1, and Parcel 1 of 2 if there are multiple parcels as part of this order.
  2. Quantify should always be set to 1.
  3. Then last but not least parcel_barcode, if you leave this empty, we will generate this and use it to generate a label with. However you do provide a parcel_barcode we assume that you have your own label that you will use.

7. AWB Documents (Labels)

Ecommerce order require labels to maintain and provide an accurate chain of custody for you records and ours. This is what allows us to keep a clean order history and track the parcels throughout it’s 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: More about this see Download the AWB Document.

8. Marking an order as ready_for_collection

Once the order has been picked, packed and labelled you can mark the order as ready for collection. Orders that remain in a pending will be ignored by Quiqup. For full details please see Mark Ready for Collection

Authorization

oauth2 - clientCredentials

Request Parameters

2 Headers

Request Body

1 Example
Schema
object
kind
string
notes
string
payment_amount
integer
payment_mode
string
disallowed_payment_types
array[string]
billing_identifier
string
scheduled_for
null
metadata
null
partner_order_id
string
required_documents
array[string]
origin
object
destination
object
items
array[object]

Responses

1 Example
Schema
object
order
object

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
oauth_access_token