notifyOrderChange

POST /v2/pds/order/notifyOrderChange

With this API call, the SaaS provider or ISV can notify D-store Platform of any changes to an order, for example, when the user modifies the pickup time of the order.

Note:

  • In the request body, provide the values for relevant fields you want to change. Do not include existing values that haven't changed. For example, to update an item in the order, provide the values of the OrderItem object for the updateItems field.
  • For any changes to an order, call this API to notify D-store Platform immediately, otherwise it may cause inconsistent order status.
  • If you call this API to remove, update, add, or replace items in an order:
    • For eat-before-payment orders, the order amount can change accordingly.
    • For pay-before-eating orders with completed payments, this API cannot change the order amount. If the actual amount is less than the payment, you can specify the totalRefundAmount parameter to issue refunds to customers. However, if the actual amount exceeds the payment, merchants need to seek offline solutions.

Before you begin

Before you integrate with this API, it is recommended to learn the following basic concepts:

  • Eat-before-payment

Eat-before-payment is a dining scenario where the users enjoy their meals first and check out later. In mini programs, this dining scenario is only applicable to dining-in orders and allows users to add items to their original order by placing multiple additional orders.

  • Main order

A main order is the combination of the first order and all additional orders placed for one single dining experience. This type of order is available only in the eat-before-payment scenario and can have one or more subordinate orders.

  • Subordinate order

A subordinate order is the first order or an additional order placed for one single dining experience. This type of order is available only in the eat-before-payment scenario and related to a main order.

  • Whole order

A whole order is a dining-in order placed with a payment, which users cannot add items to. This concept is used to refer to dining-in orders that are not placed in the eat-before-payment scenario.

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

requestId

String

Yes

Indicates the unique ID assigned by the SaaS provider or ISV to identify a request for order change notification.

  • Maximum length: 255 characters

Note: This field is an API idempotency field. For the notifyOrderChange requests that are initiated with the same requestId value, D-store Platform must return the same result. For details about API idempotency, see the Idempotency chapter.

Suggest using orderId_timestamp, for example,

"12324534534534_12321"

requestOrderId

String

Yes

Indicates the unique ID assigned by D-store Platform to identify an order.

  • Maximum length: 255 characters

Note: Specify this parameter to determine which order to change.

-

removeItemIds

Array<String>

No

Indicates the list of unique IDs assigned by the SaaS provider or ISV to identify the items to be removed from the order.

  • Maximum size: 120 elements
  • Element maximum length: 255 characters

Note: This parameter will be deprecated. To remove items, specify the removeRequestSubOrderIds parameter.

["123","456"]

removeRequestSubOrderIds

Array<String>

No

Indicates the list of unique IDs assigned by D-store Platform to identify the items to be removed from the order.

  • Maximum size: 120 elements
  • Element maximum length: 255 characters

Note: Specify this parameter to remove one or more items. For the sample request, see Remove item.

["2022050400311864775"]

addItems

Array<OrderItem>

No

Indicates the list of items to be added.

  • Maximum size: 120 elements

Note: Specify this parameter to add one or more items. For the sample request, see Add item.

-

updateItems

Array<OrderItem>

No

Indicates the list of items to be updated.

  • Maximum size: 120 elements

Note: Specify this parameter to update one or more items. For the sample request, see Update item.

-

totalRefundAmount

Integer

No

Indicates the total amount to be refunded to the user. D-store Platform will process the refund based on this amount.

Value range: 0-unlimited

Note: Specify this parameter to indicate the total amount to be refunded. For the sample request, see Initiate a refund.

-

adjustAmount

AdjustAmount

No

Indicates the way to adjust the amount and the amount to be adjusted. Specify this parameter if you need to adjust the main order amount. For the sample request, see Adjust amount.

Note: The adjustment is determined by the latest request if you send multiple requests with this parameter specified.

-

pickUpTime

Datetime

No

Indicates the modified pickup time after consultation between the user and the merchant. The value follows the ISO 8601 standard format.

Note: Specify this parameter to change the pickup time. For the sample request, see Change pickup time.

"2019-11-27T12:01:01+08:30"

orderStatus

String

No

Indicates the status of the order.

