D-Store DocsD-Store DocsDOCS

notifyOrderChange

POST /v2/pos/notifyOrderChange

The notifyOrderChange API is called by the POS provider to notify DSstore of any changes to the order. During the order fulfillment, you can call this API in the following scenarios:

  • Update the short order number to be displayed on the order details page
  • Update the order status
  • Initiate a full or partial refund from the merchant side
  • Update the order ready time
  • Update the delivery status for an order with a merchant-provided delivery service

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

requestId

String

Yes

The unique ID that is assigned by the POS provider to identify a request for order change notification.

Maximum length: 255 characters

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

requestOrderId

String

Yes

The unique ID that is assigned by D-Store to identify an order.

Maximum length: 255 characters

shortOrderNumber

String

No

The code for the buyer to collect the order.

Maximum length: 255 characters

Note: Specify this parameter to update a short order number. For the sample request, see Update short order number.

orderStatus

String

No

The latest order status. Refer to Order journey to specify this parameter properly. Valid values are:

  • For success-related statuses:
    • ACCEPTED: The merchant accepts the order.
    • PREPARING: The order is being prepared.
    • READY: The order is ready for the buyer to pick up or enjoy.
    • COMPLETED: The order is completed.
  • For issue-related statuses:
    • REJECTED: The merchant rejects the order.
    • CANCELLED: The merchant cancels the order.

Note: Specify this parameter to update the order status. For more information, see Update order status.

deliveryStatus

String

No

The latest delivery status of the order. Specify this parameter if the order involves a merchant-provided delivery service. Valid values are:

  • ALLOCATED: A delivery rider is allocated for the order.
  • ARRIVED: The delivery rider has arrived at the merchant's location to collect the order.
  • COLLECTED: The delivery rider has collected the order.
  • DELIVERED: The order is delivered to the buyer.

Note: Specify this parameter to update the delivery status. For more information, refer to Update delivery status.

refundAmount

Amount

No

The amount to be refunded to the buyer.

Value range: 0-unlimited

Note: Specify this parameter to initiate a refund to the buyer. For more information, see Initiate a refund.

orderReadyTime

String

No

The estimated time when the order is ready. The value follows the ISO 8601 standard format.

Note: Specify this parameter to update the order ready time. For more information, see Update order ready time.

extendInfo

Object

No

An extended attribute that is used to provide additional information if necessary.

Maximum length: 2048 characters

This parameter is specified in key-value pairs with the following valid key:

  • failureReason: OptionalThe reason why the merchant rejects or cancels the order. Specify this key if the orderStatus parameter is set to REJECTED or CANCELLED. Its value is String with the following valid values:
    • ITEM_UNAVAILABLE: Some items in the order are invalid or out of stock.
    • STORE_TOO_BUSY: The merchant's store is too busy to process the order.
    • STORE_TEMPORARILY_CLOSED: The merchant's store is temporarily closed.
    • NO_RIDERS: No delivery riders are available. This may occur if the order involves a merchant-provided delivery service.
    • OTHER: The order failed due to an unspecified issue.

Response parameters

Field

Data type

Required

Description

result

Result

Yes

The result of the order change notification request.

More information

How to handle the result

You might receive different results from D-Store. Follow the instructions in this table to handle the result.

result.resultStatus

result.resultCode

Notification status

Actions

S

SUCCESS

D-Store is notified of the order change successfully.

N/A

F

Multiple possible values exist, such as

ACCESS_DENIED,

PROCESS_FAIL, etc.

D-Store failed to be notified of the order change.

Take actions according to the result code (specified in the result.resultCode parameter). For more information, see Result codes.

U

UNKNOWN_EXCEPTION

Unknown

Use the same parameters to retry the notifyOrderChange request. If you keep receiving the same result indicating the unknown status, contact overseas_support@service.alibaba.com.

No result received

Unknown

Use the same parameters to retry the notifyOrderChange request. If you keep receiving no results, contact overseas_support@service.alibaba.com.

Result codes

Result code

Result status

Result message

Further action

SUCCESS

S

success

