D-Store DocsD-Store DocsDOCS

createOrder

POST /v2/pos/createOrder

The createOrder API is called by D-Store to request the POS provider to create an order for the customer. Each time a customer places an order, this request is sent immediately with details of the products, order amount, customer, expected fulfillment time, etc.

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

requestOrderId

String

Yes

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

Maximum length: 255 characters

Note: This field is an idempotency key field. For the createOrder requests that are initiated with the same requestOrderId value, POS providers must return the same result. For details about API idempotency, see the Idempotency chapter.

posAccountId

String

Yes

The unique ID that is assigned by the POS provider to identify a merchant account.

Maximum length: 64 characters

posStoreId

String

Yes

The unique ID that is assigned by the POS provider to identify a store.

Maximum length: 255 characters

orderChannel

String

Yes

The channel where an order is placed. Valid value is:

  • DSTORE: The order is placed on D-Store.
  • GRABFOOD: The order is placed on GrabFood.
  • FOODPANDA: The order is placed on foodpanda.

channelOrderId

String

Yes

The unique ID that is assigned by the order channel to identify an order. The merchant can use this order ID for order communications with the order channel.

Maximum length: 255 characters

serviceType

String

Yes

The service type of the order. Valid values are:

  • PICKUP: The order is a pickup order.
  • DINEIN: The order is a dine-in order.
  • DELIVERY: The order is a delivery order.

expectFulfillmentTime

Datetime

Yes

The pickup or dine-in time the customer chooses. The value follows the ISO 8601 standard format.

customer

Customer

No

The customer who places the order. This parameter is not passed if D-Store is unable to retrieve the relevant data, such as when orderChannel is set to GRABFOOD and the order uses the delivery service provided by the order channel.

orderProducts

Array<OrderProduct>

Yes

The products in the order.

orderAmount

Amount

Yes

The total order amount, which is the sum of the amount specified in the orderAmountDetail.subTotalAmount, orderAmountDetail.tax, and orderAmountDetail.serviceCharge parameters.

orderAmountDetail

OrderAmountDetail

Yes

The amount details of the order.

promoDetails

Array<PromotionDetail>

No

The promotion details of the order.

deliveryDetail

DeliveryDetail

No

The delivery details of the order. This parameter is specified if the order is a delivery order.

memo

String

No

The customer's notes on the entire order.

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 keys:

  • shortOrderNumber: OptionalThe code that is generated by the order channel for the customer to collect the order. Its value is String.
  • isAutoAcceptanceRequired: OptionalWhether the order channel requires the merchant to automatically accept the order. This key is specified if orderChannel is set to GRABFOOD. Its value is Boolean with the following valid values:
    • TRUE: The order channel requires the merchant to automatically accept the order.
    • FALSE: The order channel does not require the merchant to automatically accept the order.

If not specified, its value is FALSE by default.

  • isTaxIncludedInProductPrice: OptionalWhether the product price includes the tax. This key is specified if the corresponding information is provided by the merchant. Its value is Boolean with the following valid values:
    • TRUE: The product price includes the tax.
    • FALSE: The product price does not include the tax.
  • acceptanceExpiryTime: OptionalThe expiration time that is set by the order channel for accepting the order. If the merchant fails to accept the order by this time, the order status is automatically set to CANCELLED. This key is specified if orderChannel is set to FOODPANDA. The value is in Datetime format following the ISO 8601 standard.
  • scheduleType: OptionalThe customer's preference for when the order needs to be fulfilled. This key is specified in most cases, but only required when the order involves a merchant-provided delivery service. The value is String with the following valid values:
    • IMMEDIATE: The order needs to be fulfilled as soon as possible.
    • SCHEDULED: The order needs to be fulfilled at a specific future time.

Note: If this parameter is not specified, you can infer the order's schedule type by the value of the expectFulfillmentTime parameter.

  • cutleryNumber: OptionalThe quantity of utensils required by the customer. This key is specified if the customer specifies a quantity. Its value is Integer.

Response parameters

Field

Data type

Required

Description

posOrderId

String

Yes

The unique ID that is assigned by the POS provider to identify an order.

Maximum length: 255 characters

shortOrderNumber

String

No

The code for the customer to collect the order.

Maximum length: 255 characters

autoAccept

Boolean

No

Whether the order is accepted automatically. Valid values are:

  • TRUE: The order is accepted automatically.
  • FALSE: The order requires manual acceptance by the merchant.

