# Delivery order

# API-3.3.3 Order estimation

POST /order/takeaway/estimates


API type	Request API
Usage	Before order creation, get the estimations of order amount and predicted time information.

Reminder：Zeek Platform adopts different pricing models in different regions. The delivery modes is recently applicable to Hong Kong region only. Please consult local Zeek team in advance.

# About delivery modes: Long distance, standard, short range

In food delivery, Zeek platform determines the delivery mode (Long distance / standard / short range) according to the delivery distance (The distance between restaurant and customer) and volume. Zeek platform dispatches order to particular partner according to the delivery mode determined.

Here is the mapping table between volume and partner position:

Volume	Eligible partner position	Stack order
Small parcel	All positions	Can stack order
Thermal bag	All positions	Only one order for walker, cannot stack order.
Thermal box	Motorbike and Van	Only one order for motorbike, cannot stack order.
More than 1 thermal box	Van only	Can stack order

Here are the delivery modes under certain delivery distance and volume conditions:

Distance / Volume	Small parcel	Thermal bag	Thermal box	More than 1 thermal box
Short	Short range	Short range	Standard	Long distance
Middle	Standard	Standard	Standard	Long distance
Long distance	Long distance	Long distance	Long distance	Long distance

In actual scenarios, Zeek Platform converts Order amount (which developer input) into Volume. Then the delivery mode will be deduced according to the mapping table above. Here is an example, showing the conversion between order amount and volume in Zeek Platform.

Order amount lower limit (inclusive)	Order amount upper limit (exclusive)	Corresponding volume
0	200	Small parcel
200	500	Thermal bag
500	1000	Thermal box
1000	Unlimited	More than 1 thermal box

# Usage

When customer places order in mobile App, the delivery fee can be calculated from this API result. Here are 2 scenarios:

Scenario 1 - Before customer chooses menu item

When customer opens the App, the App retrieves customer location.
After customer location is retrieved, request this API. Please input customer location (recipient.location) only. The API will return a conversion table. The table contains one to multiple quotations (quotations).
Developer stores the conversion table data in the App.
In each quotation, it contains the corresponding order amount range (min_product_total_price, max_product_total_price) of a particular delivery mode (mode) in Zeek Platform.
Customer adds menu items at the ordering interface. Order amount changes when the number of menu item changes.
Each time when the order amount changes, Client system finds the corresponding delivery mode from the conversion table, according to the order amount.
After delivery mode is found, Client system calculates the delivery fee by its own system logics. Then it displays the fee to user.

Scenario 2 - Before checkout

The menu item and order amount is confirmed.
Client system calls this API again. It inputs customer location and order amount (total_price) this time. The API will return ONE quotation only.
By means of client's system logics, it calculates the delivery fee frm the delivery mode. Then it displays the fee to user.

# Request

Name	Type	Mandatory	Default	Description	Remarks
client_merchant_id	string	Y	-	Store ID in client system
schedule_type	int	N	`0`	Is it a scheduled order?	- `0` : Not scheduled - `2` : Scheduled by delivery time. The time should be after 30min from current time and within 7 days.
schedule_time	string	N*	-	Scheduled time	- It is mandatory when `schedule_type` is not equal to `0`. - `schedule_type` = 2 : Please input the scheduled delivery time. System will publish the order by its own calculation. The meal will be delivered to user on the scheduled time. - Example: `2018-07-24 18:54:07`
recipient.address	string（255）	N *	-	User address	- Same as `user_address` - Please refer to How to pass user address and location
recipient.location	string	Y *	-	User location coordinates	- Same as `user_location` - Please refer to How to pass user address and location
product.total_price	float	N	-	Order total amount	- Unit : dollar - Please input the order amount of products, excluding discount, tax and delivery fee. - Please refer to the API description above.

Example：

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "client_merchant_id": "STORE-123",
        "schedule_type": 1,
        "schedule_time": "2020-02-24 18:54:00",
        "recipient":{
            "location": "22.3902837102,114.0042115195",
        },
        "product": {
            "total_price": 13300
        }
    }
}

# Response

