/v2/miniprogram/order/sync

2023-04-28 21:00

POST /v2/miniprogram/order/sync

With this API call, a merchant can synchronize an order to the super app via Mini Program Platform, such as order items, order status, and so on.

Note: The parameters that are marked No in the Required column are optional. To pass such parameters, you need to specify values to them, instead of passing empty strings, arrays, or objects.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field	Data type	Required	Description	Example
appId	String	Yes	Indicates the unique ID assigned by Mini Program Platform to identify a mini program. Maximum length: 32 characters Characters not allowed: special characters such as @ # ?	"3333010071465913xxx"
customerId	String	Yes	Indicates the unique ID assigned by Mini Program Platform to identify a user. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	"1000001119398804xxxx"
customerBelongsTo	String	Yes	Indicates the super app that a user uses. Valid values are: `ALIPAY_CN`: Alipay CN `ALIPAY_HK`: Alipay HK `ALIPAY_MO`: Alipay MO `TNG`: Touch 'n Go `GCASH`: GCash `DANA`: DANA `KAKAOPAY`: KakaoPay `BKASH`: bKash `CHOPE`: Chope `TRUEMONEY`: TrueMoney	"TNG"
referenceOrderId	String	Yes	Indicates the unique ID assigned by the merchant to identify a merchant's order. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	"10000003333010071465913xxx"
orderCreateTime	Datetime	Yes	Indicates the time when the order is created. The value follows the ISO 8601 standard format.	"2022-04-20T10:38:09+08:00"
orderModifiedTime	Datetime	Yes	Indicates the time when the order is modified. The value follows the ISO 8601 standard format.	"2022-04-20T10:38:09+08:00"
orderLinkUrl	String	No	Indicates the URL of the order details page in the mini program. Maximum length: 1024 characters	"pages/orders/10000003333010071465913xxx"
orderType	String	Yes	Indicates the type of the order. Valid values are: `PICK_UP`: Food that is picked up by users themselves. `DINE_IN`: Food that is eaten in the restaurant where it is ordered. `DELIVERY`: Food that is delivered to a specific destination.	"PICK_UP"
orderExtendBizInfo	String	Yes	Indicates the extended business information of the order. Maximum length: 2048 characters Characters not allowed: special characters such as @ # ? Note: For extended fields, order status flows, and order status rules for different order types, refer to More information.	{ "orderBizStatus":"COMPLETED", "pickUpStartTime":"2022-04-20T10:38:09+08:00", "pickUpEndTime":"2022-04-20T11:38:09+08:00", "pickUpCodeName":"Order code", "pickUpCodeValue":"101xx" }
goods	Array<Goods>	Yes	Indicates the information related to goods. Maximum size: 30 elements	-
merchant	Merchant	Yes	Indicates the information related to the merchant.	-
buyer	Buyer	Yes	Indicates the information related to the buyer.	-
orderAmount	Amount	Yes	Indicates the total amount of the order.	{ "currency": "USD", "value": 10000 }
discountAmount	Amount	No	Indicates the discount amount of the order.	{ "currency": "USD", "value": 1000 }
promoDetails	Array<PromoDetail>	No	Indicates the discount details of the order. Maximum size: 30 elements	-
paymentAmount	Amount	No	Indicates the amount paid for the order.	{ "currency": "USD", "value": 9000 }
refunds	Arrary<Refund>	No	Indicates the refund details of the order. Maximum size: 30 elements	-

Response parameters

Field	Data type	Required	Description
result	Result	Yes	Indicates the request result such as status and error codes.

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

Result status	Description
S	The order synchronization request is successful. The corresponding result.resultCode is `SUCCESS` and result.resultMessage is `SUCCESS`.
U	The status of the order synchronization request is unknown. The corresponding result.resultCode is `UNKNOWN_EXCEPTION` and result.resultMessage is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section.
F	The order synchronization request is failed. The corresponding result.resultCode and result.resultMessage may vary based on different situations. For details, see the following Error codes section.

More information

The following sections provide more information about the order by different order types, including the extended fields, order status flow, and order status rules.

Extended fields

PICK_UP

Field	Data type	Required	Description
orderBizStatus	String	Yes	Indicates the current order status. Valid values are: `CREATED`: The order is created successfully. `WAIT_PAY`: The order is not paid and waiting for the user to pay. `PAID`: The order is paid successfully. `PENDING`: The order is waiting for confirmation from the merchant. `ACCEPTED`: The merchant accepted the order. `PREPARING`: The order is being prepared by the merchant. `READY`: The order is ready for pickup. `COMPLETED`: The order is completed. `CANCELLED`: The order is canceled. `PAY_FAILED`: The payment failed. `REJECTED`: The merchant rejected the order.
pickUpStartTime	Datetime	No	Indicates the estimated earliest pickup time. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
pickUpEndTime	Datetime	No	Indicates the estimated latest pickup time. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
pickUpCodeName	String	No	Indicates the name of the code that the user uses to retrieve their pickup order. Maximum length: 256 characters
pickUpCodeValue	String	No	Indicates the value of the code that the user uses to retrieve their pickup order. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?

