Alipay International Mini Program Development PlatformAlipay International Mini Program Development PlatformDOCS

Data dictionary

ShoppingArea

Field

Data type

Required

Description

Example

areaId

String

Yes

Indicates the unique ID assigned by the SaaS provider or ISV to identify a shopping area, such as a hawker center.

  • Maximum length: 255 characters

"20220112115009000116419747301498"

address

String

Yes

Indicates the address of the shopping area.

  • Maximum length: 1024 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"Toy Hawker Centre,Road C,District B,City A,Country Z"

images

Array<String>

No

Indicates a list of image URLs of the shopping area.

  • Maximum size: 5 elements
  • Element maximum length: 255 characters

Note: The default image will be used if no image is provided.

-

name

String

Yes

Indicates the name of the shopping area.

  • Maximum length: 64 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"Toy Hawker Centre"

description

String

No

Indicates the description of the shopping area.

  • Maximum length: 1024 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"Toy Hawker Centre, the largest hawker with long history in Singapore"

serviceAvailabilityList

Array<ServiceAvailability>

Yes

Indicates the business hours of the shopping area.

  • Maximum size: 20 elements
-

shoppingAreaStatus

String

No

Indicates the status of the shopping area.

Valid values are:

  • OPEN : The shopping area is open and available for users to place orders.
  • CLOSED: The shopping area is closed and not available for users to place orders.

Note: The default status is OPEN if no value is provided.

"OPEN"

location

Location

Yes

Indicates the geographic location of the shopping area.

{

"latitude": 40.659569,

"longitude": -73.851524

}

Or:

{

"postCode": "310000"

}

multiLanguageDetails

Array<MultiLanguageDetail>

No

Indicates the details of the multi-language content.

  • Maximum size: 20 elements

Note: This field is required when the shopping area attributes (e.g., name) need to be displayed in different languages in different countries or regions.

-

timeZone

String

Yes

Indicates the time zone of the shopping area's location.

  • GMT+8:00 or GMT-8:00

-

contactPhoneNos

Array<String>

Yes

Indicates the contact phone numbers of the shopping area.

  • Maximum size: 3 elements
  • Element maximum length: 64 characters
-

pickUpAddress

String

Yes

Indicates the location for users to pick up their food.

  • Maximum length: 1024 characters

"178 Street"

pickUpContactDetails

Array<ContactDetail>

Yes

Indicates the contact information of the pickup location.

  • Maximum size: 20 elements

-

recommendItemIds

Array<String>

No

Indicates a list of IDs to identify the recommended items.

  • Maximum size: 20 elements
  • Element maximum length: 255 characters
-

commentFlag

Boolean

Yes

Specifies whether comments are available for the shopping area. If the value is true, the comments are available for the shopping area, otherwise, the comments are not available.

true

deliveryFee

Amount

No

Indicates the delivery fee to be charged.

{

"currency": "SGD",

"amountValue": 100

}

deliveryPostCodes

Array<String>

No

Indicates a list of postcodes for the delivery service.

  • Maximum size: 400 elements
  • Element maximum length: 6 characters

[

"123456",

"23456"

]

deliveryTimeRules

Array<DeliveryTimeRule>

No

Indicates the time rule that specifies when the delivery service is available.

  • Maximum size: 3 elements

Note:

When the value of ruleType is FIXED:

  • If this array's size is 1 element, you can configure up to 90 timeslots.
  • If this array's size is 2 elements, you can configure up to 40 timeslots for each element.
  • If this array's size is 3 elements, you can configure up to 25 timeslots for each element.

[{

"ruleType": "FIXED",

"supportDays": 2,

"timeSlots": [

{

"startTime": "11:30",

"endTime": "12:15"

},

{

"startTime": "12:30",

"endTime": "13:15"

}

]

}]

Brand

Field

Data type

Required

Description

Example

brandId

String

Yes

Indicates the unique ID to identify a brand.

  • Maximum length: 255 characters

"20220112115009000116419747301498"

brandName

String

Yes

Indicates the name of the brand.

  • Maximum length: 1024 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"KFC"

brandImage

Array<String>

No

Indicates a list of the brand image URLs.

  • Maximum size: 5 elements
  • Element maximum length: 255 characters

Note: The default image will be used if no image is provided.

-

Location

Field

Data type

Required

Description

Example

latitude

String

No

Indicates the latitude of the location.

Value range: -180.000000 - 180.000000

Note:

  • If longitude is provided, then latitude must be provided.
  • Either latitude and longitude or postCode must be provided.

"40.659569"

longitude

String

No

Indicates the longitude of the location.

Value range: -90.000000 - 90.000000

Note:

  • If latitude is provided, then longitude must be provided.
  • Either latitude and longitude or postCode must be provided.

"-73.851524"

postCode

String

No

