List Itemsets
Use this API to list Measurement (Featured and Halo) and Targeting itemsets created in the advertiser account
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. Max size of the array is 25. |
| 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 Note: Currently, only targeting item sets can be shared via Walmart ad center |
| Filter[status] | To get list of itemsets belonging to a specific status | string | N | Enum values: • building • built • draft • failed • invalid • pending |
| Filter[role] | Specifies whether to return itemsets that are either owned by the advertiser or shared with them.
Note: Only one role type can be requested at a time. Responses will include either owned or shared itemsets, not both in the same response. |
| ||
| 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 - List of all itemsets in the account without Filter[role],owned itemsets will be returned in the response
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": 19000, "startIndex": 0, "count": 100
}' Sample Request - List of all itemsets in the account with Filter[role] = OWNEDowned itemsets will be returned in the response
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": 19000, "startIndex": 0, "count": 100, "Filter[role]: "OWNED"
}' Sample Request - List of all itemsets in the account with Filter[role] = SHAREDshared itemsets will be returned in the response
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": 19000, "startIndex": 0, "count": 100, "Filter[role]: "SHARED"
}' 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:
| 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 |
| 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: Auto-generated halo itemset from the same brand(s) as the featured itemset, excluding excluding items already in the featured item setCATEGORY: Auto-generated halo itemset from the same brand and product categories as the featured itemset, excluding items already in the featured item set.CUSTOM: User-defined halo itemsetNONE: no auto Halo associationEnum Values: BRAND, CATEGORY, CUSTOM, NONE Note: This field is applicable only if itemsetType = HALO | string |
| parentFeaturedItemsetId | The featured itemset used to auto-create the halo itemset Note: _This field is applicable only if itemsetType = HALO and haloType is BRAND or CATEGORY | 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 |
| isShared | Indicates whether the itemset is shared with the advertiser (true) or owned by the advertiser (false) Possible Values:
| boolean |
Sample Response Success- List of all itemsets in the account without Filter[role],owned itemsets will be returned in the 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", "isShared": false }, { "itemsetId": 2, "name": "string", "status": "FAILED", "class": "MEASUREMENT", "editable": "true", "creationDate": "string", "lastUpdatedDate": "string", "description": "string", "itemsetType": "FEATURED", "type": "ITEM", "details": "string", "source": "INTERNAL" , "isShared": false }, { "itemsetId": 10270756, "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", "isShared": false } ]
}
Sample Response Failure - List of all itemsets in the account without Filter[role], owned itemsets will be returned in the response
{ "code": "failure", "details": [ "NO_RECORD_FOUND" ]
}
Sample Response Success - List of all itemsets in the account with Filter[role] = OWNED, owned itemsets will be returned in the 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", "isShared": false }, { "itemsetId": 2, "name": "string", "status": "FAILED", "class": "MEASUREMENT", "editable": "true", "creationDate": "string", "lastUpdatedDate": "string", "description": "string", "itemsetType": "FEATURED", "type": "ITEM", "details": "string", "source": "INTERNAL" , "isShared": false }, { "itemsetId": 10270756, "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", "isShared": false } ]
}
Sample Response Failure - List of all itemsets in the account with Filter[role] = OWNED, owned itemsets will be returned in the response
{ "code": "failure", "details": [ "NO_RECORD_FOUND" ]
}
Sample Response Success - List of all itemsets in the account with Filter[role] = SHARED, shared itemsets will be returned in the 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", "isShared": true }, { "itemsetId": 2, "name": "string", "status": "FAILED", "class": "MEASUREMENT", "editable": "true", "creationDate": "string", "lastUpdatedDate": "string", "description": "string", "itemsetType": "FEATURED", "type": "ITEM", "details": "string", "source": "INTERNAL" , "isShared": true }, { "itemsetId": 10270756, "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", "isShared": true } ]
}
Sample Response Failure - List of all itemsets in the account with Filter[role] = SHARED, shared itemsets will be returned in the response
{ "code": "failure", "details": [ "NO_RECORD_FOUND" ]
}
Updated about 20 hours ago