pushOrderChange

2025-04-03 09:56

POST /v2/pos/pushOrderChange

The pushOrderChange API is called by D-Store to notify the POS provider of order changes from the order channel. These changes can include:

Order status updates.
Delivery status updates for orders that use delivery services provided by the order channel.
Order modifications exclusive to GrabFood orders, with the following restrictions:

The total number of the top-level products in the order cannot exceed the original quantity.
The total order amount cannot exceed the original total. If the total order amount is reduced, a refund will be automatically processed.

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 an order update request. Maximum length: 255 characters Note: This field is an idempotency key field. For the pushOrderChange requests that are initiated with the same requestId value, POS providers 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
orderStatus	String	No	The latest order status. This parameter is specified when the order status changes. Valid values are: `COMPLETED`: The order is completed. For example, in the case of a delivery order, it is completed when the delivery is fulfilled. `CANCELLED`: The order is canceled by the buyer, the merchant, or the delivery driver. Note that in certain circumstances, such as with orders from Foodpanda, the order channel can update orderStatus from `COMPLETED` to `CANCELLED`. `ORDER_FAIL`: The order failed, which might be caused by a failed delivery.
deliveryStatus	String	No	The latest delivery status of the order. This parameter is specified when the order channel provides the 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. Notes: This parameter is specified only when orderStatus is set to `READY` or `COMPLETED`. Valid values for this 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`. No further updates are made to this parameter once the final status of `DELIVERED` is set.
updatedOrderProducts	Array<UpdatedOrderProduct>	No	The products that require updating in an order. This parameter is specified if order modifications are made.
refundInfo	RefundInfo	No	The information of the refund to the buyer. This parameter is specified if order modifications are made and the total order amount decreases.
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: The reason why the order is unable to be fulfilled. Its value is String. This key is specified when orderStatus is set to `CANCELLED` or `ORDER_FAIL`.

Response parameters

Field	Data type	Required	Description
result	Result	Yes	The result of the order status update request.

More information

How to return the result

The POS provider needs to return the result (specified in the result parameter) by following these instructions:

If the order status update request succeeds, set the value of result.resultStatus to S and the value of result.resultCode to SUCCESS.
If the order status update request fails, set the value of result.resultStatus to F and specify the value of result.resultCode according to the failure reason.
If system or network issues exist, set the value of result.resultStatus to U and the value of result.resultCode to UNKNOWN_EXCEPTION, and D-Store will retry the request.

For more information about how to define your result codes, see the Result codes section.

Result codes

Result code	Result status	Result message
SUCCESS	S	success
PROCESS_FAIL	F	A general business failure occurred. Do not retry.
PARAM_ILLEGAL	F	Parameter names or values do not meet the specified requirements. The result message can vary according to the specific error encountered.
INVALID_API	F	The called API is invalid or not active.
INVALID_SIGNATURE	F	Signature is invalid.
ACCESS_DENIED	F	Access is denied
REQUEST_TRAFFIC_EXCEED_LIMIT	F	The request traffic exceeds the limit.
UNKNOWN_EXCEPTION	U	An API calling is failed, which is caused by unknown reasons.

Samples

Request

Refer to the following samples for how D-Store constructs requests for the following scenarios:

Order status update
Delivery status update
Order modifications

Order status update

The following sample shows that D-Store requests to notify the latest order status:

copy
{
    "requestOrderId": "202307319208000099341448",
    "requestId": "12466547567",
    "orderStatus": "CANCELLED",
    "extendInfo": {
        "failureReason": "user canceled"
    }
}

Delivery status update

The following sample shows that D-Store requests to notify the latest delivery status:

copy
{
    "requestOrderId": "202307319208000099341448",
    "requestId": "12466547567",
  "orderStatus": "COMPLETED",
    "deliveryStatus": "DELIVERED"
}

Order modifications

This section provides sample codes for the following order modifications:

Remove products
Change products
Adjust product prices
Adjust product quantities
Update subproducts

Each modification is made to the following order:

copy
{
    "expectFulfillmentTime": "2023-07-31T22:00:00Z",
    "memo": "testMemo",
    "orderAmount": {
        "currency": "SGD",
        "value": 3000
    },
    "orderAmountDetail": {
        "paymentAmount": {
            "currency": "SGD",
            "value": 3000
        },
        "serviceCharge": {
            "currency": "SGD",
            "value": 0
        },
        "subTotalAmount": {
            "currency": "SGD",
            "value": 3000
        },
        "tax": {
            "currency": "SGD",
            "value": 300
        },
        "taxDetail": {
            "subTotalTaxAmount": {
                "currency": "SGD",
                "value": 50
            },
            "serviceChargeTaxAmount": {
                "currency": "SGD",
                "value": 50
            }
        },
        "paymentDetails": [
            {
                "paymentMethod": "CASH",
                "paymentAmount": {
                    "currency": "SGD",
                    "value": 1650
                }
            }
        ]
    },
    "orderChannel": "DSTORE",
    "channelOrderId": "2023092812823534666",
    "orderProducts": [
        {
            "subOrderId": "2023092816475897668",
            "memo": "test",
            "posProductId": "pos_product_001",
            "price": {
                "currency": "SGD",
                "value": 1000
            },
            "quantity": 1,
            "subProducts": [
                {
                    "posProductId": "pos_sub_product_001",
                    "quantity": 1,
                    "price": {
                        "currency": "SGD",
                        "value": 0
                    }
                }
            ]
        },
        {
            "subOrderId": "2023092816475889667",
            "memo": "test",
            "posProductId": "pos_product_002",
            "price": {
                "currency": "SGD",
                "value": 1000
            },
            "quantity": 2
        }
    ],
    "serviceType": "PICKUP",
    "posAccountId": "testPosId0000_2102020156171449",
    "posStoreId": "pos_store_01",
    "requestOrderId": "202307319208000099341448",
    "extendInfo": {
        "shortOrderNumber": "901",
        "isAutoAcceptanceRequired": false,
        "isTaxIncludedInProductPrice": true
    }
}

As shown in the sample code, the original order contains:

One unit of pos_product_001 priced at 10 SGD
Two units of pos_product_002, each priced at 10 SGD.

The total order amount is 30 SGD.

Remove products

The following sample code shows an order modification that involves the removal of the product pos_product_001 and a refund for its price of 10 SGD:

copy
{
  "requestId": "123",
  "requestOrderId": "pds_2109xxxxxxxxxxxx_2022xxxxxxxxxxxxxxx_1",
  "updatedOrderProducts": [
    {
      "subOrderId": "2023092816475897668",
      "posProductId": "pos_product_001",
      "updateType":"REMOVE"
    }
  ],
  "refundInfo":{
    "requestRefundId":"1234587",
    "refundStatus":"REFUNDED",
    "refundAmount":{
      "currency": "SGD",
      "value": 1000
    }
  }
}

Change products

The following sample shows an order modification that involves replacing the productpos_product_001 (priced at 10 SGD) with the product pos_product_003 (priced at 5 SGD). This replacement results in an automatic refund of 5 SGD due to the price difference.

copy
{
  "requestId": "123",
  "requestOrderId": "pds_2109xxxxxxxxxxxx_2022xxxxxxxxxxxxxxx_1",
  "updatedOrderProducts": [
    {
      "subOrderId": "2023092816475897668",
      "posProductId": "pos_product_001",
      "updateType":"REMOVE"
    },
    {
      "subOrderId": "2023092816475890660",
      "posProductId": "pos_product_003",
      "updateType":"ADD",
      "price": {
        "currency": "SGD",
        "value": 500
      },
      "quantity": 1,
      "subProducts": {
        "posProductId": "pos_product_modifer_001",
        "price": {
          "currency": "SGD",
          "value": 0
        },
        "quantity": 1
      }
    }
  ],
  "refundInfo":{
    "requestRefundId":"1234587",
    "refundStatus":"REFUNDED",
    "refundAmount":{
      "currency": "SGD",
      "value": 500
    }
  }
}

Adjust product prices

The following sample code shows an order modification that involves the price reduction of the product pos_product_001 from 10 SGD to 8 SGD, along with an accompanying refund of 2 SGD:

copy
{
  "requestId": "123",
  "requestOrderId": "pds_2109xxxxxxxxxxxx_2022xxxxxxxxxxxxxxx_1",
  "updatedOrderProducts": [
    {
      "subOrderId": "2023092816475897668",
      "posProductId": "pos_product_001",
      "updateType":"UPDATE",
      "price": {
        "currency": "SGD",
        "value": 800
      },
      "quantity": 1,
      "subProducts": [
        {
          "posProductId": "pos_sub_product_001",
          "quantity": 1,
          "price": {
            "currency": "SGD",
            "value": 0
          }
        }
      ]
    }
  ],
   "refundInfo":{
    "requestRefundId":"1234587",
    "refundStatus":"REFUNDED",
    "refundAmount":{
      "currency": "SGD",
      "value": 200
    }
  }
}

Adjust product quantities

The following sample code shows an order modification that involves the quantity reduction of the product pos_product_002 from two units to one unit, along with an accompanying refund of 10 SGD:

copy
{
  "requestId": "123",
  "requestOrderId": "pds_2109xxxxxxxxxxxx_2022xxxxxxxxxxxxxxx_1",
  "updatedOrderProducts": [
    {
      "subOrderId":"2023092816475889667",
      "posProductId": "pos_product_002",
      "updateType":"UPDATE",
      "price": {
        "currency": "SGD",
        "value": 1000
      },
      "quantity": 1
    }
  ],
  "refundInfo":{
    "requestRefundId":"1234587",
    "refundStatus":"REFUNDED",
    "refundAmount":{
      "currency": "SGD",
      "value": 1000
    }
  }
}

Update subproducts

The following sample code shows an order modification that involves the change of the subproduct of the product pos_product_001 from pos_sub_product_001 (free) to pos_sub_product_002 (free):

copy
{
  "requestId": "123",
  "requestOrderId": "pds_2109xxxxxxxxxxxx_2022xxxxxxxxxxxxxxx_1",
  "updatedOrderProducts": [
    {
      "subOrderId": "2023092816475897668",
      "posProductId": "pos_product_001",
      "updateType":"UPDATE",
      "price": {
        "currency": "SGD",
        "value": 1000
      },
      "quantity": 1,
      "subProducts": [
        {
          "posProductId": "pos_sub_product_002",
          "quantity": 1,
          "price": {
            "currency": "SGD",
            "value": 0
          }
        }
      ]
    }
  ]
}

Response

The following sample shows how you can return a response when the order status update request is successful:

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