Update Itemsets
Use this API to update both Measurement (Featured & Halo) and Targeting itemsets
Note:
- PUT API requests will overwrite all current values and are not intended to be used as incremental updates like PATCH operations
- Halo itemsets that have been auto generated, cannot be updated
- Updating Featured (measurement) itemsets - You can only update item based Featured (measurement) itemsets. Older Featured (measurement) itemset that might be brand based cannot be updated unless it's converted to a brand based itemset
- This endpoint initiates an asynchronous process to update an itemset. While a unique itemsetId is returned immediately, it does not indicate that the itemset is fully built or ready for use. You must use the POST/api/v1/itemsets/list endpoint to check the status of the itemset before using it further.
URL: PUT/api/v1/itemset
Request Parameters
| Parameter | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| advertiserId | ID of the advertiser | integer | Y | Unique numeric identifier |
| itemsetId | ID of itemset | integer | Y | Unique numeric identifier |
| name | Name of itemset | string | N | Name of itemset |
| description | Description of itemset | string | N | String value |
| class | specifies whether the itemset is used for measurement or targeting Note: The 'class' field cannot be modified during an update; any value provided for it in the request will be ignored. | string | N | MEASUREMENT, TARGETING. (Default value: MEASUREMENT) |
| type | Specifies whether the itemset being created is based on a list of items, brands, categories, or a combination of these elements Note:
| string | Y | Values:
|
| editable | Indicates whether the itemset is configured to be edited post creation Note: It supports only true for now | string | N | Value: true |
| brands Note: Relevant only when creating a brand-based itemset (where type = brand) | List of brands to be added to the itemset. This is an array for brand names. Note: Specify the brand names. | array of strings | Conditional. Required if type=brand and no brand based expression added | Brand names |
| items Note: Relevant only when creating an item-based itemset (where type = item)_ | List of items to be added to the itemset. The items objects are detailed . | array of objects | Conditional. Required if type=item and no item based expression added | Values:
|
| expression | Logical expression defining the itemset criteria. “expression” object specifies logical OR operation between Item, Brand and Category The expression objects are detailed Special rules:
| json | Conditional.Required if neither items nor brands are passed | Refer details of expression object below |
Note:
- At least one of items, brands, or expression is required.
- Only Itemsets with editable = true can be updated
- Only name, description, and list of items, brands or categories in the itemset metadata can be updated.
- class and type fields are immutable. As a result, existing itemsets created with brand or hybrid (featured) measurement cannot be updated.
items Objects
| Parameters | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| id | Unique identifier for the item Note: For items with catalog = UNIVERSAL in POST /api/v1/items/list, use GTIN IDs | string | Y | Unique ID value |
| itemType | Type of the item ID | string | Y | gtin, upc, stores, onli |
expression Objects
Each block in the or array represents a targeting clause. At least one clause must be provided.
| Parameters | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| type | Type of expression. | Y | string | item, brand,category |
| value | Object specifying the matching criteria. Structure depends on the type | Y | json |
value object (based on type) When type is item:
When type is item:| Parameters | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| itemId | Unique identifier for the item Note: For items with catalog = UNIVERSAL in POST /api/v1/items/list, use GTIN IDs | Y | string | |
| itemType | Type of the item ID. | Y | string | gtin, upc, stores, online |
value object (based on type) When type is brand:
When type is brand:| Parameters | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| name | Brand name | Y | string |
value object (based on type) When type is category:
When type is category:use POST /api/v1/taxonomies/list to get details of category and available attributes
| Parameters | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| name | Name of the category. (This field case sensitive) | Y | string | |
| level | level of the category hierarchy | Y | integer | Allowed values: 1,2,3 |
| attributes | Additional filters for category-based selection. Each object inside the “attributes” array contains: | N | array |
attributes Objects
| Parameters | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| type | Type of attribute | Y | string | Allowed values: age_group, diet_type, allergens_not_contained, skin_type, item_gender, clothing_size_group, ib_ingredient_preference, ingredient_properties |
| values | List of values for the attribute. | Y | array |
Headers
| Header Name | Description | Required | Values |
|---|---|---|---|
| Authorization | The token will provide you the access to the API. It is same for all advertisers you access through the API. | Y | Please utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide |
| WM_CONSUMER.ID | We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API. | Y | Please use the generated ConsumerId shared with you at the time of partner onboarding. Refer to the Getting Started Guide for more information |
| WM_SEC.AUTH_SIGNATURE | Auth signature as an API key. | Y | Use the signature generator code from Getting Started Guide to generate this value |
| WM_SEC.KEY_VERSION | We will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API. | Y | 1 |
| WM_CONSUMER.intimestamp | Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp. | Y | Use the signature generator code from Getting Started Guide to generate this value |
Sample Request: Update Targeting Itemsets using Brands
curl -X PUT \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "itemsetId": 123, "name": "string", "description": "itemset description", "class": "targeting", "type": "brand", "editable": "true", "brands": [ "abc", "xyz" ] } ]' Sample Request: Update Featured Itemsets with Items List
ccurl -X PUT \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "itemsetId": 123, "name": "string", "description": "itemset description", "class": "measurement", "type": "item", "editable": "true", "items": [ { "id": 123456789, "itemType": "gtin" }, { "id": 123456790, "itemType": "gtin" } ] } ]' Sample Request: Update Targeting Itemsets using Brands Expression
curl -X PUT \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "itemsetId": 123, "name": "string", "description": "itemset description", "class": "targeting", "type": "brand", "editable": "true", "expression": { "or": [ { "type": "brand", "value": { "name": "pepsi" } }, { "type": "brand", "value": { "name": "red bull" } } ] } }
]' Sample Request: Update Targeting itemsets using category Expression
curl -X PUT \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "itemsetId": 123, "name": "string", "description": "itemset description", "class": "targeting", "type": "category", "editable": "true", "expression": { "or": [ { "type": "category", "value": { "name": "baby food", "level": 1 } }, { "type": "category", "value": { "name": "Quilting Basting Guns", "level": 1 } } ] } }
]' Sample Request: Update Targeting Itemsets using Hybrid Expression
Note:
- Please use 'gtin' as the "itemType" in the call, if the type of catalog is returned "universal " in the response of the call POST/api/v1/items/list
- type should be "hybrid" if we are adding a different type to the original itemset type
curl -X PUT \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "itemsetId": 123, "name": "string", "description": "itemset description", "class": "targeting", "type": "hybrid", "editable": "true", "expression": { "or": [ { "type": "item", "value": { "itemId": "123456789", "itemType": "gtin" } }, { "type": "item", "value": { "itemId": "123456789", "itemType": "gtin" } }, { "type": "brand", "value": { "name": "pepsi" } }, { "type": "category", "value": { "name": "baby food", "level": 1 } } ] } } ]' Sample Request: Update Itemsets using Category Expression with Attributes
curl -X PUT \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "itemsetId": 123, "name": "string", "description": "itemset description", "class": "targeting", "type": "category", "editable": "true", "expression": { "or": [ { "type": "category", "value": { "name": "baby food", "level": 1, "attributes": [ { "type": "age_group", "values": [ "Infant", "toddler" ] }, { "type": "skin_type", "values": [ "all", "sensitive" ] } ] } }, { "type": "category", "value": { "name": "Quilting Basting Guns", "level": 1 } } ] } }
]' Update Custom Halo Itemsets with brand and category in expression
curl -X PUT \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "itemsetId": 123463041, "name": "test_Item_no_halo1", "description": "sample itemset - 001", "advertiserId": 16273800, "type": "hybrid", "expression": { "or": [ { "type": "brand", "value": { "name": "gerber" } }, { "type": "brand", "value": { "name": "onesies" } }, { "type": "category", "value": { "name": "Toys & Games - new", "level": 1 } }, { "type": "category", "value": { "name": "Pet Supplies", "level": 10 } } ] } }
]' }
}
Update Custom Halo Itemsets with list of brands
curl -X PUT \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 16273800, "itemsetId": 123463041, "name": "Demo itemset-3 - V3-001", "description": "sample itemset - V3-002", "type": "brand", "class": "MEASUReMENT", "brands": [ "gerber", "onesies" ] }
]'
Response
| Element | Description | Type |
|---|---|---|
| code | The response code can have following values:
Click here for more information about Status Codes and Errors | string |
| details | Details of the error if value of response code is failing | string |
| itemsetId | ID of the item set | integer |
⚠️ Important: The presence of an itemsetId in the response does not mean the itemset is fully built. Use the `POST/api/v1/itemsets/list endpoint to track its status.
Update Itemset Success Response
[ { "code": "success", "details": "string", "itemsetId": 123 } ] Update Itemset Failure Response
{ "code": "failure", "details": ["error code"]
}
Updated 4 months ago