inquireOrderDetail

POST /v2/pds/order/inquireOrderDetail

With this API call, D-store Platform can request the SaaS provider or ISV to inquire about the order detail (for example, order status) by requestOrderId and return the result.

The message structure of this API is defined by D-store Platform. Follow the specifications below when the SaaS provider or ISV develops this API.

Note: This API is very important for ordering interaction. If the notification is lost or delayed when notifying the merchant to accept orders, D-store Platform can call this API to query the order status to ensure a normal transaction.

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

requestOrderId

String

Yes

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

  • Maximum length: 255 characters

"pds_2109220007538584_2022050900338308584_1"

Response parameters

Field

Data type

Required

Description

result

Result

Yes

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

-

orderId

String

Yes

Indicates the unique ID assigned by the SaaS provider or ISV to identify the order.

  • Maximum length: 255 characters

"1437327"

orderStatus

String

Yes

Indicates the status of the order.

Valid values are:

  • When the value of orderType is PICKUP:
    • SAAS_ORDER_FAIL: The order creation is failed.
    • SAAS_ORDER_SUCCESS: The order creation is successful.
    • ACCEPTED: The merchant accepts the order.
    • REJECTED: The merchant rejects the order.
    • CONFIRM_TIMEOUT: The merchant is taking too long to accept 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 DELIVERY:
    • SAAS_ORDER_FAIL: The order creation is failed.
    • SAAS_ORDER_SUCCESS: The order creation is successful.
    • ACCEPTED: The merchant accepts the order.
    • REJECTED: The merchant rejects the order.
    • CONFIRM_TIMEOUT: The merchant is taking too long to accept 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.
  • When the value of orderType is DINEIN:
    • SAAS_ORDER_FAIL: Indicates that the creation for the whole order or the subordinate order is failed.
    • SAAS_ORDER_SUCCESS: Indicates that the creation for the whole order or the subordinate order is successful.
    • 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.
    • CONFIRM_TIMEOUT: Indicates that the merchant is taking too long to accept 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 one of the following two types of order:
      • The whole order
      • The main order, which means all of its subordinate orders are completed

"REJECTED"

extendInfo

Map<String,String>

No

Indicates the extended information about this API.

  • Maximum length: 2048 characters

Take the following examples:

  • Return the rebatedAssets parameter to specify 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.
  • Return 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."}

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 inquiry is successful.

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

U

The status of the inquiry 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 inquiry is failed.

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:

Samples

Request

copy
{
    "requestOrderId": "pds_2109220007538584_2022050900338308584_1"
}

Response

The orderId, orderStatus, and result parameters must be returned.

See the following example:

copy
{
    "orderId": "1437327",
    "orderStatus": "REJECTED",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success",
        "resultStatus": "S"
    },
    "extendInfo":"{\"rejectOrderReason\":\"The store is closed.\"}"
}