result

Result

Yes

The result of the order creation 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 creation succeeds, set the value of result.resultStatus to S and the value of result.resultCode to SUCCESS.
  • If the order creation 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 three sample codes for orders with different service types:

Pickup

The following sample shows an D-Store request to create a pickup order:

copy
{
  "expectFulfillmentTime": "2023-07-31T22:00:00Z",
  "memo": "testMemo",
  "orderAmount": {
    "currency": "SGD",
    "value": 2150
  },
  "orderAmountDetail": {
    "discountAmount": {
      "currency": "SGD",
      "value": 500
    },
    "paymentAmount": {
      "currency": "SGD",
      "value": 1650
    },
    "serviceCharge": {
      "currency": "SGD",
      "value": 1000
    },
    "subTotalAmount": {
      "currency": "SGD",
      "value": 1050
    },
    "tax": {
      "currency": "SGD",
      "value": 100
    },
    "taxDetail": {
      "subTotalTaxAmount": {
        "currency": "SGD",
        "value": 50
      },
      "serviceChargeTaxAmount": {
        "currency": "SGD",
        "value": 50
      }
    },
    "paymentDetails": [
      {
        "paymentMethod": "CASH",
        "paymentAmount": {
          "currency": "SGD",
          "value": 1650
        }
      }
    ]
  },
  "orderChannel": "DSTORE",
  "channelOrderId": "2023092812823534665",
  "orderProducts": [
    {
      "subOrderId":"2023092816475897667",
      "memo": "test",
      "posProductId": "pos_product_000",
      "price": {
        "currency": "SGD",
        "value": 1000
      },
      "quantity": 1,
      "subProducts": [
        {
          "posProductId": "pos_product_001",
          "quantity": 1,
          "price": {
            "currency": "SGD",
            "value": 0
          },
          "subProducts": [
            {
              "posProductId": "pos_product_002",
              "price": {
                "currency": "SGD",
                "value": 50
              },
              "quantity": 1
            }
          ]
        }
      ]
    }
  ],
  "serviceType": "PICKUP",
  "posAccountId": "testPosId0000_2102020156171449",
  "posStoreId": "pos_store_01",
  "promoDetails": [
    {
      "discountAmount": {
        "currency": "SGD",
        "value": 500
      },
      "promoId": "testPromoId",
      "promoInvestorType": "MERCHANT",
      "promoName": "testPromoName",
      "promoType": "COUPON"
    }
  ],
  "requestOrderId": "202307319208000099341448",
  "extendInfo": {
    "shortOrderNumber": "901",
    "isAutoAcceptanceRequired": false,
    "isTaxIncludedInProductPrice": true
  }
}

Dine-in

The following sample shows an D-Store request to create a dine-in order:

copy
{
  "customer": {
    "areaCode": "86",
    "buyerName": "John Doe",
    "email": "email@example.com",
    "mobileNo": "182******81"
  },
  "expectFulfillmentTime": "2023-07-31T22:00:00Z",
  "memo": "testMemo",
  "orderAmount": {
    "currency": "SGD",
    "value": 2150
  },
  "orderAmountDetail": {
    "discountAmount": {
      "currency": "SGD",
      "value": 500
    },
    "paymentAmount": {
      "currency": "SGD",
      "value": 1650
    },
    "serviceCharge": {
      "currency": "SGD",
      "value": 1000
    },
    "subTotalAmount": {
      "currency": "SGD",
      "value": 1050
    },
    "takeawayAmount": {
      "currency": "SGD",
      "value": 0
    },
    "tax": {
      "currency": "SGD",
      "value": 100
    },
    "taxDetail": {
      "subTotalTaxAmount": {
        "currency": "SGD",
        "value": 50
      },
      "serviceChargeTaxAmount": {
        "currency": "SGD",
        "value": 50
      },
      "takeawayTaxAmount": {
        "currency": "SGD",
        "value": 0
      }
    },
    "paymentDetails": [
      {
        "paymentMethod": "CASH",
        "paymentAmount": {
          "currency": "SGD",
          "value": 1650
        }
      }
    ]
  },
  "orderChannel": "DSTORE",
  "channelOrderId": "2023092812823534665",
  "orderProducts": [
    {
      "subOrderId":"2023092816475897667",
      "memo": "test",
      "posProductId": "pos_product_000",
      "price": {
        "currency": "SGD",
        "value": 1000
      },
      "quantity": 1,
      "subProducts": [
        {
          "posProductId": "pos_product_001",
          "quantity": 1,
          "price": {
            "currency": "SGD",
            "value": 0
          },
          "subProducts": [
            {
              "posProductId": "pos_product_002",
              "price": {
                "currency": "SGD",
                "value": 50
              },
              "quantity": 1
            }
          ]
        }
      ]
    }
  ],
  "serviceType": "DINEIN",
  "posAccountId": "testPosId0000_2102020156171449",
  "posStoreId": "pos_store_01",
  "promoDetails": [
    {
      "discountAmount": {
        "currency": "SGD",
        "value": 500
      },
      "promoId": "testPromoId",
      "promoInvestorType": "MERCHANT",
      "promoName": "testPromoName",
      "promoType": "COUPON"
    }
  ],
  "requestOrderId": "202307319208000099341448",
  "extendInfo": {
    "shortOrderNumber": "901",
    "isAutoAcceptanceRequired": false,
    "isTaxIncludedInProductPrice": true
  }
}

