Data dictionary

2023-04-28 21:00

OrderItem

Field	Data type	Required	Description	Example
storeId	String	Yes	Indicates the unique ID assigned by the SaaS provider or ISV to identify a store, such as a hawker or a restaurant. Maximum length: 255 characters	-
itemId	String	Yes	Indicates the unique ID assigned by the SaaS provider or ISV to identify an item. Maximum length: 255 characters	"12334545"
categoryId	String	No	Indicates the ID assigned by the SaaS provider or ISV to identify the category to which the item belongs. Specify this parameter if the item is a single item, for which the value of store.menus.categories.items.saleType parameter is `SINGLE` in the syncStore API. Maximum length: 255 characters	"30000000ca12"
requestSubOrderId	String	No	Indicates the unique ID assigned by our server to identify an item in the order. Maximum length: 255 characters Note: For the createOrder API: This field is required in the createOrder API. This field is used in the notifyOrderChange API and the upcoming refund API to identify an item in the order. So we recommend you save requestSubOrderId for later use. For the notifyOrderChange API: This field is required when the SaaS provider or ISV calls this API to update one or more items in the order. For a sample request, see Update item. This field will be returned when the SaaS provider or ISV calls this API to add one or more items to the order. We recommend you save requestSubOrderId for later use when updating the item. For a sample response, see Add item.	"2022050400311864775"
notAvailableOption	String	No	Indicates the option for the user to choose when the item is not available. For example, remove the item from the order or cancel the entire order.	-
modifierGroupDetails	String	No	Indicates the user's choices of the modifier group. Note: This parameter is in JSON format containing an Array<ModifierGroupDetail> object (Maximum size: 20 elements).	"[{\"groupId\":\"MG_fd374195e_1abe\",\"itemDetail\":[{\"itemId\":\"M_fe5f-4c34-a2ec-b4261bf9ce06\",\"priceInfo\":{\"currency\":\"SGD\",\"saleAmount\":9},\"quantity\":1,\"requestSubOrderId\":\"\",\"storeId\":\"fd37af44-90ed-48a1-84ba-****\"}]}]"
skuId	String	No	Indicates the unique ID assigned by the SaaS provider or ISV to identify the SKU that the user selects. Maximum length: 255 characters	"2423423423"
priceInfo	PriceInfo	Yes	Indicates the price information of the item. Note: This is the price for one item, NOT including the add-on item. We recommend you verify whether the item price is accurate when creating an order.	-
quantity	Integer	Yes	Indicates the quantity of the item. Value range: 0-unlimited	1
memo	String	No	Indicates the special notes left by the user regarding the item. Maximum length: 2048 characters	"No ice, please"

ModifierGroupDetail

Field

Data type

Required

Description

Example

groupId

String

Yes

Indicates the ID assigned by the SaaS provider or ISV to identify a modifier group.

Maximum length: 255 characters

"123,456"

itemDetail

Array<OrderItem>

Yes

Indicates the user's choices of the modifier group.

Maximum size: 20 elements

