Zeek Technology

# 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: Short range, standard, long distance, city wide

In food delivery, Zeek platform determines the delivery mode (Short range / standard / long distance / city wide) 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 distance Short range Short range Standard Long distance
Middle distance Standard Standard Standard Long distance
Long distance Long distance Long distance Long distance Long distance
City wide distance City wide City wide City wide City wide

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 whenschedule_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 asuser_address
- Please refer to How to pass user address and location
recipient.location string Y * - User location coordinates - Same asuser_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.
- Please note: total_price will considered as NOT passed, if total_price=0 is passed.

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 these labels:
SHORT_RANGE (Short range)
STANDARD (Standard)
LONG_DISTANCE (Long distance)
CITY_WIDE (City wide)

- 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 It gives a delivery fee reference to merchant only. The actual delivery fee billing is subject to the commercial agreement between Zeek and Merchant.
quotations[].predicted_quote_time int Predicted quote time - Please refer toQuote 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 toFAQ - 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 whenis_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 toreceiver data format
order_detail obj Y - Order details Please refer toorder_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 toHow to pass user address and location
user_location string Y * "" User location coordinates Please refer toHow 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"
requested_pickup_time int Requested pickup time Timestamp in second
requested_delivery_time int Requested delivery time Timestamp in second

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",
        "requested_pickup_time": 1655189860,
        "requested_delivery_time": 1655189860
    }
}

# 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_code string Order cancel code RefOrder cancel code
cancel_user string Staff number who cancel order
cancel_type string Cancel order type
cancel_reason string Cancel order reason
cancel_time string Order cancel time Timestamp in second
actual_done_time int Order complete time Timestamp in second
requested_pickup_time int Requested pickup time Timestamp in second
requested_delivery_time int Requested delivery 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_code": "7002",
        "cancel_user": "Peter Cheung",
        "cancel_type": "Other",
        "cancel_reason": "Requested by customer",
        "cancel_time":"1510733606",
        "actual_done_time": 1510733606,
        "requested_pickup_time": 1655189860,
        "requested_delivery_time": 1655189860,        
        "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_code string Order cancel code RefOrder cancel code
cancel_user string Staff number who cancel order
cancel_type string Cancel order type
cancel_reason string Cancel order reason
cancel_time int Order cancel time Timestamp in second
actual_done_time int Order complete time Timestamp in second
requested_pickup_time int Requested pickup time Timestamp in second
requested_delivery_time int Requested delivery 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_code": "7002",
        "cancel_user": "Peter Cheung",
        "cancel_type": "Other",
        "cancel_reason": "Requested by customer",
        "cancel_time": 1510733606,
        "actual_done_time": 1510733606,
        "requested_pickup_time": 1655189860,
        "requested_delivery_time": 1655189860,
        "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 toOrder 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
cancel.code string Order cancel code RefOrder cancel code
cancel.cancel_user string The user who cancelled the order
cancel.time string Cancellation time
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",
            "code": "7002",
            "cancel_user": "0000",
            "cancel_time": "1625572417"
        },
        "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 Return0 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
    }
}

← Time prediction →