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

  • Maximum length: 255 characters

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: an individual item that can be ordered by itself.
  • ADDON: a complementary item that can be ordered within a modifier group.

"SINGLE"

storeId

String

No

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

  • Maximum length: 255 characters

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.

  • Maximum length: 255 characters

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:

  • 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:

  • Pass this field to update the specific single item for the specified menu type.
  • Passing only menuType is not supported, which means menuType must belong to a store or a menu.
  • If you pass menuId and menuType, make sure the menu information for these two fields has been synchronized via the initializeStore or addMenu API.

"PICKUP"

categoryId

String

No

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

  • Maximum length: 255 characters
  • Can be Null

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

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.

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

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.

  • 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

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:

  • 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:

  • Before you update this field, see More information for the rule about specifying the skus and skuPropertyGroups parameters.
  • 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.

-

skus

Array<Sku>

No

Indicates SKU details, e.g., price.

  • Maximum size: 200 elements

Note:

  • The Sku object is added or updated based on the skuId value you pass. If the skuId value you pass already exists, the Sku object for this skuId value is updated, otherwise it will be added.
  • Before you update this field, see More information for the rule about specifying the skus and skuPropertyGroups parameters.
  • 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.

-

modifierGroupIds

Array<String>

No

Indicates a list of IDs to identify the modifier groups.

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

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.
  • If a modifier group ID is removed from the item, the ModifierGroup object still exists. To delete a specific ModifierGroup object, call the updateModifierGroup API.
  • modifierGroupIds must belong to the same store.

-

multiLanguageDetails

Array<MultiLanguageDetail>

No

Indicates the details of the multi-language content.

  • Maximum size: 20 elements

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.

  • Maximum size: 20 elements

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.
  • If you pass a new list, the item is only visible to users during the specified time range when the value of itemStatus is AVAILABLE or SOLDOUT.
  • If you pass this field with an empty list, the previous time range is not effective, and the item is always visible to users 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.
  • 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.

-

isDeleted

String

No

Indicates whether the item is deleted.

The valid value is:

  • DELETED: The item is deleted and not visible to users. Once deleted, the item cannot be retrieved. Call the addItem API to add it back.

Note: If the value you set is DELETED but the item ID does not exist, S is returned, which means the request to delete the item is successful.

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

  • Maximum length: 255 characters

Note: To update an SKU, skuId must exist, otherwise the update will fail.

"40000000sk54"

image

String

No

Indicates the URL of the SKU image.

  • Maximum length: 255 characters
  • Can be Null

-

skuPropertyPairs

Map<String,String>

No

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

  • 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

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.

  • Maximum size: 20 elements

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

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 SUCCESS and result.resultMessage is SUCCESS.

U

The status of the request to update the item is unknown.

The corresponding result.resultCode is UNKNOWN_EXCEPTION and result.resultMessage is "An API calling is failed, which is caused by unknown reasons.".

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:

Samples

Request

copy
{
    "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

copy
{
    "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

copy
{
    "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

copy
{
    "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

copy
{
    "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

copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    }
}