Indicates the postcode of the location.

  • Maximum length: 32 characters
  • Only alphanumeric characters are allowed.

Note: Either latitude and longitude or postCode must be provided.

"310000"

MultiLanguageDetail

Field

Data type

Required

Description

Example

attributeName

String

Yes

Indicates the attribute name of the multi-language content.

  • Maximum length: 255 characters

"name"

multiLanguagePairs

Map<String,String>

Yes

Indicates the key-value pairs of the multi-language content. Key is the language code while value is the actual local string.

{"zh_cn":"肯德基","en_us:"KFC"}

Result

Property

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.
-

ServiceAvailability

Field

Data type

Required

Description

Example

dayOfWeek

String

Yes

Indicates the day of the week.

Valid values are:

  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY

"MONDAY"

timePeriods

Array<TimePeriod>

Yes

Indicates the business hours, which means the continuous time spans during which the items are available.

  • Maximum size: 100 elements

-

TimePeriod

Field

Data type

Required

Description

Example

startTime

String

Yes

Indicates the beginning of the business hours, which means the time at which the items of the shopping area or store become available.

Note: The time should be in 24-hour HH:MM format, for example, "08:30", "23:00".

"08:30"

endTime

String

Yes

Indicates the end of the business hours, which means the time at which the items of the shopping area or store cease to be available.

Note: The time should be in 24-hour HH:MM format, for example, "08:30", "23:00".

"23:30"

description

String

No

Indicates the description of the business hours.

  • Maximum length: 1024 characters

"Lunch"

Store

Field

Data type

Required

Description

Example

areaId

String

No

Indicates the ID of the shopping area to which the store belongs.

  • Maximum length: 255 characters

Note: This field is required when the value of storeType is HAWKER.

"000000032"

brandId

String

No

Indicates the ID to identify a brand to which the store belongs.

  • Maximum length: 255 characters

"000000032"

storeId

String

Yes

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

  • Maximum length: 255 characters

"000000032"

name

String

Yes

Indicates the name of the store.

  • Maximum length: 255 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"MOM FOOD"

storeType

String

Yes

Indicates the type of the store.

Valid values are:

  • RESTAURANT: Restaurant
  • HAWKER: Hawker in a hawker center

"HAWKER"

address

String

Yes

Indicates the address of the store.

  • Maximum length: 1024 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"311 New Upper Changi Rd, Singapore 467360"

images

Array<String>

No

Indicates a list of image URLs of the store.

  • Maximum size: 5 elements
  • Element maximum length: 255 characters

Note: The default image will be used if no image is provided.

-

storeStatus

String

No

Indicates the status of the store.

Valid values are:

  • OPEN: The store is open.
  • CLOSED: The store is closed.

Note: The default status is OPEN if no value is provided.

"OPEN"

announcement

Array<ContentModel>

No

Indicates the announcement of the store.

  • Maximum size: 20 elements

[

{

"ContentType": "TEXT",

"value": "We are open!"

},

{

"ContentType": "IMAGE",

"value": "https://wdsas/dsad.jpg"

}

]

description

String

No

Indicates the description of the store.

  • Maximum length: 1024 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"We sell Chinese Food!"

location

Location

Yes

Indicates the geographic location of the store.

-

serviceAvailabilityList

Array<ServiceAvailability>

No

Indicates the business hours of the store.

  • Maximum size: 20 elements

-

multiLanguageDetails

Array<MultiLanguageDetail>

No

Indicates the details of the multi-language content.

  • Maximum size: 20 elements

Note: This field is required when the store attributes (e.g., name) need to be displayed in different languages in different countries or regions.

-

timeZone

String

Yes

Indicates the time zone of the store's location.

  • GMT+8:00 or GMT-8:00

-

cuisine

String

No

Indicates the cuisine type of the store.

  • Maximum length: 100 characters

"Chinese food"

contactPhoneNos

Array<String>

Yes

Indicates the contact phone numbers of the store.

  • Maximum size: 3 elements
  • Element maximum length: 64 characters

["18376545678"]

pickUpAddress

String

Yes

Indicates the location for users to pick up their food.

  • Maximum length: 1024 characters

"178 Street"

pickUpContactDetails

Array<ContactDetail>

Yes

Indicates the contact information of the pickup location.

  • Maximum size: 20 elements

-

banners

Array<BannerModel>

No

Indicates the banner attribute.

  • Maximum size: 5 elements
-

recommendItemIds

Array<String>

No

Indicates a list of IDs to identify the recommended items.

  • Maximum size: 20 elements
  • Element maximum length: 255 characters
-

businessRules

Array<BusinessRule>

No

Indicates the business rules, for example, the delivery fee rules, the pickup schedule rules, etc.

Maximum size: 20 elements

Note: For the sample implementations to specify a store's business rules, see Business rules for Store in the initializeStore, addStore, or updateStore APIs.

-

extInfo

String

No

Indicates the extended information of the store.

  • Maximum length: 4096 characters

Note:

  • Specify the mccType parameter that indicates the category of the merchant's business type, for example, "5814".
  • Specify the inQueueScopes parameter, which indicates the scopes that support in-queue orders. This parameter is a JSON string containing an Array<String> object (Maximum size: 3 elements). Valid values are:
    • PICKUP: Food that is picked up by users themselves.
    • DINEIN: Food that is eaten in the restaurant where it is ordered.
    • DELIVERY: Food that requests delivery to a specific destination.
  • Specify the reservationScopes parameter, which indicates the scopes that support scheduled orders. This parameter is a JSON string containing an Array<String> object (Maximum size: 3 elements). Valid values are:
    • PICKUP: Food that is picked up by users themselves.
    • DINEIN: Food that is eaten in the restaurant where it is ordered.
    • DELIVERY: Food that requests delivery to a specific destination.

"{"mccType":"5814"}"

BannerModel

Field

Data type

Required

Description

imageUrl

String

Yes

Indicates the image URL.

  • Maximum length: 255 characters

landingUrl

String

Yes

Indicates the landing page when clicking the image.

  • Maximum length: 255 characters

ContentModel

Field

Data type

Required

Description

Example

contentType

String

Yes

Indicates the type of the content.

Valid values are:

  • TEXT: The content is in text form.
  • IMAGE: The content is in image form.

"TEXT"

value

String

Yes

Indicates the value of the content.

  • Maximum length: 20000 characters

"000000032"

Menu

Field

Data type

Required

Description

Example

menuId

String

Yes

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

  • Maximum length: 255 characters

"000000032"

storeId

String

Yes

Indicates the ID of the store to which the menu belongs.

  • Maximum length: 255 characters

"000000032"

menuType

String

Yes

Indicates the type of the menu.

Valid values are:

  • PICKUP: Food that is picked up by users themselves.
  • DINEIN: Food that is eaten in the restaurant where it is ordered.
  • DELIVERY: Food that requests delivery to a specific destination.

"PICKUP"

title

String

Yes

Indicates the title of the menu.

  • Maximum length: 255 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"COMBO"

subTitle

String

No

Indicates the subtitle of the menu.

  • Maximum length: 255 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"DRINKS"

menuStatus

String

No

Indicates the status of the menu.

Valid values are:

  • VALID: The menu is valid.
  • INVALID: The menu is invalid.

Note: The default status is VALID if no value is provided.

"VALID"

pickUpRules

Array<PickUpRule>

No

Indicates the available pickup time range.

  • Maximum size: 20 elements

Note: This field is required when the value of menuType is PICKUP.

-

multiLanguageDetails

Array<MultiLanguageDetail>

No

Indicates the details of the multi-language content.

  • Maximum size: 20 elements

Note: This field is required when the menu attributes (e.g., title) need to be displayed in different languages in different countries or regions.

-

minPrepareMinutes

Integer

No

Indicates at least how many minutes in advance users can order.

  • In minutes.
  • Value range: 1-600

Note: By default, the value is 0.

15

PickUpRule

Field

Data type

Required

Description

Example

startTime

String

Yes

Indicates the beginning of the pickup time, which means the time at which the pickup service becomes available.

Note: The time should be in 24-hour HH:MM format, for example, "08:30", "23:00".

"08:30"

endTime

String

Yes

Indicates the end of the pickup time, which means the time at which the pickup service ceases to be available.

Note: The time should be in 24-hour HH:MM format, for example, "08:30", "23:00".

"23:30"

step

String

Yes

Indicates the length of the time span.

  • In minutes.

"30"

supportDays

Integer

Yes

1 for today, 2 for today and tomorrow, etc.

Value range: 1-10

1

minPrepareMinutes

Integer

Yes

Indicates at least how many minutes in advance users can order.

Value range: 1-600

60

Category

Field

Data type

Required

Description

Example

categoryId

String

Yes

Indicates the category ID.

  • Maximum length: 255 characters

"0000000004"

storeId

String

Yes

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

  • Maximum length: 255 characters
-

menuId

String

Yes

Indicates the ID of the menu to which the category belongs.

  • Maximum length: 255 characters

"0000000003"

menuType

String

Yes

Indicates the type of the menu.

Valid values are:

  • PICKUP: Food that is picked up by users themselves.
  • DINEIN: Food that is eaten in the restaurant where it is ordered.
  • DELIVERY: Food that requests delivery to a specific destination.

Note: This field is required in the addCategory API to add a category.

"PICKUP"

title

String

Yes

Indicates the title of the category.

  • Maximum length: 255 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"Hamburger"

subTitle

String

No

Indicates the subtitle of the category.

  • Maximum length: 255 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"Big Hamburger"

icon

String

No

Indicates the icon of the category.

  • Maximum length: 255 characters
-

multiLanguageDetails

Array<MultiLanguageDetail>

No

Indicates the details of the multi-language content.

  • Maximum size: 20 elements

Note: This field is required when the category attributes (e.g., title) need to be displayed in different languages in different countries or regions.

-

Item

Field

Data type

Required

Description

Example

itemId

String

Yes

Indicates the ID assigned by the SaaS provider or ISV to identify an item.

  • Maximum length: 255 characters

Note: The ID of the root item in the same category must be unique.

"100000000it32"

saleType

String

Yes

Indicates the sale type of an item. Valid values are:

  • SINGLE: An individual item that can be ordered by itself.
  • ADDON: A complementary item that can be ordered within a modifier group.

Note: This field is required in the addItem API to add an item.

"SINGLE"

storeId

String

Yes

Indicates the ID assigned by the SaaS provider or ISV to identify a store, such as a hawker or a restaurant.

  • Maximum length: 255 characters

Note: This field is required in the addItem API. To add an item to the store, make sure the Store object has been synchronized via the initializeStore or addStore API.

"000000032"

menuId

String

Yes

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

  • Maximum length: 255 characters

Note: This field is required when the value of saleType is SINGLE in the addItem API. To add a single item to the menu, make sure the Menu object has been synchronized via the initializeStore or addMenu API.

"000000032"

menuType

String

Yes

Indicates the type of the menu. Valid values are:

  • PICKUP: Food that is picked up by users themselves.
  • DINEIN: Food that is eaten in the restaurant where it is ordered.
  • DELIVERY: Food that requests delivery to a specific destination.

Note: This field is required when the value of saleType is SINGLE in the addItem API to add an item.

"PICKUP"

categoryId

String

Yes

Indicates the ID assigned by the SaaS provider or ISV to identify the category to which the item belongs.

  • Maximum length: 255 characters

Note: This field is required when the value of saleType is SINGLE in the addItem API. To add a single item to the category, make sure the Category object has been synchronized via the initializeStore or addCategory API.

"30000000ca12"

quantityRule

QuantityRule

No

Indicates the quantity rule of the item.

Note: The rule is {"max":999,"min":0} by default.

-

images

Array<String>

No

Indicates a list of image URLs of the item.

  • Maximum size: 5 elements
  • Element maximum length: 255 characters

Note: The default image will be used if no image is provided.

-

itemTitle

String

Yes

Indicates the title of the item.

  • Maximum length: 255 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"chicken"

itemDescription

String

No

Indicates the description of the item.

  • Maximum length: 1024 characters
  • Can be Null

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"fried chicken"

priceInfo

PriceInfo

Yes

Indicates the price information of the item.

-

itemStatus

String

No

Indicates the status of the item.

Valid values are:

  • AVAILABLE: The item is available to order.
  • REMOVED: The item is removed, thus unavailable to order.
  • SOLDOUT: The item is sold out for now, but may be available at other times.

"SOLDOUT"

skuPropertyGroups

Array<SkuPropertyGroup>

No

Indicates all possible SKU property groups.

  • Maximum size: 100 elements

Note: For items with SKU information, both skus and skuPropertyGroups are required. See More information for the rule about specifying the skus and skuPropertyGroups parameters.

-

skus

Array<Sku>

No

Indicates SKU details, e.g., price.

  • Maximum size: 200 elements

Note: For items with SKU information, both skus and skuPropertyGroups are required. See More information for the rule about specifying the skus and skuPropertyGroups parameters.

-

modifierGroupIds

Array<String>

No

Indicates a list of IDs to identify different modifier groups.

  • Maximum size: 20 elements
  • Element maximum length: 255 characters

Note:

  • This field is only applicable to the addItem or updateItem API, not the initializeStore API. To attach modifier groups to an item, make sure the ModifierGroup objects have been synchronized via the initializeStore or addModifierGroup API.
  • The modifier groups you specify are in the same order as they are displayed on the mini program.

["xxxxxxa","xxxxxb","xxxxxc"]

multiLanguageDetails

Array<MultiLanguageDetail>

No

Indicates the details of the multi-language content.

  • Maximum size: 20 elements

Note: This field is required when the item attributes (e.g., itemTitle, itemDescription) need to be displayed in different languages in different countries or regions.

-

serviceAvailabilityList

Array<ServiceAvailability>

No

Indicates the time range when the item becomes visible to users.

  • Maximum size: 20 elements

Note:

  • If you specify this field, the item is only visible to users during the specified time range when the value of itemStatus is AVAILABLE or SOLDOUT.
  • When the value of itemStatus is REMOVED, the time range you set is not effective, and the item is invisible to users.
  • If you do not specify this field or specify this field with an empty list, the item is always visible to users when the value of itemStatus is AVAILABLE or SOLDOUT.
  • To make the item invisible to users, simply delete the item or set the value of itemStatus to REMOVED.
-

takeawayFee

Amount

No

Indicates the takeaway charge.

Note: By default, takeawayFee is 0.

{

"currency": "SGD",

"amountValue": 100

}

businessRules

Array<BusinessRule>

No

Indicates the business rules of the item, for example, the pricing rules based on different time periods, the item status rules, etc.

Maximum size: 20 elements

Note: For the sample implementations to specify an item's business rules, see Business rules for Item in the initializeStore, addItem, or updateItem APIs.

-

ModifierGroup

Note:

  • Nested loops are not allowed, for example, groupA contains itemB while itemB contains groupA.
  • The maximum nesting depth for item-group-item is 10 levels.

Field

Data type

Required

Description

Example

groupId

String

Yes

Indicates the ID assigned by the SaaS provider or ISV to identify a modifier group. A modifier group can belong to multiple items.

  • Maximum length: 255 characters

"1000000gr23"

storeId

String

Yes

Indicates the ID assigned by the SaaS provider or ISV to identify a store, such as a hawker or a restaurant.

  • Maximum length: 255 characters

Note: This field is required in the addModifierGroup API. To add a modifier group to the store, make sure the Store object has been synchronized via the initializeStore or addStore API.

"000000032"

groupName

String

Yes

Indicates the name of the modifier group.

  • Maximum length: 255 characters

Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"add-on"

childItemIds

Array<String>

Yes

Indicates a list of add-on item IDs in the modifier group.

  • Maximum size: 100 elements
  • Element maximum length: 255 characters

Note: This field is required in the addModifierGroup API. To attach add-on items to the new modifier group, make sure the Item objects have been synchronized via the initializeStore or addItem API.

-

quantityRule

QuantityRule

Yes

Indicates the quantity rule that constrains the total number of add-on items that can be ordered within a modifier group. For example, {"max":4,"min":1} means that within a modifier group, users are required to purchase at least 1 add-on item, and they can purchase 4 add-on items at most.

{"max":4,"min":1}

multiLanguageDetails

Array<MultiLanguageDetail>

No

Indicates the details of the multi-language content.

  • Maximum size: 20 elements

Note: This field is required when the modifier group attributes (e.g., groupName) need to be displayed in different languages in different countries or regions.

-

Sku

Field

Data type

Required

Description

Example

skuId

String

Yes

Indicates the ID assigned by the SaaS provider or ISV to identify an SKU.

  • Maximum length: 255 characters

"40000000sk54"

image

String

No

Indicates the URL of the SKU image.

  • Maximum length: 255 characters
  • Can be Null

-

skuPropertyPairs

Map<String,String>

Yes

Indicates the SKU combination.

  • Map cannot be empty.
  • Key and value cannot be empty.

Note: Within one item (specified by the itemId parameter), the key-value pairs for any SKU (specified by the skuId parameter) must be unique and cover all SkuPropertyGroup.propertyGroupKey you specify.

  • For each key-value pair (specified by the Sku.skuPropertyPairs parameter), key is specified according to skuPropertyGroups.propertyGroupKey.
  • Value is specified according to SkuProperty.propertyValue.

{

"size": "large",

"doneness": "rare"

}

priceInfo

PriceInfo

Yes

Indicates the price information of the SKU.

-

businessRules

Array<BusinessRule>

No

Indicates the business rules of the SKU, for example, the pricing rules based on different time periods.

Maximum size: 20 elements

Note: For the sample implementations to specify an SKU's business rules, see Business rules for Sku in the initializeStore, addItem, or updateItem APIs.

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, CNY.

"SGD"

QuantityRule

Field

Data type

Required

Description

Example

max

Integer

Yes

Indicates the maximum number of items a user can choose.

Value range: 0-2147483647

Note: max must be greater than or equal to min.

2

min

Integer

Yes

Indicates the minimum number of items a user can choose.

Value range: 0-2147483647

1

SkuPropertyGroup

Field

Data type

Required

Description

Example

propertyGroupName

String

Yes

Indicates the SKU group name.

  • Maximum length: 255 characters

Note:

  • Used for UI display in the mini program.
  • This field should be in English. If multi-language is needed, refer to MultiLanguageDetail.

"Size"

propertyGroupKey

String

Yes

Indicates the unique key to identify the SKU group in the item.

  • Maximum length: 64 characters

Note: English only. Not used for UI display in the mini program.

"size"

properties

Array<SkuProperty>

Yes

Indicates a list of properties in the SKU group.

  • Maximum size: 100 elements
-

multiLanguageDetails

Array<MultiLanguageDetail>

No

Indicates the details of the multi-language content.

  • Maximum size: 20 elements

Note: This field is required when the SkuPropertyGroup attributes (e.g., propertyGroupName) need to be displayed in different languages in different countries or regions.

-

SkuProperty

Field

Data type

Required

Description

Example

propertyValue

String

Yes

Indicates the unique value to identify the property in SkuPropertyGroup.

  • Maximum length: 64 characters

Note: English only. Not used for UI display in the mini program.

"small"

propertyName

String

Yes

Indicates the SKU property name.

  • Maximum length: 255 characters

Note:

  • Used for UI display in the mini program.

"Small"

multiLanguageDetails

Array<MultiLanguageDetail>

No

Indicates the details of the multi-language content.

  • Maximum size: 20 elements

Note: This field is required when the SkuProperty attributes (e.g., propertyName) need to be displayed in different languages in different countries or regions.

-

ContactDetail

Field

Data type

Required

Description

Example

name

String

Yes

Indicates the name of the contact person.

  • Maximum length: 64 characters

"mike"

phoneNo

String

Yes

Indicates the phone number of the contact person.

  • Maximum length: 64 characters

"12345678901"

Amount

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, or 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

DeliveryTimeRule

Field

Data type

Required

Description

Example

ruleType

String

Yes

Indicates the type of delivery time rule. The valid value is FIXED, which means a fixed time range when the delivery service is available.

"FIXED"

fixedTimeSlots

Array<TimePeriod>

No

Indicates the fixed time slots when the delivery service is available.

Maximum size: 100 elements

Note: This field is required when the value of ruleType is FIXED.

[

{

"startTime": "11:30",

"endTime": "12:15"

},

{

"startTime": "12:30",

"endTime": "13:15"

}

]

supportDays

Integer

Yes

1 for today, 2 for today and tomorrow, etc.

Value range: 1-10

1

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

Yes

Indicates the ID assigned by the SaaS provider or ISV to identify the category to which the item belongs.

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:

    • 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.
    • This field is required when the SaaS provider or ISV calls this API to update one or more items in the order. For 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 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 a JSON string containing an Array<ModifierGroupDetail> object (Maximum size: 20 elements).

"[{\"groupId\":1,\"itemDetail\":[{\"itemId\":213\"quantity\":1},{\"itemId\":214\"quantity\":1}]}]
"

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": 1,

"quantity": 2

},