Valid values are:

  • When the value of orderType is PICKUP:
    • ACCEPTED: The merchant accepts the order.
    • REJECTED: The merchant rejects the order.
    • PREPARING: The order is being prepared.
    • READY: The order is ready for the user to pick up.
    • COMPLETED: The order is completed.
  • When the value of orderType is DINEIN:
    • ACCEPTED: Indicates that the merchant accepts the whole order or the subordinate order.
    • REJECTED: Indicates that the merchant rejects the whole order or the subordinate order.
    • PREPARING: Indicates that the whole order or the subordinate order is being prepared.
    • READY: Indicates that the whole order or the subordinate order is ready to be served.
    • FULFILLMENT_COMPLETED: Indicates that the subordinate order is completed. This value is only applicable to orders in the eat-before-payment scenario.
    • COMPLETED: Indicates the completion of either of the following two types of order:
      • The whole order
      • The main order, which means all of its subordinate orders are completed
  • When the value of orderType is DELIVERY:
    • ACCEPTED: The merchant accepts the order.
    • REJECTED: The merchant rejects the order.
    • PREPARING: The order is being prepared.
    • READY: The order is ready for the delivery person to pick up.
    • SHIPPING: The order is shipped and on the way.
    • NEARBY: The delivery person is approaching and the order is about to be delivered.
    • DELIVERED: The order is delivered.
    • COMPLETED: The order is completed.

Notes:

  • Specify this parameter to update the order status. For the sample request, see Update order status.
  • You can call this API and specify the value of orderStatus as ACCEPTED or REJECTED to set your order status as accepted or rejected, instead of calling the notifyOrderAcceptance API.
  • You can call this API and specify the value of orderStatus as COMPLETED to set your order status as completed, instead of calling the notifyOrderCompletion API.

"NEARBY"

deliveryDetail

DeliveryDetail

No

Indicates the delivery details of the user, for example, the delivery address or expected delivery time.

Note: Specify this parameter to change the delivery details. For the sample request, see Change delivery detail.

-

extendInfo

Map<String,String>

No

Indicates the extended information about this API.

  • Maximum length: 2048 characters

Take the following examples:

  • Specify the rebatedAssets parameter that indicates what and how much the user earns by making purchases. Valid values are:
    • POINT: Earn reward points by making purchases. The corresponding value is an integer (Value range: 0-2147483647).
    • BALANCE: Earn cash back by making purchases. The corresponding value is an Amount object.
  • Specify the rejectOrderReason parameter that indicates the reason for the order rejection. This parameter is a JSON string with a maximum length of 300 characters.

Example 1:

{"rebatedAssets":"{\"POINT\":100,\"BALANCE\":{\"currency\":\"SGD\",\"amountValue\":100}}"}

Example 2:

{"rejectOrderReason": "The store is closed."}

Response parameters

Field

Data type

Required

Description

result

Result

Yes

Indicates the request result, such as status and error codes.

addResults

Array<OrderItem>

No

Indicates the details of the items that are added to the order.

Note:

  • This parameter must be returned when the SaaS provider or ISV calls this API to add one or more items to the order.
  • For the sample response, see Add item.

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 

A

The request for order change notification is accepted by us.

The corresponding result.resultCode and result.resultMessage may vary based on different situations. For details, see the following Error codes section.

S

The notification is sent successfully.

The corresponding result.resultCode is SUCCESS and result.resultMessage is SUCCESS.

U

The status of the notification 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 notification is failed to be sent.

The corresponding result.resultCode and result.resultMessage may vary based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

  • Common error codes are common for F&B mini program OpenAPIs.
  • API-specific error codes: This API does not have its dedicated error codes.

Samples

Request

Change order information

The following examples demonstrate the sample requests to change order information:

Update order status

To update the order status:

  • Specify the orderStatus parameters with valid values defined in the request parameters.
  • Update the order status to any upcoming status instead of the previous status.

Pickup

  • The value of orderType is PICKUP.
  • The valid values for the orderStatus parameter include:
    • ACCEPTED
    • REJECTED
    • PREPARING
    • READY
    • COMPLETED
  • If the initial status specified for an order is COMPLETED or REJECTED(indicates final status), you cannot call this API to update the order status.

See the following examples:

copy
{
    "requestId": "165163872164627201c17****",
    "requestOrderId": "pds_2109220000232584_2022050400309038585_2",
    "orderStatus": "ACCEPTED"
}
copy
{
    "requestId": "165163872164627201c17****",
    "requestOrderId": "pds_2109220000232584_2022050400309038585_2",
    "orderStatus": "REJECTED",
    "extendInfo":"{\"rejectOrderReason\":\"The store is closed.\"}"
}

Dine-in

  • The value of orderType is DINEIN.
  • The valid values for the orderStatus parameter include:
    • ACCEPTED
    • REJECTED
    • PREPARING
    • READY
    • FULFILLMENT_COMPLETED (only applicable to orders in the eat-before-payment scenario)
    • COMPLETED
  • If the initial status specified for an order is COMPLETED or REJECTED(indicates final status), you cannot call this API to update the order status.

See the following example:

copy
{
    "requestId": "165163872164627201c17****",
    "requestOrderId": "pds_2109220000232584_2022050400309038585_2",
    "orderStatus": "ACCEPTED"
}

Delivery

  • The value of orderType is DELIVERY.
  • The valid values for the orderStatus parameter include:
    • ACCEPTED
    • REJECTED
    • PREPARING
    • READY
    • SHIPPING
    • NEARBY
    • DELIVERED
    • COMPLETED

See the following example:

copy
{
    "requestId": "165163872164627201c17aa16",
    "requestOrderId": "pds_2109220000232584_2022050400309038584_1",
    "orderStatus": "SHIPPING"
}

Remove item

To remove items:

  • Specify the removeRequestSubOrderIds parameter to identify the items to be removed.
  • Items can only be removed when the order is in any of the following cases:
    • For orders not in the eat-before-payment scenario, the value of the orderStatus parameter needs to be: ACCEPTED, PREPARING, READY, SHIPPING, NEARBY, DELIVERED, or COMPLETED
    • For orders in the eat-before-payment scenario, the value of the orderStatus parameter needs to be: ACCEPTED, PREPARING, READY, or FULFILLMENT_COMPLETED

See the following example:

copy
{
    "requestId": "165163872164627201c17aa16",
    "requestOrderId": "pds_2109220000232584_2022050400309038584_1",
    "removeRequestSubOrderIds": [
        "2022050400311864775"
    ]
}

Update item

To update items:

  • Specify the updateItems parameter to indicate the items to be updated.
  • Items can only be updated when the order is in any of the following cases:
    • For orders not in the eat-before-payment scenario, the value of the orderStatus parameter needs to be: ACCEPTED, PREPARING, READY, SHIPPING, NEARBY, DELIVERED, or COMPLETED
    • For orders in the eat-before-payment scenario, the value of the orderStatus parameter needs to be: ACCEPTED, PREPARING, READY, or FULFILLMENT_COMPLETED

See the following example:

copy
{
    "requestId": "165163872164627201c17aa16",
    "requestOrderId": "pds_2109220000232584_2022050400309038584_1",
    "updateItems": [
        {
            "categoryId": "100",
            "itemId": "11010",
            "notAvailableOption": "Remove it from my order",
            "priceInfo": {
                "currency": "SGD",
                "saleAmount": 869
            },
            "quantity": 1,
            "skuId": "76251",
            "storeId": "121",
            "requestSubOrderId": "2022050400311864775"
        }
    ]
}
Update item quantity

To update item quantity:

  • Item quantity can only be updated when the value of orderStatus is any of the following: ACCEPTED, PREPARING, READY, or COMPLETED.
  • Items requiring updates must be included in the order before and after the API request. If you want to add a new item or remove an existing item, refer to Add item or Remove item respectively.

In the previous example, the quantity of the item (with itemId specified as 11010) is 1 (as specified in the quantity parameter). With the following sample code, the quantity for this same item is changed to 2:

copy
{
  "requestId": "165163872164627201c17aa16",
  "requestOrderId": "pds_2109220000232584_2022050400309038584_1",
  "updateItems": [
    {
      "categoryId": "100",
      "itemId": "11010",
      "notAvailableOption": "Remove it from my order",
      "quantity": 2,
      "priceInfo": {
        "currency": "SGD",
        "saleAmount": 869
      },
      "skuId": "76251",
      "storeId": "121",
      "requestSubOrderId": "2022050400311864775"
    }
  ]
}

Add item

To add items:

  • Specify the addItems parameter to indicate the items to be added.
  • Items can only be added when the order is in any of the following cases:
    • For orders not in the eat-before-payment scenario, the value of the orderStatus parameter needs to be: ACCEPTED, PREPARING, READY, SHIPPING, NEARBY, DELIVERED, or COMPLETED
    • For orders in the eat-before-payment scenario, the value of the orderStatus parameter needs to be: ACCEPTED, PREPARING, READY,or FULFILLMENT_COMPLETED

See the following example:

copy
{
    "requestId": "165163872164627201c17aa16",
    "requestOrderId": "pds_2109220000232584_2022050400309038584_1",
    "addItems": [
        {
            "categoryId": "100",
            "itemId": "11010",
            "notAvailableOption": "Remove it from my order",
            "priceInfo": {
                "currency": "SGD",
                "saleAmount": 869
            },
            "quantity": 1,
            "skuId": "76251",
            "storeId": "121"
        }
    ]
}

Replace item