Name	Type	Description	Remarks
quotations	array	Quotations	Please refer to the API description above.
quotations[].quotation_id	string	Quotation ID	The unique ID to identify this quotation.
quotations[].mode	string	Delivery mode	- Return one of the 3 labels: `STANDARD`, `LONG_DISTANCE`, `SHORT_RANGE` - Delivery mode relates to merchant configuration. Please consult Zeek team which delivery modes are supported in your city.
quotations[].min_product_total_price	float	Minimum order amount	- It is inclusive in order amount range. - Unit : dollar
quotations[].max_product_total_price	float / null	Maximum order amount	- It is exclusive in order amount range. - It returns `null` when the value is infinity. - Unit : dollar
quotations[].delivery_fee	float / null	Delivery fee	NOTE: The delivery fee function is NOT released yet. Therefore, it will return `null` instead.
quotations[].predicted_quote_time	int	Predicted quote time	- Please refer to Quote time - Unit : minute
quotations[].predicted_quote_time_range	string	Predicted quote time range	- Example: `"30-40"`
quotations[].direct_distance	int	Direct distance from merchant to customer	- Unit : meter
quotations[].travel_distance	int	Travel distance from merchant to customer	- Unit : meter

例子 Example:

{
    "error": 0,
    "data": {
        "quotations" : [
            {
                "quotation_id": "q-fd-1-1583313293",
                "mode" : "SHORT_RANGE",
                "min_product_total_price": 0,
                "max_product_total_price": 200,
                "delivery_fee": 10.5,
                "predicted_quote_time": 30,
                "predicted_quote_time_range": "30-55",
                "direct_distance": 500,
                "travel_distance": 650
            },
            {
                "quotation_id": "q-fd-1-1583313293",
                "mode" : "STANDARD",
                "min_product_total_price": 200,
                "max_product_total_price": 750,
                "delivery_fee": 10.5,
                "predicted_quote_time": 30,
                "predicted_quote_time_range": "30-55",
                "direct_distance": 500,
                "travel_distance": 650
            },
            {
                "quotation_id": "q-fd-1-1583313293",
                "mode" : "LONG_DISTANCE",
                "min_product_total_price": 750,
                "max_product_total_price": null,
                "delivery_fee": 10.5,
                "predicted_quote_time": 30,
                "predicted_quote_time_range": "30-55",
                "direct_distance": 500,
                "travel_distance": 650
            }
        ]   
    }
}

# API-3.3.1 Create order

POST /order/takeaway/create


API type	Request API
Usage	Create delivery order. Order creation is allowed when user locates inside delivery area only.

# Request

Name	Type	Mandatory	Default	Description	Remarks
client_merchant_id	string	Y	-	Store ID in client system	- Ref to FAQ - What is client merchant id? Do I need to send store address when create order?
client_order_id	string(128)	Y	-	Order ID in client system	- This is the order ID generated in client system. - The following rule applies: 1. When `merchant_order_id` is empty or not passed to Zeek platform, `client_order_id` must be numerical string. Zeek platform will use the last 4 digit of the `client_order_id` as the pickup code. 2. When `merchant_order_id` contains the 4 digits, `client_order_id` can be in non-numerical format.
merchant_order_id	string(64)	N	-	Pickup code / Order ID in third party merchant's system	- Notice: It must be a 4 digit number. - Most of the time, it is used as pickup code. This code is displayed in Zeek partner App. When partner arrives the store, store manager should verify the partner by this code. - When `merchant_order_id` is empty, the last 4 digits of `client_order_id` will be extracted and applied to pickup code. Btw, we strongly recommend developer to input `merchant_order_id`. Another usage is: When the merchant (ie. restaurant) has the order ID other than the `client_order_id`, please input here. - Ref to FAQ - What is pickup code
order_time	int	Y	-	Order creation time in client system	Timestamp in second
delivery_type	string	N	`"ZEEK_DELIVERY"`	Delivery or pickup mode	- `"ZEEK_DELIVERY"`：Delivered by Zeek - `"SELF_PICKUP"`: Pickup by customer
is_appoint	int	N	`0`	Is it a scheduled order?	- `0` : Not scheduled - `2` : Scheduled by delivery time. The time should be after 30min from current time and within 7 days.
appoint_time	string	N*	-	Scheduled time	- It is mandatory when `is_appoint` is not equal to `0`. - `is_appoint` = 2 : Please input the scheduled delivery time. System will publish the order by its own calculation. The meal will be delivered to user on the scheduled time. - Example: `2018-07-24 18:54:07`
remark	string(1024)	N	`""`	Delivery order remarks	- Special instruction to partner. For example: "Please dial the customer when arrive reception" - Display in Zeek Partner App.
merchant_remark	string(1024)	N	`""`	Merchant remarks	- Instruction for merchant internal use. - It is not displayed in Zeek Partner App.
cod_type	int	N	`0`	Payment type	`0` : Not defined. Partner collects the fee according to instructions on receipt. `1` : Cash on delivery. Partner pays to merchant when he picks up at restaurant. Then he collects amount from customer when delivers. `2` : Customer pays online already (eg. by credit card). Partner doesn't need to collect fee. `3` : Customer does not pay when places order. Partner will collect the amount via credit card imprinting upon delivery. Please check with Zeek team if it is applicable.
receive	obj	Y	-	Receiver info	Please refer to `receiver` data format
order_detail	obj	Y	-	Order details	Please refer to `order_detail` data format