{

"itemId": 1,

"quantity": 2

}

]

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

Yes

Indicates the post code.

Maximum length: 6 characters

"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

-

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\"}

BusinessRule

For Store

Field

Data type

Required

Description

Example

scene

String

Yes

Indicates the scene of the business rule.

Valid values are:

  • DELIVERY_DISTANCE: The delivery range and corresponding delivery fee.
  • PICKUP_RULE: The pickup rule.
  • DELIVERY_SCHEDULE: The available delivery time range.
  • PICKUP_SCHEDULE: The available pickup time range.
  • DINE_IN_ORDER: The dine-in rule.
  • DINE_IN_SCHEDULE: The available dine-in time range.

Note: For different scenes, specify different values to the ruleData parameter as required.

"DELIVERY_DISTANCE"

ruleData

String

Yes

Indicates the data to be synchronized based on different scenes.

  • If the value of scene is DELIVERY_DISTANCE or PICKUP_RULE, ruleData is a JSON string containing an Array<FeeRule> object. The maximum size of the array is 30 elements.
  • If the value of scene is DELIVERY_SCHEDULE , PICKUP_SCHEDULE , or DINE_IN_SCHEDULE, ruleData is a JSON string containing an Array<ScheduleRule> object. The maximum size of the array is 20 elements.
  • If the value of scene is DINE_IN_ORDER, ruleData is a JSON string containing a DineInOrderRule object.