To replace items:

  • Specify the addItems parameter to indicate the new items and the removeRequestSubOrderIds parameter to indicate the old items to be replaced.
  • Items can only be replaced when the order is in any of the following cases:
    • For orders not in the eat-before-payment scenario, the value of the orderStatus parameter needs to be: ACCEPTED, PREPARING, READY, SHIPPING, NEARBY, DELIVERED, or COMPLETED
    • For orders in the eat-before-payment scenario, the value of the orderStatus parameter needs to be: ACCEPTED, PREPARING, READY, or FULFILLMENT_COMPLETED

See the following example:

copy
{
    "requestId": "165163872164627201c17aa16",
    "requestOrderId": "pds_2109220000232584_2022050400309038584_1",
    "addItems": [
        {
            "categoryId": "100",
            "itemId": "11010",
            "notAvailableOption": "Remove it from my order",
            "priceInfo": {
                "currency": "SGD",
                "saleAmount": 869
            },
            "quantity": 1,
            "skuId": "76251",
            "storeId": "121"
        }
    ],
    "removeRequestSubOrderIds": [
        "2022050400311864775"
    ]
}

Change pickup time

To change the pickup time:

  • Specify the pickUpTime parameter with a new value, which is only applicable for dine-in or pickup orders.
  • The pickup time can only be changed when the current order status is ACCEPTED, PREPARING, or READY.
  • For a request to change the order status and pickup time, make sure the order status changed is ACCEPTED, PREPARING, or READY.

See the following example:

copy
{
    "requestId": "165163872164627201c17aa16",
    "requestOrderId": "pds_2109220000232584_2022050400309038584_1",
    "pickUpTime": "2019-11-27T12:01:01+08:30"
}

Change delivery detail

To change delivery detail:

  • Specify the deliveryDetail object with new values, which is only applicable for delivery orders.
  • The delivery detail can only be changed after the order is accepted by the merchant (ACCEPTED) and before the order is delivered (DELIVERED).

See the following example:

copy
{
    "requestId": "165163872164627201c17aa16",
    "requestOrderId": "pds_2109220000232584_2022050400309038584_1",
    "deliveryDetail": {
        "expectedDeliveryTimeStart": "2019-11-27T12:01:01+08:30",
        "expectedDeliveryTimeEnd": "2019-11-27T12:01:01+08:30",
        "estimatedDeliveryTimeStart": "2019-11-27T12:01:01+08:30",
        "estimatedDeliveryTimeEnd": "2019-11-27T12:01:01+08:30",
        "delayReason": "WEATHER"
    }
}

Adjust amount

The following sample shows that an amount of 5,500 SGD is deducted from the main order in the eat-before-payment scenario:

copy
{
  "requestId": "165163872164627201c17aa16",
  "requestOrderId": "pdsful_2023033100061527027_2023033101726454027",
  "adjustAmount":{
    "type":"REDUCE",
    "adjustPrice":{
      "value":5500,
      "currency":"SGD"
    }
  }
}

Initiate a refund

To initiate a refund,

  • Specify the totalRefundAmount parameter to indicate the amount to be refunded to the user.
  • The refund can only be processed when the order is in ACCEPTED and subsequent statuses (including PREPARING, READY, SHIPPING, NEARBY, DELIVERED, and COMPLETED).
  • The total refund amount, including failed refunds, cannot be greater than the payment amount.
  • Refund is not applicable to orders in the eat-before-payment scenario when the payment is made in store.

See the following example:

copy
{
    "requestId": "165163872164627201c17aa16",
    "requestOrderId": "pds_2109220000232584_2022050400309038584_1",
    "totalRefundAmount": 55
}

Response

Add item

The following provides the sample response for adding an item to the order:

copy
{
    "addResults": [
        {
            "categoryId": "100",
            "itemId": "11010",
            "notAvailableOption": "Remove it from my order",
            "priceInfo": {
                "currency": "SGD",
                "saleAmount": 869
            },
            "quantity": 1,
            "skuId": "76251",
            "storeId": "121",
            "requestSubOrderId": "2022050400311864775"
        }
    ],
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success",
        "resultStatus": "S"
    }
}

Replace item

The following provides the sample response for replacing items in an order:

copy
{
    "addResults": [
        {
            "categoryId": "100",
            "itemId": "11010",
            "notAvailableOption": "Remove it from my order",
            "priceInfo": {
                "currency": "SGD",
                "saleAmount": 869
            },
            "quantity": 1,
            "skuId": "76251",
            "storeId": "121",
            "requestSubOrderId": "2022050400311864775"
        }
    ],
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success",
        "resultStatus": "S"
    }
}

Other changes to the order

The following provides the sample response for other changes to the order, for example, removing items, updating items, or changing pickup time, delivery detail, order status, or refund amount.

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