Update Itemsets

Use this API to update both Measurement 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

📘

URL: ​ PUT/api/v1/itemset

Request Parameters

ParameterNotesTypeRequiredPossible Values
advertiserIdID of the advertiserintegerYUnique numeric identifier
itemsetIdID of itemsetintegerYUnique numeric identifier
nameName of itemsetstringNName of itemset
descriptionDescription of itemsetstringNString value
classspecifies 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.
stringNMEASUREMENT, TARGETING. (Default value: MEASUREMENT)
typeSpecifies whether the itemset being created is based on a list of items, brands, categories, or a combination of these elements

Note: Featured itemsets can be only item based
stringYValues:
  • item
  • brand
  • category
  • hybrid
editableIndicates whether the itemset is configured to be edited post creation
Note: It supports only true for now
stringNValue: 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 stringsRequired if type=brand and no brand based expression addedBrand 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

here

.
array of objects Required if type=item and no item based expression addedValues:
  • id
  • itemType
expressionLogical expression defining the itemset criteria. “expression” object specifies logical OR operation between Item, Brand and Category
The expression objects are detailed

here


Special rules:
  • For items with catalog = UNIVERSAL in POST /api/v1/items/list, only GTIN should be used
  • If catalog is not UNIVERSAL, other itemType values (STORES, ONLINE, UPC) are allowed.
  • Values for attributes.type and attributes.values applicable for a category can be retrieved from POST/api/v1/taxonomies/list
jsonRequired if neither items nor brands are passedRefer details of expression object below

Note: At least one of items, brands, or expression is required.

items Objects

ParametersNotesTypeRequiredPossible Values
idUnique identifier for the item

Note: For items with catalog = UNIVERSAL in POST /api/v1/items/list, use GTIN IDs
stringYUnique ID value
itemTypeType of the item IDstringYgtin, upc, stores, onli

expression Objects

Each block in the or array represents a targeting clause. At least one clause must be provided.

ParametersNotesTypeRequiredPossible Values
typeType of expression.Ystringitem, brand,category
valueObject specifying the matching criteria. Structure depends on the typeYjson

value object (based on type) When type is item:

ParametersNotesTypeRequiredPossible Values
itemIdUnique identifier for the item

Note: For items with catalog = UNIVERSAL in POST /api/v1/items/list, use GTIN IDs
Ystring
itemTypeType of the item ID.Ystringgtin, upc, stores, online

value object (based on type) When type is brand:

ParametersNotesTypeRequiredPossible Values
nameBrand nameYstring

value object (based on type) When type is category:

use POST /api/v1/taxonomies/list to get details of category and available attributes

ParametersNotesTypeRequiredPossible Values
nameName of the category. (This field case sensitive)Ystring
levellevel of the category hierarchyYintegerAllowed values: 1,2,3
attributesAdditional filters for category-based selection. Each object inside the “attributes” array contains:Narray

attributes Objects

ParametersNotesTypeRequiredPossible Values
typeType of attributeYstringAllowed values: age_group, diet_type, allergens_not_contained, skin_type, item_gender, clothing_size_group, ib_ingredient_preference, ingredient_properties
valuesList of values for the attribute.Yarray

Headers

Header NameDescriptionRequiredValues
AuthorizationThe token will provide you the access to the API. It is same for all advertisers you access through the API.YPlease utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
WM_CONSUMER.IDWe will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.   YPlease 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_SIGNATUREAuth signature as an API key.YUse the signature generator code from Getting Started Guide to generate this value
WM_SEC.KEY_VERSIONWe will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API.Y1
WM_CONSUMER.intimestampTimestamp for which the auth signature is generated. Use Unix epoch format for the timestamp.YUse 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": "targeting", "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 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 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 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 } } ] } } ]' 

Response

ElementDescriptionType
codeThe response code can have following values:
  • success
  • failure

Click here for more information about Status Codes and Errors
string
detailsDetails of the error if value of response code is failingstring
itemsetIdID of the item setinteger

Update Itemset Success Response

[ {   "code": "success",      "details": "string",      "itemsetId": 123 } ] 

Update Itemset Failure Response

{ "code": "failure", "details": ["error code"]
}