-

For Item

Field

Data type

Required

Description

Example

scene

String

Yes

Indicates the scene of the business rule.

Valid values are:

  • PRICE_SCHEDULE: The item price differs based on the time periods specified.
  • ITEM_STATUS_RULE: The item status differs based on the time periods specified.

Note: For different scenes, specify different values to the ruleData parameter as required.

"PRICE_SCHEDULE"

ruleData

String

Yes

Indicates the data to be synchronized based on different scenes.

  • If the value of scene is PRICE_SCHEDULE, ruleData is a JSON string containing an Array<PriceScheduleRule> object. The maximum size of the array is 40 elements.
  • If the value of scene is ITEM_STATUS_RULE, ruleData is a JSON string containing an Array<ItemStatusRule> object. The maximum size of the array is 40 elements.

-

For Sku

Field

Data type

Required

Description

Example

scene

String

Yes

Indicates the scene of the business rule.

The valid value is:

  • PRICE_SCHEDULE: The SKU price differs based on the time periods specified.
  • SKU_STATUS_RULE: The SKU status differs based on the time periods specified.

Note: For different scenes, specify different values to the ruleData parameter as required.

"PRICE_SCHEDULE"

ruleData

String

Yes

Indicates the data to be synchronized based on different scenes.

  • If the value of scene is PRICE_SCHEDULE, ruleData is a JSON string containing an Array<PriceScheduleRule> object. The maximum size of the array is 40 elements.
  • If the value of scene is SKU_STATUS_RULE, ruleData is in JSON format containing an Array<SkuStatusRule> object. The maximum size of the array is 40 elements.

