Create Itemsets
Use this API to create Measurement (Featured and Halo) and Targeting itemsets
Note: This endpoint initiates an asynchronous process to build 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/listendpoint to check the status of the itemset before using it further.
URL: POST/api/v1/itemset
Request Parameters
| Parameter | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| advertiserId | ID of the advertiser | integer | Y | Unique numeric identifier |
| name | Name of itemset | string | Y | Name of itemset |
| description | Description of itemset | string | N | String value |
| class | Indicates whether the itemset is used for measurement or targeting | string | N | Values: measurement, targeting Note: Default value is measurement |
| type | Specifies whether the itemset being created is using 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 | string | N | Value: 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 . | array of objects | Conditional. Required if type=item and no item based expression added | Values:
|
| 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 | list 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 Special rules:
| Conditional.Required if neither items nor brands are passed | ||
| itemsetType | Specifies whether the itemset is FEATURED or HALO This field is applicable only if class = MEASUREMENT and ignored when class = TARGETING | string | N |
|
Note: Either one of items, brands or expression is required
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, online |
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 object
| 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 |
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 Requset: Create Itemsets Using List of Items
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 Targeting 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 Targeting 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 } } ] } }
]
' Create Custom Halo Itemset 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", "itemsetType": "HALO", "type": "BRAND", "editable": "true", "expression": { "or": [ { "type": "BRAND", "value": { "name": "pepsi" } }, { "type": "BRAND", "value": { "name": "red bull" } } ] } }
]
'
Create Halo Itemset using list of categories
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": "CATEGORY", "itemsetType": "HALO", "editable": "true", "expression": { "or": [ { "type": "CATEGORY", "value": { "name": "baby food", "level": 1 } }, { "type": "CATEGORY", "value": { "name": "Quilting Basting Guns", "level": 1 } } ] } }
]' Create Halo Itemset using hybrid 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", "itemsetType": "HALO", "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 } } ] } }
]' 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 | string |
| itemsetId | ID of the item set | 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.
Create Itemset Success Response
[ { "code": "success", "details": "string", "itemsetId": 1234 } ] Create Itemset Failure Response
{ "code": "failure", "details": ["error code"]
}
Updated 4 months ago