[{\"itemId\":\"M_fe5f-4c34-a2ec-b4261bf9ce06\",\"priceInfo\":{\"currency\":\"SGD\",\"saleAmount\":9},\"quantity\":1,\"requestSubOrderId\":\"\",\"storeId\":\"fd37af44-90ed-48a1-84ba-****\"}]

DeliveryDetail

For createOrder

Field	Data type	Required	Description	Example
addressInfo	AddressInfo	Yes	Indicates the address details of the user.	-
expectedDeliveryTimeStart	Datetime	Yes	Indicates the earliest time that the user expects to receive the order. The value follows the ISO 8601 standard format.	"2022-04-27T12:01:01+08:30"
expectedDeliveryTimeEnd	Datetime	Yes	Indicates the latest time that the user expects to receive the order. The value follows the ISO 8601 standard format.	"2022-04-27T12:01:01+08:30"
memoToDeliverymen	String	No	Indicates the user's special instructions for delivery. Maximum length: 2048 characters	-

For notifyOrderChange

Field	Data type	Required	Description	Example
expectedDeliveryTimeStart	Datetime	No	Indicates the earliest time that the user expects to receive the order, which is modified after consultation between the user and the merchant. The value follows the ISO 8601 standard format. Note: This field is applicable when the value of orderStatus is `PREPARING`, `READY`, `SHIPPING`, or `NEARBY`, which means when the order is in the above statuses, you can pass this field to change the expected earliest delivery time of the order.	"2022-04-27T12:01:01+08:30"
expectedDeliveryTimeEnd	Datetime	No	Indicates the latest time that the user expects to receive the order, which is modified after consultation between the user and the merchant. The value follows the ISO 8601 standard format. Note: This field is applicable when the value of orderStatus is `PREPARING`, `READY`, `SHIPPING`, or `NEARBY`, which means when the order is in the above statuses, you can pass this field to change the expected latest delivery time of the order.	"2022-04-27T12:01:01+08:30"
estimatedDeliveryTimeStart	Datetime	No	Indicates the earliest time of arrival estimated by the delivery person. The value follows the ISO 8601 standard format. Note: This field is applicable when the value of orderStatus is `PREPARING`, `READY`, `SHIPPING`, or `NEARBY`, which means when the order is in the above statuses, you can pass this field to provide the estimated earliest time of arrival.	"2022-04-27T12:01:01+08:30"
estimatedDeliveryTimeEnd	Datetime	No	Indicates the latest time of arrival estimated by the delivery person. The value follows the ISO 8601 standard format. Note: This field is applicable when the value of orderStatus is `PREPARING`, `READY`, `SHIPPING`, or `NEARBY`, which means when the order is in the above statuses, you can pass this field to provide the estimated latest time of arrival.	"2022-04-27T12:01:01+08:30"
delayReason	String	No	Indicates the reason why the order may be delayed. Valid values are: `WEATHER`: The order may be delayed due to bad weather. `TRAFFIC`: The order may be delayed due to traffic challenges. Note: This field is applicable when the value of orderStatus is `PREPARING`, `READY`, `SHIPPING`, or `NEARBY`, which means when the order is in the above statuses, you can pass this field to provide possible reasons for the delay.	"WEATHER"

AddressInfo

Field	Data type	Required	Description	Example
addressDetail	String	Yes	Indicates the user's address. Maximum length: 255 characters	"Road X, Geyland, Singapore"
postCode	String	No	Indicates the postcode of the user's address. You can use this parameter to calculate delivery distance and time. Maximum length: 6 characters Notes: This parameter is specified if D-store Platform obtains it. This parameter needs to be specified by D-store Platform if latitude and longitude are not specified.	"311023"
blockNo	String	No	Indicates the block number. Maximum length: 255 characters	"1212"
floorNo	String	No	Indicates the floor number. Maximum length: 255 characters	"6"
unitNo	String	No	Indicates the unit number. Maximum length: 255 characters	"1"
additionalInformation	String	No	Indicates the additional address information. Maximum length: 255 characters	-
latitude	String	No	Indicates the latitude of the user's address. You can use this parameter and longitude to calculate delivery distance and time. Value range: -180.000000-180.000000 Notes: This parameter is specified if D-store Platform obtains it or longitude is specified. This parameter needs to be specified by D-store Platform if postCode is not specified.	"11.3548791"
longitude	String	No	Indicates the longitude of the user's address. You can use this parameter and latitude to calculate delivery distance and time. Value range: -90.000000-90.000000 Notes: This parameter is specified if D-store Platform obtains it or latitude is specified. This parameter needs to be specified by D-store Platform if postCode is not specified.	"13.8308643"

OrderAmountDetail

Field	Data type	Required	Description	Example
takeawayFeeAmount	Integer	Yes	Indicates the takeaway charge, which is in the currency's smallest unit. For example, `9999` means 99.99 in SGD. Value range: 0-2147483647	10
itemFeeAmount	Integer	Yes	Indicates the cost of the items ordered, which is in the currency's smallest unit. For example, `9999` means 99.99 in SGD. Value range: 0-2147483647 Note: To learn how itemFeeAmount is calculated, see itemFeeAmount.	10
smallOrderFeeAmount	Integer	Yes	Indicates the fee to be charged on orders less than the minimum order amount. This field is in the currency's smallest unit. For example, `9999` means 99.99 in SGD. Value range: 0-2147483647 Note: To learn how smallOrderFeeAmount is calculated, see smallOrderFeeAmount.	10
deliveryFeeAmount	Integer	Yes	Indicates the delivery fee, which is in the currency's smallest unit. For example, `9999` means 99.99 in SGD. Value range: 0-2147483647	10
convenienceFeeAmount	Integer	Yes	Indicates the convenience fee, which is in the currency's smallest unit. For example, `9999` means 99.99 in SGD. Value range: 0-2147483647	10

PromoDetail

Property	Data type	Required	Description	Example
promoId	String	Yes	Indicates the unique ID assigned by our server to identify a promotion. Maximum length: 64 characters	-
promoType	String	Yes	Indicates the type of promotion. Valid values are: `INSTANT_DISCOUNT`: An instant discount on items. `COUPON`: A coupon to be applied that offers a discount on items.	"COUPON"
promoName	String	No	Indicates the name of the promotion. Maximum length: 256 characters	-
discountAmount	Amount	Yes	Indicates the amount that is reduced.	-
extendInfo	String	No	Indicates the extended information about the promotion. Maximum length: 1024 characters Characters not allowed: special characters such as @ # ? Note: Pass the promoInvestorType parameter to specify the investor who funds the marketing promotions. Valid values are: `MERCHANT`: The merchant funds the marketing promotions. `PLATFORM`: Our server funds the marketing promotions. `SUPER_APP`: The super app funds the marketing promotions.	"{\"promoInvestorType\":\"PLATFORM\"}"

PriceInfo

Field	Data type	Required	Description	Example
originAmount	Integer	No	Indicates the original sale price, which is in the currency's smallest unit. For example, `10000` means 100.00 in SGD. Value range: 0-2147483647 Note: This field is used for marketing activities. The value of originAmount is expected to be greater than that of saleAmount. In this scenario, both originAmount and saleAmount is displayed to users, as well as the discount. If the value of originAmount is lower than or equal to that of saleAmount, only saleAmount is displayed to users.	10000
saleAmount	Integer	Yes	Indicates the actual sale price, which is in the currency's smallest unit. For example, `9999` means 99.99 in SGD. Value range: 0-2147483647	9999
currency	String	Yes	The 3-character currency code that follows ISO-4217. For example, SGD, USD, or CNY.	"SGD"

Amount (1)

Note: This data model is used in the following parameters:

The createOrder API

promoDetails.discountAmount
extendInfo.paymentMethodAmountDetails

The notifyOrderChange API

extendInfo.rebatedAssets

The inquireOrderDetail API

extendInfo.rebatedAssets

The consult API

extendInfo.merchantPromotions.discountAmount

For other parameters using the Amount object, refer to Amount (2).

Field

Data type

Required

Description

Example

currency

String

Yes

Indicates the 3-letter currency code that follows the ISO 4217 standard. For example, SGD, USD, CNY.

"SGD"

amountValue

Integer

Yes

Indicates the amount to charge, which is in the smallest currency unit. For example, 9999 means 99.99 in SGD.

Value range: 0-2147483647

9999

Amount (2)

Field

Data type

Required

Description

Example

value

Integer

Yes

Indicates the value of the amount which is in the currency's smallest unit. For example, 10000 means 100.00 in SGD.

Value range: 0-2147483647

10000

currency

String

Yes

Indicates the 3-character currency code that follows ISO-4217. For example, SGD, USD, or CNY.

Maximum length: 3 characters

"SGD"

Result

Field	Data type	Required	Description	Example
resultStatus	String	Yes	Indicates the result status. Valid values are: `S`: Successful `F`: Failed `U`: Unknown `A`: Accepted, not yet succeeded, but can proceed with some actions.	"S"
resultCode	String	No	Indicates the result code. Maximum length: 64 characters.	-
resultMessage	String	No	Indicates the result messages that describe the result code in detail. Maximum length: 256 characters.	-

OrderStoreSnapshot

Field	Data type	Required	Description	Example
id	String	No	Indicates the unique ID assigned by D-store Platform to identify a store. Maximum length: 255 characters	"2102010113769***"
image	Array<String>	No	Indicates the image URLs of the store. Maximum size: 5 elements Element maximum length: 255 characters	-
title	String	No	Indicates the title of the store. Maximum length: 255 characters	"Sample *** @ Braddell"
tpId	String	No	Indicates the unique ID assigned by the SaaS provider or ISV to identify a store. Maximum length: 255 characters	"fd37af44-90ed-48a***********"
timeZone	String	No	Indicates the time zone where the store is located.	"GMT+08:00"
address	String	No	Indicates the address of the store. Maximum length: 255 characters	-
mccCodeType	String	No	Indicates the merchant category code, for example, `"5814"`.	-
contactPhoneNos	Array<String>	No	Indicates the contact numbers of the store. Maximum size: 3 elements Element maximum length: 64 characters	-
locationDomain	LocationDomain	No	Indicates the geographical location of the store.	{\"latitude\":\"1.33**\",\"longitude\":\"103.858**\"}

LocationDomain

Field	Data type	Required	Description	Example
latitude	String	No	Indicates the latitude of the location. Value range: -180.000000 - 180.000000	"40.659569"
longitude	String	No	Indicates the longitude of the location. Value range: -90.000000 - 90.000000	"-73.851524
postCode	String	No	Indicates the postcode of the location. Maximum length: 32 characters Only alphanumeric characters are allowed.	"310000"

UserInfo

Field	Data type	Required	Description	Example
userName	String	No	Indicates the user's name. Maximum length: 64 characters	"John Doe"
userPhone	String	No	Indicates the user's phone number. Maximum length: 64 characters The value follows the [+][country code][area code without leading 0][local phone number] format, for example, `+658812****`.	"+86156****721"
userEmail	String	No	Indicates the user's email address. Maximum length: 64 characters	"email@example.com"
userAddress	String	No	Indicates the user's address. Maximum length: 255 characters Note: This parameter is required when the value of orderType is `DELIVERY`.	-
userLatitude	String	No	Indicates the latitude of the user's location. You can use this parameter and userLongitude to calculate delivery distance and time. Value range: -180.000000-180.000000 Notes: This parameter is specified if D-store Platform obtains it or userLongitude is specified. This parameter needs to be specified by D-store Platform if userPostCode is not specified.	"11.3548791"
userLongitude	String	No	Indicates the longitude of the user's location. You can use this parameter and userLatitude to calculate delivery distance and time. Value range: -90.000000-90.000000 Notes: This parameter is specified if D-store Platform obtains it or userLatitude is specified. This parameter needs to be specified by D-store Platform if userPostCode is not specified.	"13.8308643"
userPostCode	String	No	Indicates the postcode of the user's location. You can use this parameter to calculate delivery distance and time. Maximum length: 32 characters Only alphanumeric characters are allowed. Notes: This parameter is specified if D-store Platform obtains it. This parameter needs to be specified by D-store Platform if userLatitude and userLongitude are not specified.	"574408"
cardNo	String	No	Indicates the unique card number generated by the SaaS provider or ISV to identify a card. Maximum length: 64 characters. Characters not allowed: special characters such as @ # ?	-

SellerInfo

Field	Data type	Required	Description	Example
sellerStoreId	String	Yes	Indicates the unique ID assigned by the SaaS provider or ISV to identify a merchant's store. Maximum length: 255 characters	"2022120611151100021000620064****"
sellerName	String	Yes	Indicates the merchant's name. Maximum length: 255 characters	"1206_01store"
sellerPhone	String	No	Indicates the merchant's phone number. Maximum length: 64 characters The value follows the [+][country code][area code without leading 0][local phone number] format, for example, `+658812****`.	"+86183****678"
sellerAddress	String	No	Indicates the merchant's address. Maximum length: 255 characters	-
sellerLatitude	String	No	Indicates the latitude of the merchant's location. Value range: -180.000000 - 180.000000 Note: If sellerLongitude is provided, then sellerLatitude must be provided. Either sellerLatitude and sellerLongitude or sellerPostCode must be provided.	"1.3548791"
sellerLongitude	String	No	Indicates the longitude of the merchant's location. Value range: -90.000000 - 90.000000 Note: If sellerLatitude is provided, then sellerLongitude must be provided. Either sellerLatitude and sellerLongitude or sellerPostCode must be provided.	"103.8308643"
sellerPostCode	String	No	Indicates the postcode of the merchant's location. Maximum length: 32 characters Only alphanumeric characters are allowed. Note: Either sellerLatitude and sellerLongitude or sellerPostCode must be provided.	"574408"

ConsultOrderAmountDetail

Field	Data type	Required	Description	Example
totalAmount	Amount	Yes	Indicates the total order amount for the user to pay.	{ "currency": "SGD", "value": 1910 }
itemFeeAmount	Amount	Yes	Indicates the cost of the items ordered.	-
takeawayFeeAmount	Amount	No	Indicates the takeaway charge.	-
deliveryFeeAmount	Amount	No	Indicates the delivery fee.	-
taxAmount	Amount	No	Indicates the sales tax on the order.	-
taxSeparatelyCharged	Boolean	No	Specifies whether the sales tax is separately stated in the order total. If the value is `true`, the tax is separately stated in the order total, otherwise, the sales tax is included in the price of items. Note: The value is `null` by default, which means the tax is included in the price of items.	true
serviceChargeAmount	Amount	No	Indicates the service charge.	-
handlingFeeAmount	Amount	No	Indicates the handling fee.	-
tipsAmount	Amount	No	Indicates the tip amount.	-
roundAmount	Amount	No	Indicates the rounded amount.	-
smallOrderFeeAmount	Amount	No	Indicates the fee to be charged on orders less than the minimum order amount.	-
extendInfo	Map<String,String>	No	Indicates the extended information about the amount details. Maximum length: 2048 characters	-

AdjustAmount

Field

Data type

Required

Description

Example

type

String

Yes

The way to adjust the order amount. Valid value is:

REDUCE: Indicates to deduct a certain amount

"REDUCE"

adjustPrice

Amount

Yes

The amount to be adjusted for the order.

Notes:

The value of the adjustPrice.value parameter needs to be greater than 0 and smaller than the amount that needs to be paid by customers.
The value of the adjustPrice.currency parameter needs to be the same as the currency of the item prices (specified in the store.menus.categories.items.saleAmount parameter in the syncStore API) in the store.

{"value":100,"currency":"SGD"}