-

FeeRule

Field

Data type

Required

Description

Example

from

Integer

No

Indicates the start of a distance range, in meters.

Value range: 0-500,000

Note: This field is required when the value of scene is DELIVERY_DISTANCE.

1000

to

Integer

No

Indicates the end of a distance range, in meters.

Value range: 0-500,000

Note: This field is required when the value of scene is DELIVERY_DISTANCE.

5000

fee

Amount

No

Indicates the delivery fee.

Note: This field is required when the value of scene is DELIVERY_DISTANCE.

copy
{
  "currency": "SGD",
  "amountValue": 2000
}

minimumOrderAmount

Amount

No

Indicates the minimum order amount for orders.

copy
{
  "currency": "SGD",
  "amountValue": 10000
}

discounts

Array<DiscountRule>

No

Indicates the discount rules.

Maximum size: 10 elements

copy
[
  {
    "discountType": "REDUCE",
    "thresholdAmount" {
      "currency": "SGD",
      "amountValue": 1000
    },
    "discountValue": "{\"currency\": \"SGD\", \"amountValue\":1000}"
  },
  {
    "discountType": "PERCENTAGE",
    "thresholdAmount" {
      "currency": "SGD",
      "amountValue": 2000
    },
    "discountValue": "20"
  },
  {
    "discountType": "EXEMPTION",
    "thresholdAmount" {
      "currency": "SGD",
      "amountValue": 3000
    }
  }
]

