HomeGuidesAPI Reference
Guides

Update Itemsets

Use this API to update item sets

Note: PUT API requests will overwrite all current values and are not intended to be used as incremental updates like PATCH operations
The 'class' field cannot be modified during an update; any value provided for it in the request will be ignored.

📘

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
classIndicates whether the itemset is used for measurement or targetingstringNValue: measurement
typeType of itemset being createdstringYValues:
  • item
  • brand
editableIndicates whether the itemset is configured to be edited post creationstringNValue: 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.		arrayRequired if type=brandBrand names
items
Note: Relevant only when creating an item-based itemset (where type = item)_		List of items to be added to the itemset. This is an array element with following parameters:
  • id
    • data type: integer
    • Required: Y
  • itemType
    • data type: string
    • Required: Y
    • Value: gtin, stores, online, upc
arrayRequired if type=itemValues:
  • id
  • itemType
expression“expression” object specifies logical OR operation between Item, Brand and Category
  • “or” – array of conditions evaluated with OR logic. Each object within the OR array represents a filter condition
    • “type”(required) - specifies the type of filter. Allowed values: CATEGORY, BRAND, ITEM.
    • “value” (required) - Contains details related to the filter type. Fields depends on value of “type”
      • If type = “ITEM” – value contains following fields
        • “itemId”(required) – Unique identifier for the item.
        • “itemType”(required) - Type of ID passed. Allowed values: GTIN, STORES, ONLINE, UPC
      • If type = “BRAND” – value contains following fields
        • “name” (required) – Name of the brand
      • If type = “CATEGORY” – value contains following fields
        (use POST /api/v1/taxonomies/list to get details of category and available attributes)
        • “name” (required) – Name of the category. (This field is case sensitive)
        • “level” (required) – level of the category hierarchy. Allowed values – 1,2,3
        • “attributes” (optional)  - Additional filters for category-based selection. Each object inside the “attributes” array contains:
          • “type” (required) - Type of attribute (Allowed values: age_group, diet_type, allergens_not_contained, skin_type, item_gender, clothing_size_group, ib_ingredient_preference, ingredient_properties).
          • “values” (required) - List of values for the attribute.

    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

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": "measurement", "type": "brand", "editable": "true", "brands": [ "abc", "xyz" ] } ]'

Sample Request: Update Itemsets

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": "measurement", "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
codePossible values of response code:
  • success
  • failure
string
detailsDetails of the error if value of response code is failingstring
itemsetIdID of the item setinteger

Sample Response

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

Updated 23 days ago