updateItem
POST /v2/pds/item/updateItem
With this API call, the SaaS provider or ISV can update an existing item that has been synchronized via the initializeStore or addItem API, such as making small edits or deleting the item.
Note:
- To update an item, itemId is required. Determine which item to update with itemId, storeId, menuId, menuType, categoryId, and saleType.
- There are two scenarios you can expect when updating a specific item:
- The value of saleType is
ADDON
, which means the add-on item to update belongs to a store. Pass storeId to update the specific add-on item.- The value of saleType is
SINGLE
, which means the single item to update belongs to a category. Pass storeId, menuId, menuType, and categoryId to update the specific single item. Before that, make sure the menu information for menuId and menuType has been passed, with at least one record in the store. Also, make sure the category information for categoryId has been passed, with at least one record in the menu.
- For more information, refer to Request parameters.
- To learn how the update works, check below:
- To update a field, pass the field with a new value.
- To delete a field, pass the field with an empty object, for example, "" for String, {} for Object, [] for Array. The required fields in the initializeStore or addItem API cannot be deleted with this API call.
- If you do not pass a field, it will not be updated.
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 |
itemId | String | Yes | Indicates the ID assigned by the SaaS provider or ISV to identify an item.
Note: Passing only the item ID will update multiple items with the same item ID. | "100000000it32" |
saleType | String | Yes | Indicates the sale type of items. Valid values are:
| "SINGLE" |
storeId | String | No | Indicates the ID assigned by the SaaS provider or ISV to identify a store.
Note: Pass this field to update the specific add-on or single item for the specified store. Before that, make sure the Store object has been synchronized via the initializeStore or addStore API and is not deleted. | "000000032" |
menuId | String | No | Indicates the ID of the menu to which the category belongs.
Note: Pass this field to update the specific single item for the menu. Before that, make sure the Menu object has been synchronized via the initializeStore or addMenu API and is not deleted. | "000000032" |
menuType | String | No | Indicates the type of the menu. Valid values are:
Note:
| "PICKUP" |
categoryId | String | No | Indicates the ID assigned by the SaaS provider or ISV to identify the category to which the item belongs.
Note: Pass this field to update the specific single item for the specified category. Before that, make sure the Category object has been synchronized via the initializeStore or addCategory API and is not deleted. | "30000000ca12" |
quantityRule | No | Indicates the quantity rule of the item. Note: To update the quantity rule, pass the entire new quantity rule. We will replace the old rule with the new one. | {"max":1,"min":0} | |
images | Array<String> | No | Indicates a list of image URLs of the item.
Note: To add or update an element of this array, pass the entire new list. We will replace the old list of elements with the new list. | - |
itemTitle | String | No | Indicates the title of the item.
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.
Note: This field should be in English. If multi-language is needed, refer to MultiLanguageDetail. | "fried chicken" |
priceInfo | No | Indicates the price information of the item. Note: To update price information, pass the entire new price information. We will replace the old information with the new one. | - | |
itemStatus | String | No | Indicates the status of the item. Valid values are:
| "SOLDOUT" |
skuPropertyGroups | Array<SkuPropertyGroup> | No | Indicates all possible SKU property groups.
Note:
| - |
skus | Array<Sku> | No | Indicates SKU details, e.g., price.
Note:
| - |
modifierGroupIds | Array<String> | No | Indicates a list of IDs to identify the modifier groups.
Note:
| - |
multiLanguageDetails | Array<MultiLanguageDetail> | No | Indicates the details of the multi-language content.
Note: If the MultiLanguageDetail object you pass already exists, it will be updated, otherwise, it will be added. | [{"column":"itemTitle","languageKey":"en","value":"KFC"}, {"column":"itemTitle","languageKey":"zh_cn","value":"肯德基"}] |
serviceAvailabilityList | Array<ServiceAvailability> | No | Indicates the time range when the item becomes visible to users.
Note:
| - |
takeawayFee | No | Indicates the takeaway charge. Note: By default, takeawayFee is | { "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.
Note: For the sample implementations to specify an item's business rules, see Business rules for Item. | - |
isDeleted | String | No | Indicates whether the item is deleted. The valid value is:
Note: If the value you set is | "DELETED" |
Sku
Field | Data type | Required | Description | Example |
skuId | String | Yes | Indicates the ID assigned by the SaaS provider or ISV to identify an SKU.
Note: To update an SKU, skuId must exist, otherwise the update will fail. | "40000000sk54" |
image | String | No | Indicates the URL of the SKU image.
| - |
skuPropertyPairs | Map<String,String> | No | Indicates the SKU combination.
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 pass.
| { "size": "large", "doneness": "rare" } |
priceInfo | No | Indicates the price information of the SKU. Note: To update price information, pass the entire new price information. We will replace the old information with the new one. | - | |
businessRules | Array<BusinessRule> | No | Indicates the business rules of the SKU, for example, the pricing rules based on different time periods.
Note: For the sample implementations to specify an SKU's business rules, see Business rules for Sku. | - |
Response parameters
Field | Data type | Required | Description |
result | Yes | Indicates the request result, such as status and error codes. |
Result process logic
In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:
Result status | Description |
S | The item is updated successfully. The corresponding result.resultCode is |
U | The status of the request to update the item is unknown. The corresponding result.resultCode is For details, see the Common error codes section. |
F | Failed to update the item. The corresponding result.resultCode and result.resultMessage may vary based on different situations. For details, see the following Error codes section. |
Error codes
Error codes are usually classified into the following categories:
- Common error codes are common for F&B mini program OpenAPIs. Â
Samples
Request
{
"storeId": "lzteststore879856",
"menuId": "055",
"menuType": "PICKUP",
"categoryId": "005",
"itemTitle": "xi1chuadd3item",
"itemId": "single2022010101",
"saleType": "SINGLE",
"images": [
"https://www.example.com/images/uploads/meals/2de02248cee773f990ca.JPG"
],
"itemStatus": "SOLDOUT",
"itemDescription": "delicous",
"quantityRule": {
"min": 0,
"max": 10
},
"priceInfo": {
"originAmount": 100,
"saleAmount": 10,
"currency": "SGD"
},
"modifierGroupIds": [],
"serviceAvailabilityList": [
{
"dayOfWeek": "MONDAY",
"timePeriods": [
{
"description": "timePeriod desc",
"startTime": "09:59",
"endTime": "12:00"
}
]
},
{
"dayOfWeek": "SUNDAY",
"timePeriods": [
{
"description": "timePeriod desc",
"startTime": "09:59",
"endTime": "22:00"
}
]
}
],
"skuPropertyGroups": [
{
"propertyGroupName": "size",
"propertyGroupKey": "27731",
"properties": [
{
"propertyName": "Small",
"propertyValue": "Small"
},
{
"propertyName": "Large",
"propertyValue": "Large"
}
]
},
{
"propertyGroupKey": "27733",
"propertyGroupName": "Level of Spiciness",
"properties": [
{
"propertyName": "No Chilli",
"propertyValue": "No Chilli"
},
{
"propertyName": "Less Chilli",
"propertyValue": "Less Chilli"
},
{
"propertyName": "Extra Chilli",
"propertyValue": "Extra Chilli"
},
{
"propertyName": "Normal Spicy",
"propertyValue": "Normal Spicy"
}
]
}
],
"skus": [
{
"image": "https://wwww.example.com/images/uploads/meals/2cf2de02248cee773f990ca.JPG",
"priceInfo": {
"originAmount": 100,
"saleAmount": 90,
"currency": "SGD"
},
"skuId": "tsku2121",
"skuPropertyPairs": {
"27731": "Small",
"27733": "Normal Spicy"
}
},
{
"image": "https://wwww.example.com/images/uploads/meals/2cf2de4261dfab72cf2de02248cee773f990ca.JPG",
"priceInfo": {
"originAmount": 100,
"saleAmount": 80,
"currency": "SGD"
},
"skuId": "tsku2122",
"skuPropertyPairs": {
"27731": "Large",
"27733": "Normal Spicy"
}
}
]
}
Business rules for Item
The following code excerpts demonstrate the business rules of an item:
Specify price rule
{
"businessRule": [
{
"scene": "PRICE_SCHEDULE",
"ruleData": "[{\"from\": \"2022-09-21T00:00:01+08:00\",\"to\": \"2022-12-31T01:00:01+08:00\",\"weekDays\": [\"MONDAY\",\"WEDNESDAY\",\"TUESDAY\"],\"timeSlot\": {\"startTime\": \"10:00\",\"endTime\": \"14:00\"},\"originAmount\":200,\"saleAmount\":180,\"currency\": \"SGD\"}]"
}
]
}
Specify item status rule
{
"businessRule": [
{
"scene": "ITEM_STATUS_RULE",
"ruleData": "[{\"from\":\"2022-09-01T00:00:01+08:00\",\"to\": \"2022-12-31T01:00:01+08:00\",\"weekDays\": [\"MONDAY\",\"WEDNESDAY\",\"TUESDAY\"],\"timeSlot\": {\"startTime\": \"10:00\",\"endTime\": \"14:00\"},\"itemStatus\":\"AVAILABLE\"}]"
}
]
}
Business rules for Sku
The following code excerpts demonstrate the business rules for an SKU:
Specify price rule
{
"businessRule": [
{
"scene": "PRICE_SCHEDULE",
"ruleData": "[{\"from\": \"2022-09-09T11:00:01+08:00\",\"to\": \"2022-12-31T01:00:01+08:00\",\"weekDays\": [\"MONDAY\",\"WEDNESDAY\",\"TUESDAY\"],\"timeSlot\": {\"startTime\": \"10:00\",\"endTime\": \"15:00\"},\"originAmount\":200,\"saleAmount\":180,\"currency\": \"SGD\"}]"
}
]
}
Specify SKU status rule
{
"businessRule": [
{
"scene": "SKU_STATUS_RULE",
"ruleData": "[{\"from\":\"2022-09-01T00:00:01+08:00\",\"to\": \"2022-12-31T01:00:01+08:00\",\"weekDays\": [\"MONDAY\",\"WEDNESDAY\",\"TUESDAY\"],\"timeSlot\": {\"startTime\": \"10:00\",\"endTime\": \"14:00\"},\"skuStatus\":\"AVAILABLE\"}]"
}
]
}
Response
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
}
}