ScheduleRule

Field

Data type

Required

Description

Example

startTime

Datetime

No

Indicates the start date of the schedule. The value follows the ISO 8601 standard format. 

Note: If this parameter is not specified, the schedule will take effect immediately.

"2022-06-01T12:01:01+08:30"

endTime

Datetime

No

Indicates the end date of the schedule. The value follows the ISO 8601 standard format. 

Note: If this parameter is not specified, there is no expiration date after the schedule takes effect.

"2022-12-31T12:01:01+08:30"

scheduleType

String

Yes

Indicates the type of the schedule.

Valid values are:

  • DAILY: A fixed schedule for a day, which means the schedule will take effect every day.
  • WEEKLY: A list of schedules for each day of the week.

"WEEKLY"

schedules

Map<String, Array<TimePeriod>>

Yes

Indicates the details of the schedule, represented as key-value pairs.

  • The key is specified differently based on the value of scheduleType to represent a certain day:
    • When the value of scheduleType is WEEKLY, the key is specified as MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.
    • When the value of scheduleType is DAILY, the key is specified as FIXED.
  • The value is specified by Array<TimePeriod> to represent a set of time periods. The maximum size of the array is 100 elements.
  • When the value is an empty array, that means the store does not open on the day specified by the key.
copy
{
  "MONDAY": [
    {
      "startTime": "11:30", 
      "endTime": "12:15" 
    },
    {
      "startTime": "12:30", 
      "endTime": "13:15" 
    }
  ],
  "TUESDAY": [
    {
      "startTime": "11:30", 
      "endTime": "12:15" 
    },
    {
      "startTime": "12:30", 
      "endTime": "13:15" 
    }
  ]
}

