HomeGuidesAPI Reference
Guides

Create Itemsets

Use this API to create item sets

📘

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
typeType of itemset being createdstringYValues:
  • 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 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
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
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 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": "measurement", "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": "12345679", "itemType": "gtin" } }, { "type": "item", "value": { "itemId": "123456789", "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
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: Create Itemsets

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

Updated 23 days ago