DINE_IN

Property	Data type	Required	Description
orderBizStatus	String	Yes	Indicates the current order status. Valid values are: `CREATED`: The order is created successfully. `WAIT_PAY`: The order is not paid and waiting for the user to pay. `PAID`: The order is paid successfully. `PENDING`: The order is waiting for confirmation from the merchant. `ACCEPTED`: The merchant accepted the order. `PREPARING`: The order is being prepared by the merchant. `READY`: The order is ready. `COMPLETED`: The order is completed. `CANCELLED`: The order is canceled. `PAY_FAILED`: The payment failed. `REJECTED`: The merchant rejected the order.
dineInStartTime	Datetime	No	Indicates the estimated earliest dine-in time. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
dineInEndTime	Datetime	No	Indicates the estimated latest dine-in time. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
dineInCodeName	String	No	Indicates the name of the code that the user uses to retrieve their dine-in order. Maximum length: 256 characters
dineInCodeValue	String	No	Indicates the value of the code that the user uses to retrieve their dine-in order. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?

DELIVERY

Field	Data type	Required	Description
orderBizStatus	String	Yes	Indicates the current order status. Valid values are: `CREATED`: The order is created successfully. `WAIT_PAY`: The order is not paid and waiting for the user to pay. `PAID`: The order is paid successfully. `PENDING`: The order is waiting for confirmation from the merchant. `ACCEPTED`: The merchant accepted the order. `PREPARING`: The order is being prepared by the merchant. `READY`: The order is ready to deliver. `IN_DELIVERY`: The order is on the way. `DELIVERED`: The order is delivered. `COMPLETED`: The order is completed. `CANCELLED`: The order is canceled. `PAY_FAILED`: The payment failed. `REJECTED`: The merchant rejected the order.
deliveryStartTime	Datetime	No	Indicates the estimated earliest delivery time. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
deliveryEndTime	Datetime	No	Indicates the estimated latest delivery time. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
courierName	String	No	Indicates the name of the delivery person. Maximum length: 256 characters
courierPhoneNo	String	No	Indicates the contact number of the delivery person. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?

Order status flow

PICK_UP

The following diagram illustrates the order status flow of pickup orders:

yuque_diagram (2).jpg

The diagram can be described as follows:

Start with the status CREATED when a user places an order. Change the status to WAIT_PAY.

If the payment is successful, change the status to PAID.
If the payment is failed, change the status to PAY_FAILED.
If the payment timed out or the user cancels the order, initiate the order cancellation process and change the status to CANCELLED.

Since the merchant is responsible for accepting the order, there are two possible upcoming statuses:

If the merchant accepts the order, change the status to ACCEPTED.
If the merchant rejects the order, change the status to REJECTED.

Change the status to PREPARING and switch to READY when the order is ready for pickup.
Once the user picks up the food, change the status to COMPLETED.

DINE_IN

The following diagram illustrates the order status flow of dine-in orders:

yuque_diagram (3).jpg

The diagram can be described as follows:

Start with the status CREATED when a user places an order. Change the status to WAIT_PAY.

If the payment is successful, change the status to PAID.
If the payment is failed, change the status to PAY_FAILED.
If the payment timed out or the user cancels the order, initiate the order cancellation process and change the status to CANCELLED.

Since the merchant is responsible for accepting the order, there are two possible upcoming statuses:

If the merchant accepts the order, change the status to ACCEPTED.
If the merchant rejects the order, change the status to REJECTED.

Change the status to PREPARING and switch to READY when the order is ready for the user to enjoy.
Once the user gets the food, change the status to COMPLETED.

DELIVERY

The following diagram illustrates the order status flow of delivery orders:

yuque_diagram (4).jpg

The diagram can be described as follows:

Start with the status CREATED when a user places an order. Change the status to WAIT_PAY.

If the payment is successful, change the status to PAID.
If the payment is failed, change the status to PAY_FAILED.
If the payment timed out or the user cancels the order, initiate the order cancellation process and change the status to CANCELLED.

Since the merchant is responsible for accepting the order, there are two possible upcoming statuses:

If the merchant accepts the order, change the status to ACCEPTED.
If the merchant rejects the order, change the status to REJECTED.

Change the status to PREPARINGand switch to READY when the order is ready for the delivery person to deliver.
Change the status to IN_DELIVERY when the delivery person collects the order and is on the way to the destination. Switch to DELIVERED when the delivery person delivers the order to the user.
Change the status to COMPLETED.

