# Order management

# PA-API-3.1 Create order

POST /order/create

API type Request API
Usage - Create delivery order

# Request

Name Type Mandatory Default Description Remarks
merchant_id string Y - Merchant ID in Zeek Platform
client object Y - Client info
client.order_id string Y - Client order ID The order ID in Client system
client.shipment_code string N '' Client shippment code The shipping code in Client system
product_code string Y - Product code - Support "DASH2HR", "DASH4HR" or "MPOINTS".
- Please consult Zeek team about the supported values.
preferences array N [] Preferences Please refer to supplementary info How to input preferences below.
preferences.type string Y - Preference type Example: "business_position"
preferences.value string Y - Preference value Example: "mR"
schedule_time string N '' Scheduled pickup time - Please omit it for realtime order
- Earliest schedule time = Current time + 30mins
- Latest schedule time = Current time + 31days
- Example: "2020-09-08 16:00"
cancel_time string N - Cancel publish time - If the order is not accepted by any partner by cancel_time, system will cancel the order automatically.
- By default, order will be cancelled in 2 hours after it is created.
- Example: "2020-09-08 16:00"
contact object N - Contact person info
contact.name string N '' Contact person name
contact.country_code string N * Ref to remarks Contact person country code By default, system finds the corresponding country code based on the region value. For example, the default value for region="HK" is "852".
contact.phone string N '' Contact person phone number
path array Y - Delivery waypoints Please input the starting point, waypoints (if any) and destination in sequence.
path[].address string Y - Address
path[].postal_code string N '' Postal code
path[].description string N - Supplementary address
path[].coordinate string Y - Coordinates Ref Geolocation
path[].contact array Y - Contact person(s) for that waypoint It can be multiple contact persons. Minimum one contact person.
path[].contact[].name string Y - Contact person name
path[].contact[].phone string Y - Contact person phone number
path[].contact[].country_code string N * Ref to remarks Contact person country code By default, system finds the corresponding country code based on the region value. For example, the default value for region="HK" is "852".
path[].contact[].company_name string N '' Contact person company name
vas array N [] VAS service Please obtain the available VAS by PA-API-2.1 Get available VAS.
vas[].code string Y - VAS service code
vas[].count string Y - VAS service count
items object Y - Items
items.amount string Y - Item amount - Unit: dollar
- Max. 2 decimal places
items.weight string Y - Item weight - Unit: KG
- Max. 2 decimal places
items.box string Y - Item capacity code Please refer to Box size code
items.types array N [] Item type - Supports "Bouquet""Food""Wine""Doc"
items.detail string N '' Item description
cod object N - Cash on delivery (COD) information
cod.service_fee string N "0.00" Delivery fee - Unit: dollar
- Max. 2 decimal places
cod.cash string N "0.00" Item amount - Unit: dollar
- Max. 2 decimal places
remark object N - Remarks
remark.partner string N '' Remarks for partner
{
    "merchant_id": "1111111",
    "client": {
        "order_id": "order-12345",
        "shipment_code": "ship-12345"
    },
    "product_code": "DASHCALLVAN",
    "preferences": [
        { 
            "type": "business_position",
            "value" : "mR" 
        }
    ],
    "schedule_time": "2020-08-19 19:30",
    "cancel_time": "10",
    "contact": {
        "name": "Kevin Tsang",
        "country_code": "852",
        "phone": "91234567"
    },
    "path": [
        {
            "address": "JW Marriott Hotel Hong Kong, Queensway, Admiralty, Hong Kong",
            "postal_code": "000000",
            "description": "Flat 27, 3/F",
            "coordinate": "22.277495,114.166271",
            "contact": [
                {
                    "name": "Mr. Chan",
                    "phone": "91334455",
                    "country_code": "852",
                    "company_name": "ABC Company" 
                },
                {
                    "name": "Mr. Li",
                    "phone": "91334459"
                }
            ]
        },
        {
            "address": "Hotel Icon, Tsim Sha Tsui, Kowloon",
            "postal_code": "000000",
            "description": "Room 414",
            "coordinate": "22.300813,114.179696",
            "contact": [
                {
                    "name": "Mr. Cheung",
                    "phone": "912345678"
                }
            ]
        }
    ],
    "vas": [
        {
            "code": "HKDASH_HOURS",
            "count": "3"
        },
        {
            "code": "HKDASH_PASSENGER",
            "count": "1"
        }
    ],
    "items": {
        "amount": "9.30",
        "weight": "2.45",
        "box": "M",
        "types": [
            "Food",
            "Wine"
        ],
        "detail": "This is item description"
    },
    "cod": {
        "service_fee": "12.50",
        "cash": "30.50"
    },
    "remark": {
        "partner": "This is the remark sent to partner"
    }
}
# How to input preferences