N/A

PROCESS_FAIL

F

A general business failure occurred. Do not retry.

Contact overseas_support@service.alibaba.com to troubleshoot the issue.

PARAM_ILLEGAL

F

Parameter names or values do not meet the specified requirements. The result message can vary according to the specific error encountered.

Check whether the request parameters, including the header parameters and body parameters, are correct and valid. For more information about the parameters of this API, see the Structure section.

INVALID_API

F

The called API is invalid or not active.

Check whether the correct API name is used when making the API call.

INVALID_SIGNATURE

F

Signature is invalid.

Check whether the public key, signed message, and signature algorithm are as expected.

ACCESS_DENIED

F

Access is denied

Contact overseas_support@service.alibaba.com to troubleshoot the issue.

REQUEST_TRAFFIC_EXCEED_LIMIT

F

The request traffic exceeds the limit.

Reduce the API calling frequency.

INVALID_ORDER_STATUS

F

The updated order status is invalid. For example, the order status does not conform to a valid order journey.

Specify the orderStatus parameter correctly. For more information about this parameter, refer to the Request parameter section.

UNKNOWN_EXCEPTION

U

An API calling is failed, which is caused by unknown reasons.

Recall the API.

Samples

Request

Update order status

To update order status, meet the following guidelines:

  • Specify the orderStatus parameters with valid values defined in the request parameters.
  • The update must conform to a valid order journey. For more information, refer to Order journey.

The following sample shows how to update the order status when the order is accepted by the merchant:

copy
{
  "requestId": "123",
  "requestOrderId": "pds_2109xxxxxxxxxxxx_2022xxxxxxxxxxxxxxx_1",
  "orderStatus": "ACCEPTED"
}

Update short order number

To update the short order number, specify the shortOrderNumber parameter according to the following sample:

copy
{
  "requestId": "123",
  "requestOrderId": "pds_2109xxxxxxxxxxxx_2022xxxxxxxxxxxxxxx_1",
  "shortOrderNumber": "0123",
  "orderStatus": "ACCEPTED"
}

Initiate a refund

To initiate a refund, meet the following guidelines:

  • Specify the refundAmount parameter to indicate the amount to be refunded to the buyer.
  • If the value of orderStatus is REJECTED (which means the merchant rejects the order), a full refund is automatically initiated. Do not request a refund in this scenario.
  • You can initiate multiple refunds, but the total refund amount, including failed refunds, cannot be greater than the payment amount (as specified by orderAmountDetail.paymentAmount parameter in the createOrder API).

The following sample shows how to initiate a refund and specify the refund amount:

copy
{
  "requestId": "123",
  "requestOrderId": "pds_2109xxxxxxxxxxxx_2022xxxxxxxxxxxxxxx_1",
  "refundAmount": {
    "currency":"SGD",
    "value":2000
  }
}

Update order ready time

To update the order ready time, specify the orderReadyTime parameter according to the following sample code:

copy
{
  "requestId": "123",
  "requestOrderId": "pds_2109xxxxxxxxxxxx_2022xxxxxxxxxxxxxxx_1",
  "orderReadyTime": "2023-07-31T22:00:00Z"
}

Update delivery status

To update the delivery status, meet the following guidelines:

  • Specify the deliveryStatus parameter only when orderStatus is set to READY or COMPLETED. Valid values for the deliveryStatus parameter vary depending on the order status:
    • When orderStatus is READY, valid values include ALLOCATED, ARRIVED, COLLECTED, and DELIVERED.
    • When orderStatus is COMPLETED, the only valid value is DELIVERED.
  • Do not request further updates to the deliveryStatus parameter once the final status of DELIVERED is set.

The following sample shows how to update the delivery status when the order is delivered to the buyer:

copy
{
  "requestId": "123",
  "requestOrderId": "pds_2109xxxxxxxxxxxx_2022xxxxxxxxxxxxxxx_1",
  "orderStatus": "COMPLETED",
  "deliveryStatus": "DELIVERED"
}

Response

The following sample shows that D-Store is notified of the order change successfully:

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