Delivery

The following sample shows an D-Store request to create a delivery order:

copy
{
  "expectFulfillmentTime": "2023-07-31T22:00:00Z",
  "memo": "testMemo",
  "orderAmount": {
    "currency": "SGD",
    "value": 2150
  },
  "orderAmountDetail": {
    "discountAmount": {
      "currency": "SGD",
      "value": 500
    },
    "paymentAmount": {
      "currency": "SGD",
      "value": 1650
    },
    "deliveryFee": {
      "currency": "SGD",
      "value": 1000
    },
    "subTotalAmount": {
      "currency": "SGD",
      "value": 1050
    },
    "tax": {
      "currency": "SGD",
      "value": 100
    },
    "taxDetail": {
      "subTotalTaxAmount": {
        "currency": "SGD",
        "value": 100
      }
    },
    "paymentDetails": [
      {
        "paymentMethod": "CASH",
        "paymentAmount": {
          "currency": "SGD",
          "value": 1650
        }
      }
    ]
  },
  "orderChannel": "DSTORE",
  "channelOrderId": "2023092812823534665",
  "orderProducts": [
    {
      "subOrderId":"202309281647897669",
      "memo": "test",
      "posProductId": "pos_product_000",
      "price": {
        "currency": "SGD",
        "value": 1000
      },
      "quantity": 1,
      "subProducts": [
        {
          "posProductId": "pos_product_001",
          "quantity": 1,
          "price": {
            "currency": "SGD",
            "value": 0
          },
          "subProducts": [
            {
              "posProductId": "pos_product_002",
              "price": {
                "currency": "SGD",
                "value": 50
              },
              "quantity": 1
            }
          ]
        }
      ]
    }
  ],
  "serviceType": "DELIVERY",
  "posAccountId": "testPosId0000_2102020156171449",
  "posStoreId": "pos_store_01",
  "promoDetails": [
    {
      "discountAmount": {
        "currency": "SGD",
        "value": 500
      },
      "promoId": "testPromoId",
      "promoInvestorType": "MERCHANT",
      "promoName": "testPromoName",
      "promoType": "COUPON"
    }
  ],
  "customer": {
    "areaCode": "86",
    "buyerName": "John Doe",
    "email": "email@example.com",
    "mobileNo": "182******81"
  },
  "deliveryDetail": {
    "deliveryProvider": "MERCHANT",
    "addressInfo": {
      "addressDetail": "******, Shanghai, China, 200120",
      "blockNo": "1",
      "floorNo": "1",
      "unitNo": "1",
      "postCode": "200120",
      "latitude": "31.240609",
      "longitude": "121.499671",
      "additionalInformation": "additional information"
    },
    "expectedDeliveryTimeStart": "2023-07-31T21:00:00Z",
    "expectedDeliveryTimeEnd": "2023-07-31T21:00:00Z"
  },
  "requestOrderId": "202307319208000099341448",
  "extendInfo": {
    "shortOrderNumber": "901",
    "isAutoAcceptanceRequired": false,
    "isTaxIncludedInProductPrice": true,
    "acceptanceExpiryTime": "2023-08-01T20:00:00Z",
    "cutleryNumber":1
  }
}

Response

The following sample shows how you can return a response when the order is created successfully:

copy
{
  "posOrderId": "2023063000010002",
  "shortOrderNumber": "0123",
  "autoAccept": false,
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  }
}