You need to obtain the available business position values by PA-API-2.2 Get available business positions in advance, so that you can input the appropriate values in this parameter.

If you are going to create order for MPOINTS in Singapore, please input one "business_position" in the preferences parameter.

Here is an example:

"preferences": [
    { 
        "type": "business_position",
        "value" : "mR" 
    }
]

For further question, please consult Zeek team.

# Response

Name Type Description Remarks
order_id string Order ID

Example:

{
    "error": 0,
    "data": {
        "order_id" : "DA-A-04844"
    }
}

# PA-API-3.2 Get order details

POST /order/info

API type Request API
Usage - Get order detailed information.

# Request

Name Type Mandatory Default Description Remarks
merchant_id string Y - Merchant ID in Zeek platform
order_id string Y - Order ID

Example:

{
    "merchant_id": "111111",
    "order_id": "DA-A-04844"
}

# Response

Name Type Description Remarks
order_id string Order ID
merchant_id string Merchant ID in Zeek platform
client object Client info
client.order_id string Client order ID The order ID in Client system
client.shipment_code string Client shippment code The shipping code in Client system
product_code string Product code
order_time string Order creation time
schedule_time string Scheduled pickup time
publish_until_time string The time which the order will be cancelled by system.
accept_time string Partner accepts order time
complete_time string Order completed time
cancel_time string Actual order cancelled time
contact object Contact person info
contact.name string Contact person name
contact.country_code string Contact person country code
contact.phone string Contact person phone number
path array Delivery waypoints - Please input the paths (starting point, midpoints and destination) in sequence.
- Starting point and destination are required.
path[].address string Address
path[].description string Supplementary address
path[].coordinate string Coordinates
path[].contact array Contact person(s) for that waypoint
path[].contact[].name string Contact person name
path[].contact[].phone string Contact person phone number
path[].contact[].country_code string Contact person country code
path[].contact[].company_name string Contact person company name
vas array VAS service
vas[].code string VAS service code
vas[].count string VAS service count
vas[].fee string VAS service fee
items object Items
items.amount string Item amount
items.weight string Item weight
items.box string Item capacity code
items.types array Item type
items.detail string Item description
cod object Cash on delivery (COD) information
cod.type string COD type
cod.service_fee string Delivery fee
cod.cash string Item amount
cod.total string Total fee
payment object Payment info which merchant pay to Zeek
payment.type string Payment type
status object Order status
status.code string Order status code Please refer to Order status code
status.name string Order status description
status.lastmodify string Order status time
partner object Partner info
partner.name string Partner name
partner.country_code string Partner country code
partner.phone string Partner phone number
partner.position object Partner position
partner.position.code string Position code
partner.position.name string Position name
partner.position.vehicle_number string Vehicle number
receipts array Receipt image URLs

Example:

{
    "error": 0,
    "data": {
        "order_id": "DA-A-04788",
        "merchant_id": "1111111",
        "client": {
            "order_id": "order-12345",
            "shipment_code": "ship-12345"
        },
        "product_code": "DASH2HR",
        "order_time": "2020-07-22 15:59", 
        "schedule_time": "2020-07-22 15:59", 
        "publish_until_time": "2020-07-22 15:59",
        "accept_time": "2020-07-22 16:06",
        "complete_time": "2020-07-22 16:06",
        "cancel_time": "2020-07-22 15:59",
        "contact": {
            "name": "Kevin Tsang",
            "country_code": "852",
            "phone": "91234567"
        },
        "path": [
            {
                "address": "JW Marriott Hotel Hong Kong, Queensway, Admiralty, Hong Kong",
                "description": "Flat 27, 3/F",
                "coordinate": "22.277495,114.166271",
                "contact": [
                    {
                        "name": "Mr. Chan",
                        "phone": "91334455",
                        "country_code": "852",
                        "company_name": "ABC Company" 
                    },
                    {
                        "name": "Mr. Li",
                        "phone": "91334459"
                    }
                ]
            },
            {
                "address": "Hotel Icon, Tsim Sha Tsui, Kowloon",
                "description": "Room 414",
                "coordinate": "22.300813,114.179696",
                "contact": [
                    {
                        "name": "Mr. Cheung",
                        "phone": "912345678"
                    }
                ]
            }
        ],
        "vas": [
            {
                "code": "HKDASH_HOURS",
                "count": "3",
                "fee": "6.00",
                "name": "Hourly rental"
            },
            {
                "code": "HKDASH_PASSENGER",
                "count": "1",
                "fee": "6.00",
                "name": "Ride with passengers"
            }
        ],
        "items": {
            "amount": "0.00",
            "weight": "0.00",
            "box": "S",
            "type": "",
            "detail": ""
        },
        "cod": {
            "type": "cash",
            "service_fee": "12.50",
            "cash": "30.50",
            "total": "43.00"
        },
        "payment": {
            "type": "1",
        },
        "status": {
            "code": "9005",
            "name": "About to pickup",
            "lastmodify": "2020-07-22 16:06"
        },
        "partner": {
            "name": "Albert Chan",
            "country_code": "852",
            "phone": "17612008",
            "position": {
                "code": "R",
                "name": "Motobike",
                "vehicle_number": "RJ 456"
            }
        },
        "receipts": [
            "https://ap1-img.zeek.one/1.jpeg",
            "https://ap1-img.zeek.one/2.jpeg",
            "https://ap1-img.zeek.one/3.jpeg",
        ]
    }
}

# PA-API-3.3 Cancel order

POST /order/cancel

API type Request API
Usage Cancel order

# Request

Name Type Mandatory Default Description Remarks
merchant_id string Y - Merchant ID in Zeek platform
order_id string Y - Order ID
cancel_reason string N '' Reason to cancel order
{
    "merchant_id": "111111",
    "order_id": "DA-A-04844",
    "cancel_reason": "Cancelled by customer"
}

# Response

Example:

{
    "error": 0
}

# PA-API-3.4 Order status 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.

# Request

  • Zeek platform sends API request to Client system
Name Type Mandatory Default Description Remarks
order_id string Y - Order ID
merchant_id string Y - Merchant ID in Zeek platform
client object Y - Client info
client.order_id string Y '' Client order ID The order ID in Client system
client.shipment_code string Y '' Client shippment code The shipping code in Client system
status object Y - Order status
status.code string Y - Order status code Please refer to Order status code
status.name string Y - Order status description Zeek platform will send in same the language when the order is created.
status.lastmodify string Y - Order status time
{
    "order_id": "DA-A-04844",
    "merchant_id": "1111111",
    "client": {
        "order_id": "order-12345",
        "shipment_code": "ship-12345"
    },
    "status": {
        "code": "9005",
        "name": "About to pickup",
        "lastmodify": "2020-07-22 16:06",
    }
}

# Response

  • Please reply the payload below for successful API response. Otherwise, Zeek platform will consider the callback is failed and retry.
{
    "error": 0
}

# PA-API-3.5 Get order status

POST /order/status

API type Request API
Usage Get the latest order status

# Request

Name Type Mandatory Default Description Remarks
merchant_id string Y - Merchant ID in Zeek platform
order_id string Y - Order ID

Example:

{
    "merchant_id": "1111111",
    "order_id": "DA-A-04844"
}

# Response

Name Type Description Remarks
status object Y -
status.code string Y -
status.name string Y -
status.lastmodify string Y -

Example:

{
    "error": 0,
    "data": {
        "status": {
            "code": "9005",
            "name": "About to pickup",
            "lastmodify": "2020-07-22 16:06"
        }
    }
}