receive data format

Name	Type	Mandatory	Default	Description	Remarks
user_name	string（64）	Y	-	User name
user_phone	string（32）	Y	-	User phone number	Not include country code, example: `"91234567"`
user_phone_country_code	string（5)	N	See remarks	User phone country code	- For example: `"852"` - Default country code value is assigned according to the `region` value in "Global parameters". For instance, if `region` is `"SG"`, then default country code will be `"65"`.
user_address_id	string	N *	`""`	User address ID	- When use, please input the address ID provided by Zeek. For example, `"SF2.5972"`. - Please refer to How to pass user address and location
user_address	string（255）	Y	-	User address	Please refer to How to pass user address and location
user_location	string	Y *	`""`	User location coordinates	Please refer to How to pass user address and location

order_detail data format

Name	Type	Mandatory	Default	Description	Remarks
total_price	int	Y	-	Order total price	- Unit: cents (1 dollar = 100 cents) - Please input the order amount of products, excluding discount, tax and delivery fee.

Example：

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "client_merchant_id": "STORE-123",
        "client_order_id": "201806121528793155",
        "merchant_order_id": "1234",
        "is_appoint": 2,
        "appoint_time": "2018-07-24 18:54:07",
        "order_time": 1528793155,
        "remark": "Please dial the customer when arrive reception",
        "merchant_remark": "",
        "cod_type": 2,
        "receive":{
            "user_name":"Guiying Yao",
            "user_phone":"63632752",
            "user_phone_country_code": "65",
            "user_location": "22.3902837102,114.0042115195",
            "user_address":"#12-456, Woodlands, Singapore, 730779"
        },
        "order_detail":{
            "total_price": 200
        }
    }
}

# Response

Name	Type	Description	Remarks
order_id	string	Order ID in Zeek Platform
client_order_id	string	Order ID in client system
order_url	string	Order URL	- In specific integration, client can generate QR code by this url. - The QR code is used for order bidding by partners.
direct_distance	int	Direct distance from merchant to customer	- Unit : meter
travel_distance	int	Travel distance from merchant to customer	- Unit : meter
predicted_accept_time	int	Predicted accept time	- Unit : minute
predicted_accept_time_range	string	Predicted accept time range	- Example：`"30-40"`
predicted_showup_time	int	Predicted showup time	- Unit : minute
predicted_showup_time_range	string	Predicted showup time range	- Example：`"30-40"`
predicted_delivery_time	int	Predicted delivery time	- Unit : minute
predicted_delivery_time_range	string	Predicted delivery time range	- Example：`"30-40"`

Example:

