addItem
POST /v2/pds/item/addItem
With this API call, the SaaS provider or ISV can add a single item or an add-on item to the current items that have been synchronized via the initializeStore API.
Note: There are two scenarios you can expect when adding an item:
- The value of saleType is
ADDON, which means the add-on item to add belongs to a store. Pass storeId and itemId to add the specific add-on item. modifierGroupIds must belong to the same store.- The value of saleType is
SINGLE, which means the single item to add belongs to a category. Pass storeId, itemId, menuId, menuType, and categoryId to add 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. modifierGroupIds must belong to the same store.For more information, refer to Request parameters.
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 |
requestId | String | Yes | Indicates the unique ID assigned by the SaaS provider or ISV to identify a request of adding an item.
Note: This field is an API idempotency field. For the addItem requests using the same requestId value, our sever must return the same result. For details about API idempotency, see the Idempotency chapter. | "item_2022012111061234567890" |
item | Yes | Indicates the details of the item to add. | - |
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 |
A | The request for adding the item is accepted by us. The corresponding result.resultCode and result.resultMessage may vary based on different situations. For details, see the following Error codes section. |
S | The item is added successfully. The corresponding result.resultCode is |
U | The status of the request to add the item is unknown. The corresponding result.resultCode is For details, see the Common error codes section. |
F | Failed to add 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
{
"requestId": "5376658ba53c48c9aded4f6f46625891",
"item": {
"storeId": "ST879856",
"menuId": "055",
"menuType": "PICKUP",
"categoryId": "005",
"itemId": "single2022010101",
"saleType": "SINGLE",
"itemTitle": "Stir Fried Hor Fun",
"images": [
"https://wwww.example.com/images/uploads/meals/2de02248cee773f990ca.JPG",
"https://wwww.example.com/images/uploads/meals/cf2de022f990ca.JPG"
],
"itemStatus": "AVAILABLE",
"itemDescription": "nice",
"quantityRule": {
"min": 0,
"max": 100
},
"priceInfo": {
"originAmount": 100,
"saleAmount": 90,
"currency": "SGD"
},
"modifierGroupIds": [
"tpgroup222"
],
"serviceAvailabilityList": [
{
"dayOfWeek": "MONDAY",
"timePeriods": [
{
"description": "timePeriod desc",
"startTime": "09:59",
"endTime": "22:00"
}
]
},
{
"dayOfWeek": "SUNDAY",
"timePeriods": [
{
"description": "timePeriod desc",
"startTime": "09:59",
"endTime": "22:00"
}
]
},
{
"dayOfWeek": "SUNDAY",
"timePeriods": [
{
"description": "timePeriod desc",
"startTime": "09:59",
"endTime": "22:00"
}
]
},
{
"dayOfWeek": "TUESDAY",
"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://www.example.com/images/uploads/meals/de02248cee773f990ca.JPG",
"priceInfo": {
"originAmount": 100,
"saleAmount": 90,
"currency": "SGD"
},
"skuId": "tsku2121",
"skuPropertyPairs": {
"27731": "Small",
"27733": "Normal Spicy"
}
},
{
"image": "https://www.example.com/images/uploads/meals/f2de02248cee773f990ca.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"
}
}