supportDays

Integer

Yes

Indicates the number of days the schedule is applied to, for example, 1 for today, 2 for today and tomorrow, etc.

Value range: 1-30

1

DiscountRule

Field

Data type

Required

Description

Example

orderThresholdAmount

Amount

Yes

Indicates the threshold order amount for the discount to take effect.

copy
{
  "currency": "SGD",
  "amountValue": 1000
}

discountType

String

Yes

Indicates the type of discount on delivery fees.

Valid values are:

  • REDUCE: Money-off discount, for example, SGD 2 off the delivery fee on orders over SGD 20.
  • PERCENTAGE: Percentage-off discount, for example, 20% off the delivery fee on orders over SGD 30.
  • EXEMPTION: Free delivery, for example, free delivery on orders over SGD 50.

"REDUCE"

discountValue

String

No

Indicates the specific discount of the delivery fee. The value may vary based on different discount types.

  • If the value of discountType is REDUCE, discountValue is a JSON string containing an Amount object. For example, "{\"currency\":\"SGD\", \"amountValue\":\"1000\"}" means that the delivery fee is reduced by SGD 10.
  • If the value of discountType is PERCENTAGE, discountValue is a string. For example, when the value of discountValue is 20, it means a 20% discount on the delivery fee.
  • If the value of discountType is EXEMPTION, discountValue is null, which means no delivery fee is charged.