{
    "error": 0,
    "data": {
        "order_id": "FD20180615080181522",
        "client_order_id": "15104092022333",
        "order_url":"https://ap1-track.zeek.one/FD20180615080181522",
        "direct_distance": 500,
        "travel_distance": 650,
        "predicted_accept_time": 5,
        "predicted_accept_time_range": "5-10",
        "predicted_showup_time": 20,
        "predicted_showup_time_range": "20-30",
        "predicted_delivery_time": 40,
        "predicted_delivery_time_range": "40-60"
    }
}

# API-3.3.2 Cancel order

POST /order/takeaway/cancel


API type	Request API
Usage	- Cancel delivery order - Developer can cancel order before the order is completed. - Different order status will be given if you cancel order before or after partner arrived store. Please refer to Order status code

# Request

Name	Type	Mandatory	Default	Description	Remarks
order_id	string（128）	Y	-	Order ID in Zeek platform
client_merchant_id	string	Y	-	Store ID in client system
cancel_reason	string（255）	N	`""`	Cancel reason
user_code	string（4）	N	`"0000"`	Staff number	4 digits format, example: `"1234"`

Example：

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "order_id": "FD20180615080181522",
        "client_merchant_id": "STORE-123",
        "cancel_reason": "Requested by customer",
        "user_code": "1223"
    }
}

# Response

Name	Type	Description	Remarks
order_id	string	Order ID in Zeek Platform
client_order_id	string	Order ID in client system

Example:

{
    "error": 0,
    "data": {
        "order_id": "FD20180615080181522",
        "client_order_id": "14570817752333"
    }
}

# API-3.4.1 Get order details

POST /order/takeaway/info


API type	Request API
Usage	Get delivery order details

# Request

Name	Type	Mandatory	Default	Description	Remarks
order_id	string（128）	Y	-	Order ID in Zeek platform
client_merchant_id	string	Y	-	Store ID in client system

Example：

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "order_id": "FD20180615080181522",
        "client_merchant_id": "STORE-123"
    }
}

# Response

Name	Type	Description	Remarks
order_id	string	Order ID in Zeek Platform
client_order_id	string	Order ID in client system
order_url	string	Order URL	- In specific integration, client can generate QR code by this url. - The QR code is used for order bidding by partners.
delivery_type	string	Delivery or pickup mode
brand_id	int	Brand ID
brand_key	string	Brand Key
merchant_location	string	Merchant location
user_location	string	User location
direct_distance	int	Direct distance from merchant to customer	- Unit : meter
travel_distance	int	Travel distance from merchant to customer	- Unit : meter
addtime	int	Order creation time	Timestamp in second
appointment_time	int	Scheduled time	Timestamp in second
name	string	Order name
remark_text	string	Remarks
merchant_remark	string	erchant remarks
partner_name	string	Partner name
partner_phone	string	Partner phone number
partner_carno	string	Partner vehicle number
order_status	int	Order status
cancel_user	string	Staff number who cancel order
cancel_type	string	Cancel order type
cancel_reason	string	Cancel order reason
actual_done_time	int	Order complete time	Timestamp in second
lastmodify	int	Lastmodify time	Timestamp in second

Example:

{
    "error": 0,
    "data": {
        "order_id": "FD2019010484047222",
        "client_order_id": "201901041133245454",
        "order_url":"https://ap1-track.zeek.one/FD2019010484047222",
        "delivery_type": "ZEEK_DELIVERY",
        "brand_id": 22,
        "brand_key": "abc-brand",
        "merchant_location": "22.3902837102,114.0042115195",
        "user_location": "22.3902837102,114.0042115195",
        "direct_distance": 500,
        "travel_distance": 650,
        "addtime": 1510733606,
        "appointment_time": 1510733606,
        "name": "ABC restaurant delivery",
        "remark_text": "Please dial the customer when arrive reception",
        "merchant_remark": "",
        "partner_name": "Zhihao Shi",
        "partner_phone": "62988967",
        "partner_carno": "AB1234",
        "order_status": 9025,
        "cancel_user": "Peter Cheung",
        "cancel_type": "Other",
        "cancel_reason": "Requested by customer",
        "actual_done_time": 1510733606,
        "lastmodify": 1510733606
    }
}

