# 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
}
}