-

DineInOrderRule

Field

Data type

Required

Description

Example

isTableNoRequired

Boolean

Yes

Specifies whether the user needs to fill in the table number when scanning a QR code to order. If the value is true, the user needs to fill in the table number, otherwise, the user does not need to fill in the table number.

true

serviceType

String

Yes

Indicates the service type of a dine-in order. Valid values are:

  • SELF_COLLECT: Food is collected by the user.
  • SERVE_TO_TABLE: Food is served to the user's table.

"SELF_COLLECT"

PriceScheduleRule

Field

Data type

Required

Description

Example

from

Datetime

Yes

Indicates the date and time when the pricing schedule takes effect.

The value follows the ISO 8601 standard format.

"2022-11-27T12:01:01+08:00"

to

Datetime

Yes

Indicates the date and time when the pricing schedule ends.

The value follows the ISO 8601 standard format.

Note: to must be equal to or later than from.

"2022-12-27T12:01:01+08:00"

weekDays

Array<String>

Yes

Indicates the list of days for each week.

Valid values are:

  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY

Maximum size: 7 elements

copy
[
  "MONDAY",
  "SUNDAY"
]

timeSlot

TimePeriod

Yes

Indicates the business hours, which means the continuous time spans during which the item or SKU is available.

-

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, CNY.

"SGD"

ItemStatusRule

Field

Data type

Required

Description

Example

from

Datetime

Yes

Indicates the date and time when the item status rule takes effect.

The value follows the ISO 8601 standard format.

"2019-11-27T12:01:01+08:00"

to

Datetime

Yes

Indicates the date and time when the item status rule ends.

The value follows the ISO 8601 standard format.

Note: to must be equal to or later than from.

"2022-12-27T12:01:01+08:00"

weekDays

Array<String>

Yes

Indicates the list of days for each week.

Valid values are:

  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY

Maximum size: 7 elements

copy
[
  "MONDAY",
  "SUNDAY"
]

timeSlot

TimePeriod

Yes

Indicates the business hours, which means the continuous time spans during which the item is available.

-

itemStatus

String

Yes

Indicates the status of the item.

Valid values are:

  • AVAILABLE: The item is available to order.
  • REMOVED: The item is removed, thus unavailable to order.
  • SOLDOUT: The item is sold out for now, but may be available at other times.

"SOLDOUT"

SkuStatusRule

Field

Data type

Required

Description

Example

from

Datetime

Yes

Indicates the date and time when the SKU status rule takes effect.

The value follows the ISO 8601 standard format.

"2019-11-27T12:01:01+08:00"

to

Datetime

Yes

Indicates the date and time when the SKU status rule ends.

The value follows the ISO 8601 standard format.

Note: to must be equal to or later than from.

"2022-12-27T12:01:01+08:00"

weekDays

Array<String>

Yes

Indicates the list of days for each week.

Valid values are:

  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY

Maximum size: 7 elements

copy
[
  "MONDAY",
  "SUNDAY"
]

timeSlot

TimePeriod

Yes

Indicates the business hours, which means the continuous time spans during which the SKU is available.

-

skuStatus

String

Yes

Indicates the status of the SKU.

Valid values are:

  • AVAILABLE: The SKU is available to order.
  • REMOVED: The SKU is removed, thus unavailable to order.

"AVAILABLE"

Vendor

Field

Data Type

Required

Description

Example

convenienceFee

Amount

No

Indicates the convenience fee.

Note:

  • By default, convenienceFee is 0.
  • The field is only applicable when the value of orderType is PICKUP, which means you can only update the convenience fee of pickup orders.

{

"currency": "SGD",

"amountValue": 100

}

smallOrderFeeRule

SmallOrderFeeRule

No

Indicates the rule for the small order fee to be charged on orders less than the minimum order amount (specified by the thresholdAmount parameter).

Note:

  • By default, maxAmount is 0, which indicates smallOrderFeeAmount is 0.
  • To learn how smallOrderFeeAmount is calculated, see smallOrderFeeAmount.

{

"currency": "SGD",

"maxAmount": 3,

"thresholdAmount": 10

}

SmallOrderFeeRule

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, or CNY.

"SGD"

maxAmount

Integer

Yes

Indicates the maximum amount you can charge to 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

3

thresholdAmount

Integer

Yes

Indicates the minimum order amount specified to charge a small order fee, which is in the currency's smallest unit. For example, 9999 means 99.99 in SGD.

Value range: 0-2147483647

10