# API-3.4.4 Get order details by user phone number

POST /order/takeaway/info_by_phone


API type	Request API
Usage	Get delivery order details by user phone number

# Request

Name	Type	Mandatory	Default	Description	Remarks
user_phone	string（32）	Y	-	User phone number
user_phone_country_code	string（5)	N	See remarks	User phone country code	- For example: `"852"` - Default country code value is assigned according to the `region` value in "Global parameters". - For instance, if `region` is `"SG"`, then default country code will be `"65"`.

Example:

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "user_phone_country_code": "852",
        "user_phone": "12345678"
    }
}

# Response

Name	Type	Description	Remarks
order_id	string	Order ID in Zeek Platform
client_order_id	string	Order ID in client system
order_url	string	Order URL	- In specific integration, client can generate QR code by this url. - The QR code is used for order bidding by partners.
delivery_type	string	Delivery or pickup mode
brand_id	int	Brand ID
brand_key	string	Brand Key
merchant_location	string	Merchant location
user_location	string	User location
direct_distance	int	Direct distance from merchant to customer	- Unit : meter
travel_distance	int	Travel distance from merchant to customer	- Unit : meter
addtime	int	Order creation time	Timestamp in second
appointment_time	int	Scheduled time	Timestamp in second
name	string	Order name
remark_text	string	Remarks
merchant_remark	string	erchant remarks
partner_name	string	Partner name
partner_phone	string	Partner phone number
partner_carno	string	Partner vehicle number
order_status	int	Order status
cancel_user	string	Staff number who cancel order
cancel_type	string	Cancel order type
cancel_reason	string	Cancel order reason
actual_done_time	int	Order complete time	Timestamp in second
lastmodify	int	Lastmodify time	Timestamp in second

Example:

{
    "error": 0,
    "data": {
        "order_id": "FD2019010484047222",
        "client_order_id": "201901041133245454",
        "order_url":"https://ap1-track.zeek.one/FD2019010484047222",
        "delivery_type": "ZEEK_DELIVERY",
        "brand_id": 22,
        "brand_key": "abc-brand",
        "merchant_location": "22.3902837102,114.0042115195",
        "user_location": "22.3902837102,114.0042115195",
        "direct_distance": 500,
        "travel_distance": 650,
        "addtime": 1510733606,
        "appointment_time": 1510733606,
        "name": "ABC restaurant delivery",
        "remark_text": "Please dial the customer when arrive reception",
        "merchant_remark": "",
        "partner_name": "Zhihao Shi",
        "partner_phone": "62988967",
        "partner_carno": "AB1234",
        "order_status": 9025,
        "cancel_user": "Peter Cheung",
        "cancel_type": "Other",
        "cancel_reason": "Requested by customer",
        "actual_done_time": 1510733606,
        "lastmodify": 1510733606
    }
}

# API-3.9.1 Order status update callback

POST The endpoint is provided by developer


API type	Callback API
Usage	When delivery order status updates, Zeek platform will send latest status code to the callback API.

# Request failure handling

When Zeek platform cannot receive a successful response from callback API, it will be regarded as failure. Then the platform will retry. The retry frequency is 15/15/30/180/1800/1800/1800/1800/3600 in seconds.

# API Authentication

Zeek platform will pass signature to developer's callback API. The signature is generated according to Authentication. Therefore, please verify the signature by the same way.

# Request

Name	Type	Description	Remarks
order_id	string（128）	Order ID in Zeek platform
client_order_id	string	Order ID in client system
timestamp	int	Actual timestamp when the status is triggered
order_status	int	Order status	Please refer to Order status code
status_desc	string	Order status description
partner.partner_name	string	Partner name
partner.partner_phone	string	Partner phone number
partner.partner_location	string	Partner location coordinates
cancel.cancel_reason	string	Cancel order reason	If the order is cancelled by KS platform, `cancel_reason` will be `"CANCELLED_BY_PLATFORM"`
predicted_accept_time	int	Predicted accept time	- Unit：minute - If partner have accepted order, Zeek Platform will send `null`.
predicted_accept_time_range	string	Predicted accept time range	- Example：`"30-40"` - If partner have accepted order, Zeek Platform will send `null`.
predicted_showup_time	int	Predicted showup time	- Unit：minute - If partner have arrived store, Zeek Platform will send `null`.
predicted_showup_time_range	string	Predicted showup time range	- Example：`"30-40"` - If partner have arrived store,Zeek Platform will send `null`.
predicted_delivery_time	int	Predicted delivery time	- Unit：minute - If the order is delivered, Zeek Platform will send `null`.
predicted_delivery_time_range	string	Predicted delivery time range	- Example：`"30-40"` - If the order is delivered, Zeek Platform will send `null`.

