List Itemsets
Use this API to list Measurement (Featured and Halo) and Targeting itemsets created in the advertiser account
Note: The API currently provides only a list of measurement itemsets that were successfully built
URL: POST/api/v1/itemsets/list
Request Parameters
| Parameter | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| advertiserId | ID of the advertiser | integer | Y | Unique numeric identifier |
| Filter[itemsetId] | List of itemset IDs Note: max size of the array is 25 | array | N | Unique itemset IDs |
| Filter[lastModifiedDate] | To get list of itemsets modified on or after this date | date | N | date value. Date should be in format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX |
| Filter[class] | To get list of itemsets belonging to a specific class | string | N | Enum values: • measurement • targeting |
| Filter[status] | To get list of itemsets belonging to a specific status | string | N | Enum values: • building • built • draft • failed • invalid • pending |
| startIndex | You can use this parameter to fetch specific number of itemsets from the available list. This indicates the starting position of the list | string | N | A range of 0 to length of the list minus one Example: To return the first ten itemsets entries, set startIndex=0 and count=10 |
| count | You can use this parameter in combination with startIndex to fetch specific number of itemsets from the available list. | integer | N | Number of itemsets that you want to fetch in response to this call Note: defaultCount=100, maxCount = 100, minCount = 1 Example: To return the first ten itemset entries, set startIndex=0 and count=10 |
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 Request
curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemsets/list' \ --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, "Filter[itemsetId]": [1, 2], "Filter[lastModifiedDate]": "string", "Filter[class]": "measurement", "Filter[status]": "built", "startIndex": 0, "count": 10 } ' Response
| Element | Description | Type |
|---|---|---|
| code | Possible values of response code: • success • failure | string |
| totalResults | Total number of rows returned in the response | integer |
| itemsets | List of itemset objects. Each object represents a distinct itemset The itemsets objects are detailed | array of objects |
itemsets Objects
| Element | Description | Type |
|---|---|---|
| itemsetId | unique identifier for item set | integer |
| name | Name of the itemset | string |
| description | description of the itemset | string |
| status | Build status of the itemset Enum Values: DRAFT, BUILDING, FAILED, BUILT, INVALID, PENDING | string |
| details | Details of the error while building an itemset. Note: This field is returned only if the value of 'status' field is FAILED in API response | string |
| class | Itemset classification Enum Values: 'MEASUREMENT', 'TARGETING' | string |
| editable | Indicates if the itemset is editable Values: true, false Note: editable will be 'false' for auto generated halo itemsets | boolean |
| creationDate | Timestamp when the itemset was created (ISO-8601 format) ISO 8601 timezone format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX | string |
| lastUpdatedDate | Timestamp when the itemset was last updated (ISO-8601 format) ISO 8601 timezone format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX | string |
| creationType | Indicates whether halo itemset was created automatically or manually. Enum Values: AUTO, MANUAL Note:This field is applicable only if itemsetType = HALO | string |
| itemsetType | Indicates whether the itemset is FEATURED or HALO Enum Values: FEATURED, HALO Note: This field is applicable only if class = MEASUREMENT | string |
| haloType | Indicates whether the halo itemset is BRAND (items belonging to the same brand that are not included in the featured itemset) or CATEGORY (items belonging to same brand and category that are not included in the featured itemset)Enum Values: BRAND, CATEGORY Note: This field is applicable only if itemsetType = HALO | string |
| parentFeaturedItemsetId | Only for auto generated HALO itemsets. Links to a parent FEATURED itemset. Note: This field is applicable only if itemsetType = HALO and creationType = AUTO | string |
| type | Itemset content type. Indicates whether the itemset was built using list of Items, brands, categories or if it's a combination of these Enum Values: ITEM, BRAND, CATEGORY, HYBRID | string |
| source | Indicates where the itemset was created from Possible Values: Any valid source.
| string |
List Itemset Success Response
{ "code": "success", "totalResults": 3, "itemsets": [ { "itemsetId": 1, "name": "string", "status": "BUILT", "class": "MEASUREMENT", "editable": "true", "creationDate": "string", "lastUpdatedDate": "string", "description": "string", "itemsetType": "FEATURED", "type": "ITEM", "source": "INTERNAL" }, { "itemsetId": 2, "name": "string", "status": "FAILED", "class": "MEASUREMENT", "editable": "true", "creationDate": "string", "lastUpdatedDate": "string", "description": "string", "itemsetType": "FEATURED", "type": "ITEM", "details": "string", "source": "INTERNAL" }, { "itemsetId": 3, "status": "BUILT", "name": "itemset_halo2", "description": "Halo ItemSet", "editable": false, "creationDate": "2025-01-01T15:19:10.000-05:00", "lastUpdatedDate": "2025-03-05T08:38:10.000-05:00", "source": "INTERNAL", "type": "ITEM", "itemSetType": "HALO", "class": "MEASUREMENT", "parentFeaturedItemsetId": 123, "haloType": "CATEGORY", "creationType": "AUTO" } ]
}
List Itemset Failure Response
{ "code": "failure", "details": [ "NO_RECORD_FOUND" ]
}
Updated 1 day ago