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 |
|
| 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 |
| ItemsetType | ItemsetType value can either be featured or halo. this field is needed while updating measurement class itemset | string | N |
|
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 |
Rules/Validations
- An item cannot be removed from a featured itemset if it is associated with any creatives used in the ad groups of the campaign.
- Itemset updates are allowed only if the current status is BUILT or INVALID.
- Featured itemsets can only be item-based.
- Halo and targeting itemsets can be item-based, brand-based, category-based, or hybrid.
- 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.
- Changing the itemset type is not allowed. Example, you cannot change an itemset from item-based to brand-based or category-based or hybrid and vice versa
- expression Rules
- expression object cannot be used in combination with items or brands array fields
- Only the OR gate is supported in expression object in the current API version.
- Nested logical gates are not supported in the current API version.
- Rules by Itemset Type
- Brand-based itemsets: should have list of brands specified either in brands array or expression object.; items array must be empty or null.
- Item-based itemsets: should have list of items specified either in items array or expression object.; brands array must be empty or null.
- Category-based itemsets: should have list of categories in expression object.; items and brands arrays must be empty or null.
- Hybrid-based itemsets: must include either a non-empty expression object
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 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": "measurement", "type": "brand", "editable": "true", "brands": [ "abc", "xyz" ] } ]' Sample Request: Update 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 Itemset with brand based 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": "measurement", "type": "brand", "editable": "true", "expression": { "or": [ { "type": "brand", "value": { "name": "pepsi" } }, { "type": "brand", "value": { "name": "red bull" } } ] } }
]' Sample Request: Update itemset with 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 Itemset with 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 | array |
| itemsetId | Unique identifier for the itemset | 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.
Itemsets Update Matrix
Fields that can be updated using PUT/api/v1/itemset
| API Field Name | Display Label | Draft | Building | Built | Failed | Invalid | Pending | Notes |
|---|---|---|---|---|---|---|---|---|
| type | TYPE | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | Immutable |
| name | Itemset Name | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | Editable only when Built or Invalid |
| expression | Itemset definition with list of Brands, Items, Categories | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | Can add/remove only in Built or Invalid states and if editable = true Once updated, the itemset build process will automatically restart, and the audience status will transition to PENDING. |
| editable | Editable Flag | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | Immutable |
| description | Itemset Description | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | Same as above |
| class | Class | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | Immutable |
Sample Response - Update Itemsets using Brands
[ { "code": "success", "details": ["string"], "itemsetId": 123 } ] Sample Response - Update Itemsets with Items List
[ { "code": "success", "details": ["string"], "itemsetId": 123 } ]
Sample Response -Update Itemset with brand based expression
[ { "code": "success", "details": ["string"], "itemsetId": 123 } ]
Sample Response -Update Itemset with category expression
[ { "code": "success", "details": ["string"], "itemsetId": 123 } ]
Sample Response -Update Itemset with hybrid expression
[ { "code": "success", "details": ["string"], "itemsetId": 123 } ]
Sample Response -Update Itemset with attribute category in expression
[ { "code": "success", "details": ["string"], "itemsetId": 123 } ]
Updated 3 days ago