Overview

Retrieve products and associated metadata available within an advertiser’s catalog.

Items are used throughout Walmart Connect Display for campaign measurement, audience creation, creative association, and targeting workflows.

Use this endpoint to:

Retrieve item identifiers
Retrieve GTINs and other product metadata
Build measurement item sets
Build targeting item sets
Associate products with creatives
Validate product eligibility

Availability

Supported for Onsite Display advertisers.

How it works

This endpoint returns item-level metadata including:

Item IDs
GTINs
Product names
Brand information
Retail taxonomy classifications
Product URLs
Images

Discovery

Retrieve products and metadata from the advertiser catalog.

Search

Filter by item, GTIN, name, brand, or taxonomy.

Validate

Confirm product metadata, catalog scope, and variant relationships.

Apply

Use item data in item sets, creatives, and targeting workflows.

Launch

Activate downstream Display workflows with validated item data.

Choosing the right item lookup

Use the table below to determine which filter best matches your workflow.

Need	Filter
Retrieve a specific Walmart item	`filter[itemId]`
Retrieve a universal retail identifier	`filter[gtin]`
Search by product name	`filter[itemName]`
Retrieve products from a brand	`filter[brandName]`
Retrieve products by hierarchy	`filter[department]`, `filter[category]`, `filter[subCategory]`
Retrieve only primary items or only variants.	`filter[itemType]`
Retrieve all variants for a matched item	`expandVariants=true`

Before you begin

Valid advertiserId

Endpoint

`POST /api/v1/items/list`

View technical specifications

Request details

How this request is used

Use this endpoint to:

Build measurement item sets
Build targeting item sets
Associate products with creatives
Validate product eligibility
Retrieve item identifiers

Key fields and behaviors

Filtering options

Use filters to narrow results to specific products, brands, or portions of the Walmart catalog. Choose the filter type using the information you’re trying to find.

Filter	Use case
`filter[itemId]`	Retrieve specific Walmart items
`filter[gtin]`	Retrieve products using universal retail identifiers
`filter[itemName]`	Retrieve a specific item by name

Filter	Use case
`filter[catalog]`	Limit results to Online, Stores, or Universal products
`filter[itemType]`	Retrieve only primary items or only variants

Filter	Use case
`filter[department]`	Retrieve products from a department
`filter[category]`	Retrieve products from a category
`filter[subCategory]`	Retrieve products from a subcategory

Filter	Use case
`filter[brandName]`	Retrieve products belonging to a brand

Parameter	Use case
`expandVariants=true`	Return all variants associated with a filtered item or GTIN

Understanding Item IDs and GTINs

Both Item IDs and GTINs can be used when building item sets.

Item ID
The Walmart-specific identifier assigned to an item.
GTIN
A universal retail identifier used across Walmart stores and digital properties.

Understanding variants

Some products belong to a variant group, such as size variations, color variations, or package variations.

Each variant maintains its own:

Item ID
GTIN

How to identify variants

Condition	Result
`itemId = baseItemId`	Primary item
`itemId ≠ baseItemId`	Variant item

Identifiers

Item IDs and GTINs

Use the identifier that best matches the catalog type and downstream workflow.

Item ID is the Walmart-specific identifier
GTIN is a universal retail identifier
Use GTINs when building item sets for universal products

Variants

Primary and variant items

Some products belong to a variant group, such as different sizes, colors, or package variations.

`itemId = baseItemId` indicates a primary item
`itemId ≠ baseItemId` indicates a variant item
Use expandVariants=true to return all variants

Readiness check: use the returned item metadata to confirm the correct product, hierarchy, and variant relationship before using the item in item set creation, creative association, or targeting workflows.

Scope results

Parameter	Use case
`isRestricted=true`	Return only items associated with the advertiser
`isRestricted=false`	Search beyond the advertiser's items

Understanding restricted vs. unrestricted mode

Restricted mode (default behavior) returns only items associated with the advertiser.

Unrestricted mode returns items outside the advertiser catalog. This requires both filter[itemName] and isRestricted=false in the request. Brand, category, and subcategory filters cannot be used.

Sample requests

List items using multiple filters

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/items/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, "isRestricted": true, "filter[itemId]": [29799], "filter[itemName]": ["Planner Datebook"], "filter[catalog]": "online", "filter[gtin]": ["0062"], "filter[department]": ["Office"], "filter[category]": ["Calendars"], "filter[subCategory]": ["Planners"], "filter[brandName]": ["brand"], "startIndex": 0, "count": 5 }'

List items with their variants

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/items/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[itemId]": [29799], "expandVariants": true "startIndex": 0, "count": 5 }'

Filter by item name when `isRestricted=false`

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/items/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[itemName]": ["test"], "isRestricted": false "startIndex": 0, "count": 5 }'

Response details

What this response returns

The response returns:

Product identifiers
Brand information
Product images
Product URLs
Category hierarchy
Variant relationships

Key fields to use

itemId
Walmart item identifier
gtin
Universal product identifier
brandName
Product brand
catalog
Online, stores, or universal
department
Retail hierarchy department
category
Retail hierarchy category
subCategory
Retail hierarchy subcategory
baseItemId
Variant relationship
imageUrl
Product image reference
itemPageUrl
Product destination URL

Sample responses

List of items using multiple filters


{ "code": "success", "totalResults": 1, "data": [ { "catalog": "ONLINE", "itemId": 29799, "gtin": "0062", "itemName": "Planner Datebook", "imageUrl": "imageUrl", "itemPageUrl": "itemPageUrl", "brandName": "brand", "department": "Office", "category": "Calendars", "subCategory": "Planners", "baseItemId" 1 } ]
}

List of items with variants

{ "code": "success", "totalResults": 2, "data": [ { "catalog": "ONLINE", "itemId": 29799, "gtin": "1", "itemName": "itemName", "imageUrl": "imageUrl", "itemPageUrl": "itemPageUrl", "brandName": "brand", "department": "department", "category": "Personal Organizers", "subCategory": "Planners & Appointment Books", "baseItemId": 29799,
"isSubscribeEligible": true     }, { "catalog": "ONLINE", "itemId": 29790, "gtin": "1", "itemName": "itemName", "imageUrl": "imageUrl", "itemPageUrl": "itemPageUrl", "brandName": "brand", "department": "department", "category": "Personal Organizers", "subCategory": "Planners & Appointment Books", "baseItemId": 29799,
"isSubscribeEligible": false     } ]
}

Common issues

Using item IDs instead of GTINs for universal products
Attempting partial matches on item names
Using invalid taxonomy values
Confusing primary and variant items
Using the wrong catalog value for the intended workflow
Fetching items with isrestricted=false without also including filter[itemName]
Using expandVariants=true without also including filter[itemId] or filter[gtin]

What happens next

After retrieving item data:

Select the products needed for the workflow
Store item IDs and GTINs
Use items in item set creation workflows
Associate products with creatives
Validate product eligibility before downstream use

Overview

Availability

How it works

Discovery

Search

Validate

Apply

Launch

Choosing the right item lookup

Before you begin

Endpoint

POST /api/v1/items/list

Request details

How this request is used

Key fields and behaviors

Filtering options

Understanding Item IDs and GTINs

Understanding variants

How to identify variants

Item IDs and GTINs

Primary and variant items

Scope results

Understanding restricted vs. unrestricted mode

Sample requests

Response details

What this response returns

Key fields to use

Sample responses

Common issues

What happens next

Related pages

`POST /api/v1/items/list`