Example:

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "order_id": "FD20180615080181522",
        "client_order_id": "201808076580818698",
        "timestamp": 1533609085,
        "order_status": 9015,
        "status_desc": "Delivery in progress",
        "partner": {
            "partner_name": "Zhihao Shi",
            "partner_phone": "62988967",
            "partner_location": "22.3902837102,114.0042115195",
        },
        "cancel": {
            "cancel_reason" : "Requested by customer"
        },
        "predicted_accept_time": 5,
        "predicted_accept_time_range": "5-10",
        "predicted_showup_time": 10,
        "predicted_showup_time_range": "10-20",
        "predicted_delivery_time": 30,
        "predicted_delivery_time_range": "30-50",
    }
}

# Response

Please return the API response in callback API, according to the format below.

Name	Type	Description	Remarks
error	int	Error code	Return `0` when API request is successful.
err_msg	string	Error message

{
    "error": 0,
    "err_msg": "",
}

# API-3.5.1 Partner location

POST /tasker/takeaway/position_latest


API type	Request API
Usage	Get the current partner location of a delivery order

# Request

Name	Type	Mandatory	Default	Description	Remarks
order_id	string（128）	Y	-	Order ID in Zeek platform
client_merchant_id	string	Y	-	Store ID in client system

例子 Example：

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "order_id": "FD20180615080181522",
        "client_merchant_id": "STORE-123"
    }
}

# Response

Name	Type	Description	Remarks
order_id	string	Order ID in Zeek Platform
client_order_id	string	Order ID in client system
partner_name	string	Partner name
partner_location	string	Partner location
upload_time	int	Lastmodify time	Timestamp in second
predicted_delivery_time	int	Predicted delivery time	- Unit : Minute - It returns `-1` after the order is completed.
predicted_delivery_time_range	string	Predicted delivery time range	- Example: `"30-40"`

Example:

{
   "error": 0,
    "data": {
        "order_id": "FD20180615080181522",
        "client_order_id": "14570817752333",
        "partner_name": "Zhihao Shi",
        "partner_location": "22.3902837102,114.0042115195",
        "upload_time":1510733606,
        "predicted_delivery_time": 30,
        "predicted_delivery_time_range": "30-60"
    }
}

# API-3.5.2 Partner location path

POST /tasker/takeaway/position_track


API type	Request API
Usage	Get the location path of a delivery order's partner

# Request

Name	Type	Mandatory	Default	Description	Remarks
order_id	string（128）	Y	-	Order ID in Zeek platform
client_merchant_id	string	Y	-	Store ID in client system
page	int	Y	-	Page number
pagesize	int	N	20	Page size	Maximum: 500

Example：

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "order_id": "FD20180615080181522",
        "client_merchant_id": "STORE-123",
        "page": 1,
        "pagesize": 30
    }
}

# Response

Name	Type	Description	Remarks
data	array	Partner location (multiple)
data[].partner_location	string	Partner location
data[].upload_time	int	Lastmodify time	Timestamp in second

{
    "error": 0,
    "data": [
        {
            "partner_location": "22.3902837102,114.0042115195",
            "upload_time": 1510409202
        },
        {
            "partner_location": "22.3902837102,114.0042115195",
            "upload_time": 1510409202
        }
    ],
    "pageinfo": {
        "total": 3,
        "pagecount": 2,
        "pagesize": 2,
        "curpage": 1
    }
}

← Merchant management Time prediction →