HomeGuidesAPI Reference
Guides

Create Itemsets

Use this API to create Measurement and Targeting itemsets

📘

URL: ​ POST/api/v1/itemset

Request Parameters

ParameterNotesTypeRequiredPossible Values
advertiserIdID of the advertiserintegerYUnique numeric identifier
nameName of itemsetstringYName of itemset
descriptionDescription of itemsetstringNString value
classIndicates whether the itemset is used for measurement or targetingstringNValues: measurement, targeting

Note: Default value is measurement
typeSpecifies whether the itemset being created is using list of Items, brands, categories or a combination of these elements
Note: Featured itemsets can be only item based		stringYValues:
  • item
  • brand
  • category
  • hybrid


Note: type = category is not supported for class = measurement
editableIndicates whether the itemset is configured to be edited post creationstringNValue: true
items
Note: Relevant only when creating an item-based itemset (where type = item)		List of valid items to be added to the itemset.
The items objects are detailed

here

.		array of objectsRequired if type=item and no item based expression addedValues:
  • id
  • itemType
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 addedlist of valid brands as String, required when type as BRAND & no brand-based expression added
expression“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

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 ID.stringYgtin, upc, stores, online

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 object

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 Requset: Create Itemsets

curl -X POST \
'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, "name": "string", "description": "itemset description", "class": "measurement", "type": "item", "editable": true, "items": [ { "id": 123456789, "itemType": "gtin" }, { "id": 123456790, "itemType": "gtin" } ] } ]'

Sample Request: Create Itemsets using Brands

curl -X POST \ '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, "name": "string", "description": "itemset description", "class": "measurement", "type": "brand", "editable": "true", "brands":["abc", "xyz"] } ]'

Sample Request: Create Itemsets using Brand expression

curl -X POST \
'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, "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: Create Itemsets using category expression

curl -X POST \
'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, "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: Create 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

curl -X POST \
'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, "name": "string", "description": "itemset description", "class": "targeting", "type": "hybrid", "editable": "true", "expression": { "or": [ { "type": "item", "value": { "itemId": "12389", "itemType": "gtin" } }, { "type": "item", "value": { "itemId": "12589", "itemType": "gtin" } }, { "type": "brand", "value": { "name": "pepsi" } }, { "type": "category", "value": { "name": "baby food", "level": 1 } } ] } } ]'

Sample Request: Create Itemsets using category expression with attributes

curl -X POST \
'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, "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

Create Itemset Success Response

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

Create Itemset Failure Response

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

Updated 1 day ago