syncStore
POST /v2/pds/store/syncStore
The syncStore API is used by SaaS providers or ISVs to send a request to D-store Platform to insert, update, or hide a store, such as updating or hiding menus, categories, or items for a store.
[IMPORTANT] When you call this API, keep the following points in mind:
- The request URL for this API is:
- Production environment: https://open-region.alipayplus.com/v2/pds/store/syncStore
- Sandbox environment: https://open-region-pre.alipayplus.com/v2/pds/store/syncStore
- How to specify request parameters:
- To insert data, refer to the notes in the Store, Menu, Category, Item, and ModifierGroup models to make sure you specify all the required parameters in the request body.
- To update data:
- To update store information, menus, categories, items, or modifier groups, specify new values for the relevant parameters you want to update in the request body. Do not include existing values that haven't changed. For example, if there are five existing items and you want to add three new items, only pass the new items with the items parameter.
- To update elements from an object or array, pass the entire new object or array. For example, if there are two SKUs for one item and you want to add one more, pass the skus parameter with three SKUs, including the original two and the new one.
- To hide a store, menu, category, or item, specify the status parameter, for example, to hide a menu, specify the value of the store.menus.status parameter as
INVALID.To learn potential implementations of the syncStore API, see Exploring API use cases.
Structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:
Request parameters
Field | Data type | Required | Description | Example |
appId | String | No | Indicates the unique ID assigned by Mini Program Platform to identify a mini program.
Note: Obtain this parameter value by calling the my.getAppIdSync JSAPI or from Mini Program Platform. | "210201011541****" |
requestId | String | Yes | Indicates the unique ID assigned by the SaaS provider or ISV to identify a request for the synchronization of stores.
Note: This field is an idempotent field.
| "20220434217220111" |
store | Yes | Indicates the details of a store. | - |
Response parameters
Field | Data type | Required | Description |
result | Yes | Indicates the request result such as status and error codes. |
More information
How to specify skus and skuPropertyGroups
To specify the skus and skuPropertyGroups parameters, follow the rule below:
- For items with SKU information, both skus and skuPropertyGroups are required.
- Within one item (specified in the itemId parameter), the Sku.skuPropertyPairs parameter is specified according to skuPropertyGroups:
- For each key-value pair (specified in the Sku.skuPropertyPairs parameter), key is specified according to skuPropertyGroups.skuGroupId.
- Value is specified according to SkuProperty.propertyId.
- Within one item (specified in the itemId parameter), the key-value pairs for any SKU (specified in the skuId parameter) must be unique and cover all SkuPropertyGroup.skuGroupId you pass.
See the following sample:
copy
{
"skuPropertyGroups": [
{
"name": "size",
"skuGroupId": "27731",
"properties": [
{
"name": "Small",
"propertyId": "Small"
},
{
"name": "Large",
"propertyId": "Large"
}
]
},
{
"skuGroupId": "27733",
"name": "Level of Spiciness",
"properties": [
{
"name": "No Chilli",
"propertyId": "No Chilli"
},
{
"name": "Less Chilli",
"propertyId": "Less Chilli"
},
{
"name": "Extra Chilli",
"propertyId": "Extra Chilli"
},
{
"name": "Normal Spicy",
"propertyId": "Normal Spicy"
}
]
}
],
"skus": [
{
"image": "https://www.example.com/images/uploads/meals/0f62cf2de02248cee773f990ca.JPG",
"priceInfo": {
"originAmount": 100,
"saleAmount": 90,
"currency": "SGD"
},
"skuId": "tsku2121",
"skuPropertyPairs": {
"27731": "Small",
"27733": "Normal Spicy"
}
},
{
"image": "https://wwww.example.com/images/uploads/meals/2cf2dfssdmgkeqec1c.png",
"priceInfo": {
"originAmount": 100,
"saleAmount": 80,
"currency": "SGD"
},
"skuId": "tsku2122",
"skuPropertyPairs": {
"27731": "Large",
"27733": "Normal Spicy"
}
}
]
}How to handle the result
You might receive different results from D-store Platform. Follow the instructions below to handle the result:
result.resultStatus | result.resultCode | Actions |
S | SUCCESS | The store sync request is successful and being processed. We will ensure the consistency of the final data. |
F | ... | Take actions according to the result message (specified in the result.resultMessage parameter). For more information, see Result codes. |
U | ... | Contact our technical support to troubleshoot the issue. |
No result received | Contact our technical support to troubleshoot the issue. | |
Result codes
Result code | Result status | Result message | Further action |
SUCCESS | S | Success. | N/A |
UNKNOWN_EXCEPTION | U | Unknown exception like NPE, ClassCastException etc. | Contact our technical support to troubleshoot the issue. |
PROCESS_FAIL | F | PENDING_API: The previous request is being processed, please wait a minute. | Wait and call the API later. If not resolved, contact our technical support to troubleshoot the issue. |
INVALID_PARAMETER | F | *Result messages vary according to specific parameters. Stay tuned. | - |
Samples
The data flow of sending a request to synchronize store information is illustrated as follows:
The above diagram consists of the following steps:
- A SaaS provider calls this API to send a request to D-store Platform for data synchronization.
- D-store Platform processes the request.
- D-store Platform returns the result to the SaaS provider.
Request
copy
{
"requestId": "20220434217220111",
"appId": "210201011541****",
"store": {
"storeId": "AMP-YW6****",
"brandId": "itemIdTest01",
"name": {
"value": {
"en-US": "ItemIdTest0108"
}
},
"type": "RESTAURANT",
"location": {
"address": {
"value": {
"en-US": "Lot 1.103.00 & E1.103.0, Level 1, Elite Pavilion, 168 Jalan Bukit Bintang, 55100 Kuala Lumpur."
}
},
"postcode": "55100",
"latitude": "40.659569",
"longitude": "-73.851524"
},
"status": "OPEN",
"contacts": [
{
"name": {
"value": {
"en-US": "will"
}
},
"phoneNo": "03-2110****"
},
{
"name": {
"value": {
"en-US": "Bob"
}
},
"phoneNo": "03-2120****"
}
],
"contents": [
{
"type": "TEXT",
"scene": "ANNOUNCEMENT",
"value": "{\"value\":{\"en-US\":\"Store ABC\"}}"
},
{
"type": "IMAGE",
"scene": "BACKGROUND",
"value": "https://omni.posplus-crm.com/Omni_FnbItem/storeabc/test.png"
},
{
"type": "TEXT",
"scene": "DESCRIPTION",
"value": "{\"value\":{\"en-US\":\"Store ABC\"}}"
}
],
"serviceSchedules": [
{
"scheduleType": "DAILY",
"schedules": {
"FIXED": [
{
"startTime": "00:30+08:00",
"endTime": "12:15+08:00"
},
{
"startTime": "12:30+08:00",
"endTime": "23:15+08:00"
}
]
}
},
{
"scheduleType": "WEEKLY",
"startTime": "2022-06-01T00:00:01+08:00",
"endTime": "2022-12-01T00:00:01+08:00",
"schedules": {
"MONDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"TUESDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"WEDNESDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"THURSDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"FRIDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"SATURDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"SUNDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
]
}
}
],
"bizRules": [
{
"scene": "DINE_IN_SCHEDULE",
"ruleData": "[{\"scheduleType\":\"DAILY\",\"supportDays\":1,\"schedules\":{\"FIXED\":[{\"startTime\":\"00:00+08:00\",\"endTime\":\"12:00+08:00\"},{\"startTime\":\"12:10+08:00\",\"endTime\":\"23:50+08:00\"}]}}]"
},
{
"scene": "DINE_IN_ORDER",
"ruleData": "{\"isTableNoRequired\":\"false\",\"serviceType\":\"SERVE_TO_TABLE\"}"
}
],
"extendInfo": {
"recommendItemIds": [
"123",
"245"
],
"banners": [
{
"imageUrl": "https://omni.posplus-crm.com/Omni_FnbItem/storeabc//test.png",
"landingUrl": "https://omni.posplus-crm.com/Omni_FnbItem/storeabc/"
}
],
"cuisine": {
"value": {
"en-US": "Ice Food"
}
},
"inQueueScopes": [
"DINEIN"
],
"reservationScopes": [
"DINEIN"
]
},
"menus": [
{
"menuId": "DINEIN_CAT-01",
"name": {
"value": {
"en-US": "Breakfast"
}
},
"status": "VALID",
"type": "DINEIN",
"minPrepareMinutes": 15,
"categories": [
{
"categoryId": "DINEIN_CAT-01_SUBCAT-01",
"name": {
"value": {
"en-US": "Limited Time Offer"
}
},
"iconUrl": "https://www.example.com/images/antfincdn/cdZOWIR73/0011icon.jpg",
"status": "ACTIVE",
"extendInfo": {
"subtitle": {
"value": {
"en-US": "Main Course"
}
}
},
"items": [
{
"itemId": "300009_1",
"name": {
"value": {
"en-US": "Nachos Deluxe Double Cat01"
}
},
"status": "AVAILABLE",
"saleType": "SINGLE",
"originAmount": {
"currency": "SGD",
"value": "0"
},
"saleAmount": {
"currency": "SGD",
"value": "150"
},
"quantityRule": {
"min": 0,
"max": 9
},
"contents": [
{
"type": "IMAGE",
"scene": "BACKGROUND",
"value": "https://omni.posplus-crm.com/Omni_FnbItem/storeabc/NSDLX_DBBF_AC.png"
},
{
"type": "TEXT",
"scene": "DESCRIPTION",
"value": "{\"value\":{\"en-US\":\"For those who prefer a cheesy meal, indulge in our Nachos Deluxe Double Beef. Served with two beef patties, American cheese, lettuce and a combination of different sauces such as mayonnaise, ketchup and Nachos Cheese sauce!\"}}"
}
],
"extendInfo": {
"subTitle": {
"value": {
"en-US": "delicious chicken"
}
},
"takeAwayFee": {
"currency": "SGD",
"value": 100
},
"serviceSchedules": [
{
"scheduleType": "WEEKLY",
"schedules": {
"MONDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"TUESDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"WEDNESDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"THURSDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"FRIDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"SATURDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
],
"SUNDAY": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
]
}
}
]
},
"modifierGroups": [
{
"groupId": "MODIFIERGROUP-1",
"name": {
"value": {
"en-US": "Add-On"
}
},
"quantityRule": {
"min": 0,
"max": 12
},
"childItems": [
{
"itemId": "201002||300009||@CD",
"name": {
"value": {
"en-US": "Add Beef Patty"
}
},
"saleType": "ADDON",
"originAmount": {
"currency": "SGD",
"value": 0
},
"saleAmount": {
"currency": "SGD",
"value": 350
}
}
]
}
]
},
{
"itemId": "300009_2",
"name": {
"value": {
"en-US": "Nachos Deluxe Double Cat02"
}
},
"status": "AVAILABLE",
"saleType": "SINGLE",
"originAmount": {
"currency": "SGD",
"value": "0"
},
"saleAmount": {
"currency": "SGD",
"value": "1150"
},
"quantityRule": {
"min": 0,
"max": 9
},
"contents": [
{
"type": "IMAGE",
"scene": "BACKGROUND",
"value": "https://omni.posplus-crm.com/Omni_FnbItem/storeabc/NSDLX_DBBF_AC.png"
},
{
"type": "TEXT",
"scene": "DESCRIPTION",
"value": "{\"value\":{\"en-US\":\"For those who prefer a cheesy meal, indulge in our Nachos Deluxe Double Beef. Served with two beef patties, American cheese, lettuce and a combination of different sauces such as mayonnaise, ketchup and Nachos Cheese sauce!\"}}"
}
],
"extendInfo": {
"subTitle": {
"value": {
"en-US": "delicious chicken"
}
},
"takeAwayFee": {
"currency": "SGD",
"value": 100
},
"serviceSchedules": [
{
"scheduleType": "DAILY",
"schedules": {
"FIXED": [
{
"startTime": "00:00+08:00",
"endTime": "23:59+08:00"
}
]
}
}
]
},
"modifierGroups": [
{
"groupId": "MODIFIERGROUP-2",
"name": {
"value": {
"en-US": "Add-On"
}
},
"quantityRule": {
"min": 0,
"max": 12
},
"childItems": [
{
"itemId": "201002||300009||@CD",
"name": {
"value": {
"en-US": "Add Beef Patty"
}
},
"saleType": "ADDON",
"originAmount": {
"currency": "SGD",
"value": 0
},
"saleAmount": {
"currency": "SGD",
"value": 350
}
}
]
}
]
}
]
}
]
}
]
}
}Response
copy
{
"result": {
"resultCode": "SUCCESS",
"resultMessage": "Success.",
"resultStatus": "S"
}
}