Order status rules

Follow the following rules when you synchronize the order statuses:

When synchronizing an order for the first time, the initial status does not have to be CREATED.
A cross-status passing is supported. For example, you can change the status CREATED to COMPLETED directly, skipping other statuses in between.

Error codes

Error codes are usually classified into the following categories:

Common error codes are common for all mini program OpenAPIs in V2.
API-specific error codes: This API does not have its dedicated error codes.

Samples

The following diagram illustrates the sequence of order synchronization:

The steps in the diagram are described as follows:

The merchant initiates a request for order synchronization. [1]
Mini Program Platform validates the merchant's request and saves the order details. [2-3]
Mini Program Platform returns the order details to the merchant. [4]
Mini Program Platform asynchronously initiates a request for order synchronization. [5]
Mini Program Platform calls the order sync API implemented by the super app. [6]
The super app returns the response to Mini Program Platform. [7]

Request

copy
{
    "appId": "2102010120672524",
    "customerId": "1000001119398804xxxx",
    "customerBelongsTo": "CHOPE",
    "referenceOrderId": "011164447512282000000002060",
    "orderCreateTime": "2022-04-20T10:38:09+08:00",
    "orderModifiedTime": "2022-04-20T10:38:09+08:00",
    "orderLinkUrl": "pages/orders/xxxxx",
    "orderType": "PICK_UP",
    "orderExtendBizInfo": {
        "orderBizStatus": "PAID",
        "pickUpStartTime": "2022-04-20T10:38:09+08:00",
        "pickUpEndTime": "2022-04-20T10:38:09+08:00",
        "pickUpCodeName": "9001",
        "pickUpCodeValue": "122234"
    },
    "goods": [
        {
            "referenceGoodsId": "38834854894322",
            "goodsName": "jfkdskk",
            "goodsCategory": "fjkdskks",
            "goodsBrand": "adwqads",
            "goodsUnitAmount": {
                "currency": "USD",
                "value": 126
            },
            "goodsPaymentAmount": {
                "currency": "USD",
                "value": 126
            },
            "goodsQuantity": "3",
            "goodsSkuName": "xxxx",
            "goodsUrl": "pages/goods/xxxxx",
            "extendInfo": "{\"key\": \"value\"}"
        }
    ],
    "merchant": {
        "referenceMerchantId": "fdsjkkkk",
        "merchantMCC": "dsakkk",
        "merchantName": "fdsafds",
        "merchantDisplayName": "dsafsa",
        "merchantAddress": {
            "region": "US",
            "state": "NYS",
            "city": "NYC",
            "address1": "Street address/PO Box/Company name",
            "address2": "Apartment/Suite/Unit/Building",
            "label": "home",
            "zipCode": "220311",
            "longitude": "120.000000",
            "latitude": "40.7000000",
            "extendInfo": "{\"key\": \"value\"}"
        },
        "merchantRegisterDate": "2022-04-03T17:30:08+08:00",
        "merchantStore": {
            "referenceStoreId": "fassaa",
            "storeName": "Restaurant A",
            "storeMCC": "food",
            "storeDisplayName": "Restaurant A",
            "storeTerminalId": "dfsadsa",
            "storeOperatorId": "dfsafdfsgs",
            "storeAddress": {
                "region": "US",
                "state": "NYS",
                "city": "NYC",
                "address1": "Street address/PO Box/Company name",
                "address2": "Apartment/Suite/Unit/Building",
                "label": "home",
                "zipCode": "220311",
                "longitude": "74.000000",
                "latitude": "40.000000",
                "extendInfo": "{\"key\": \"value\"}"
            },
            "storePhoneNo": "13321324456"
        }
    },
    "buyer": {
        "referenceBuyerId": "userId",
        "buyerName": {
            "fullName": "Jack"
        },
        "buyerPhoneNo": "13312341234",
        "buyerEmail": "email@example.com"
    },
    "orderAmount": {
        "currency": "USD",
        "value": 1236
    },
    "discountAmount": {
        "currency": "USD",
        "value": 36
    },
    "promoDetails": [
        {
            "promoId": "salon",
            "promoType": "INSTANT_DISCOUNT",
            "promoName": "name",
            "discountAmount": {
                "currency": "USD",
                "value": 36
            },
            "extendInfo": "{}"
        }
    ],
    "paymentAmount": {
        "currency": "USD",
        "value": 12
    },
    "refunds": [
        {
            "refundId": "fds11254556636",
            "refundAmount": {
                "currency": "USD",
                "value": 36
            },
            "refundStatus": "SUCCESS",
            "refundTime": "2022-04-20T10:38:09+08:00"
        }
    ]
}

Response

copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "SUCCESS"
    }
}