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.

1

Identify Item Set

Retrieve the Item Set ID and confirm its status is BUILT.

2

Request expression

Submit the advertiser ID and a single Item Set ID.

3

Review criteria

Inspect returned brand, category, or child Item Set references.

4

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


Request 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 BUILT status.
  • 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 availability

An Item Set must reach BUILT status 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 failed
  • itemsetId
    Identifies the Item Set whose expression was retrieved
  • expression
    Object containing the returned product selection criteria
  • expression.or
    Array containing the expression clauses
  • type
    Identifies the expression node type: ITEMSET, BRAND, or CATEGORY
  • value
    Object containing the selection criteria associated with each node
  • value.id
    Identifies a referenced child Item Set when type=ITEMSET
  • value.name
    Identifies a brand or category name, depending on the node type
  • value.level
    Identifies the category hierarchy level when type=CATEGORY
  • value.attributes
    Contains additional category selection attributes, when applicable
  • details
    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 typeWhat it representsReturned information
ITEMSETA child Item Set created from a list of individual productsChild Item Set ID
BRANDA brand included in the selection criteriaBrand name
CATEGORYA retail taxonomy category included in the selection criteriaCategory 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

When 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

When type=BRAND, the value.name field identifies the selected brand.

An expression may contain multiple brand clauses.

CATEGORY

When type=CATEGORY, the returned value object can include:

FieldDescription
nameName of the selected retail taxonomy category.
levelHierarchy level of the category. Supported values: 1, 2, 3.
attributesOptional 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 type with expression node type
  • Treating ITEMSET as 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


Did this page help you?