Retrieve item set expression metadata
Retrieve Item Set expressions to review brand, category, and product selection logic.
Overview
Use this endpoint to review brand selections, category hierarchy, category attributes, and referenced child Item Sets.
This endpoint returns configuration logic rather than the complete list of products included in an Item Set.
Availability
Supported for Onsite Display only.
Only Item Sets with status=BUILT are supported.
How it works
Retrieve the expression for a specific Item Set to understand how its product selection criteria were defined.
Identify Item Set
Retrieve the Item Set ID and confirm its status is BUILT.
Request expression
Submit the advertiser ID and a single Item Set ID.
Review criteria
Inspect returned brand, category, or child Item Set references.
Continue workflow
Validate configuration or retrieve underlying items when needed.
Before you begin
- Valid
advertiserId - Valid
itemsetId - Item Set has reached
status=BUILT
Use List Item Sets to retrieve the Item Set ID and verify its build status.
Endpoint
POST /api/v1/itemset/expression
POST /api/v1/itemset/expressionRequest details
How this request is used
Use this endpoint to retrieve the product selection logic for an existing Item Set.
Common uses include:
- Reviewing the criteria used to define an Item Set
- Displaying brand and category selections in a partner platform
- Validating expression configuration
- Identifying child Item Sets referenced by a Hybrid expression
Key fields and behaviors
Filter[itemsetId]
Identifies the item set whose expression is being retrieved. Accepts a single item set ID.
Important behavior
- Only one Item Set can be requested at a time.
- The Item Set must have reached
BUILTstatus. - Expression metadata may take approximately 3–5 minutes to become available after a successful build, or longer for larger Item Sets.
- This endpoint retrieves expression configuration. It does not update the Item Set or return its complete product contents.
Expression metadata availabilityAn Item Set must reach
BUILTstatus before its expression can be retrieved.Expression metadata may not be immediately available after build completion. Allow approximately 3–5 minutes, or longer for larger Item Sets, before retrying the request.
Sample request
Retrieve Item Set expression
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset/expression' \ --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]": 13240239 }'Response details
What this response returns
The response returns the Item Set identifier and the expression defining its product selection criteria.
Depending on the Item Set's configuration, the expression may contain brand names, category hierarchy information, category attributes, or references to child Item Sets.
Key fields to use
code
Indicates whether the request succeeded or faileditemsetId
Identifies the Item Set whose expression was retrievedexpression
Object containing the returned product selection criteriaexpression.or
Array containing the expression clausestype
Identifies the expression node type:ITEMSET,BRAND, orCATEGORYvalue
Object containing the selection criteria associated with each nodevalue.id
Identifies a referenced child Item Set whentype=ITEMSETvalue.name
Identifies a brand or category name, depending on the node typevalue.level
Identifies the category hierarchy level whentype=CATEGORYvalue.attributes
Contains additional category selection attributes, when applicabledetails
Provides additional information about the request, including errors when applicable.message
Optional. High-level, human-readable summary of the error when available.errors
Detailed information about one or more errors. This is an array object with fields:field,errorType,description
Error Handling
If the request or an individual item fails, the response includes error information to help identify the issue and determine the corrective action. Use errorType for the error condition, field for the affected request field when applicable, and description for an explanation of the error and, when available, guidance on how to resolve it.
For the complete error response schema and endpoint-specific response definitions, see the API Reference. For guidance on HTTP status codes and how clients should handle them, see API status codes and error handling.
Understand expression node types
Each entry in expression.or identifies one selection criterion.
Node type | What it represents | Returned information |
|---|---|---|
ITEMSET | A child Item Set created from a list of individual products | Child Item Set ID |
BRAND | A brand included in the selection criteria | Brand name |
CATEGORY | A retail taxonomy category included in the selection criteria | Category name, hierarchy level, and optional attributes |
Important distinction: Item Set type vs. expression node type
The Item Set's type describes how the overall Item Set was constructed: item, brand, category, or hybrid.
The type returned inside an expression clause describes an individual selection criterion.
For example, an Item Set created with type=hybrid can return ITEMSET, BRAND, and CATEGORY nodes within the same expression.or array.
HYBRID is not a returned expression node type.
Interpret expression values
The structure of value depends on the expression node's type.
ITEMSET
ITEMSETWhen type=ITEMSET, the value.id field identifies a child Item Set containing individual products.
Use View Item Set Contents to retrieve the products included in the referenced child Item Set.
BRAND
BRANDWhen type=BRAND, the value.name field identifies the selected brand.
An expression may contain multiple brand clauses.
CATEGORY
CATEGORYWhen type=CATEGORY, the returned value object can include:
| Field | Description |
|---|---|
name | Name of the selected retail taxonomy category. |
level | Hierarchy level of the category. Supported values: 1, 2, 3. |
attributes | Optional array of additional category selection criteria. |
Each entry in attributes can include:
type— identifies the category attribute.values— lists the selected values for that attribute.
Use the List Taxonomies API for category attribute names, definitions, and values.
Sample responses
Brand-based expression
{ "code": "success", "itemsetId": 13240239, "expression": { "or": [ { "type": "BRAND", "value": { "name": "pepsi" } }, { "type": "BRAND", "value": { "name": "red bull" } } ] }
}Category-based expression
{ "code": "success", "itemsetId": 13240239, "expression": { "or": [ { "type": "CATEGORY", "value": { "name": "baby food", "level": 1 } }, { "type": "CATEGORY", "value": { "name": "Quilting Basting Guns", "level": 1 } } ] }
}Hybrid expression with Item Set, Brand, and Category criteria
{ "code": "success", "itemsetId": 13240239, "expression": { "or": [ { "type": "ITEMSET", "value": { "id": 12345679 } }, { "type": "BRAND", "value": { "name": "pepsi" } }, { "type": "CATEGORY", "value": { "name": "baby food", "level": 1, "attributes": [ { "type": "age-group", "values": [ "Infant", "toddler" ] }, { "type": "skin_type", "values": [ "all", "sensitive" ] } ] } } ] }
}Sample response - failure
[ { "code": "failure", "details": [ "string" ], "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ] }
]Common issues
- Requesting expression metadata before the Item Set reaches
BUILT - Assuming metadata is immediately available after build completion
- Supplying multiple IDs in
Filter[itemsetId] - Confusing the Item Set's
typewith expression nodetype - Treating
ITEMSETas an individual product identifier rather than a child Item Set reference - Expecting the expression response to include all underlying products
- Assuming every expression contains the same node types or attributes
What happens next
After retrieving the Item Set expression:
- Validate configuration: Review the returned selection criteria against the expected Item Set definition.
- Inspect underlying products: Use View Item Set Contents to retrieve products associated with the Item Set or referenced child Item Sets.
- Review Item Set metadata: Use List Item Sets to retrieve classification, build status, and ownership information.
- Update eligible Item Sets: Use Update Item Set when changes to the existing definition are required.
Related pages
Updated 24 days ago
