Guides

Item set management APIs

Learn how Display item sets function and how the Display API provides support.

Overview

Create and manage Item Sets used throughout Walmart Connect Display workflows.

Item Sets are collections of products that support campaign measurement, attribution reporting, audience creation, and targeting.

When creating an Item Set, select a type that determines how products are included:

  • Item — individual products
  • Brand — products associated with selected brands
  • Category — products within selected retail taxonomy categories
  • Hybrid — combinations of items, brands, and categories

The supported type depends on whether the Item Set is used for Featured Measurement, Halo Measurement, or targeting.

Availability

Supported for Onsite Display only.

How it works

Item Sets support measurement and targeting workflows across Walmart Connect Display.

Create Item Set

Define the products included using a supported Item Set type.

Measurement

Measure attributable sales and campaign impact.

Audiences

Build audiences based on products and shopper behavior.

Item Set creation and updates are asynchronous:

  1. Create or update the Item Set.
  2. Walmart Connect begins processing the Item Set.
  3. Check build status using the List Item Sets API.
  4. Use the Item Set once status=BUILT.
📌

Item Set readiness

A successful create or update response does not mean the Item Set is ready for use. Processing can take up to a few hours depending on the number of items.

Verify status=BUILT using the List Item Sets API before using the Item Set in measurement, audience, or targeting workflows.

Choosing an Item Set type

The type field in the Create Item Set API determines how products are selected for inclusion.

Choose the type based on the products you want to include and the Item Set's intended purpose.

Item

Create an Item Set using a specific list of individual products. This type provides precise control over which products are included.

Best for: Product-level measurement and targeting.
Supported for
Featured Measurement Halo Measurement Targeting

Brand

Create an Item Set using products associated with one or more selected brands.

Best for: Brand-level measurement and targeting.
Compatibility
Halo Measurement Targeting Not Featured Measurement

Category

Create an Item Set using products within selected retail taxonomy categories.

Best for: Category-level measurement and targeting.
Compatibility
Halo Measurement Targeting Not Featured Measurement

Hybrid

Create an Item Set using a combination of individual items, brands, and categories.

Best for: Targeting workflows that require multiple product selection criteria.
Compatibility
Targeting Not Featured Measurement Not Halo Measurement

Item set type compatibility

TypeFeatured MeasurementHalo MeasurementTargeting
Item✅✅✅
Brand❌✅✅
Category❌✅✅
Hybrid❌❌✅

  • ✅ = supported

  • ❌ = not supported

Measurement Item Sets

Measurement Item Sets define which products are included when calculating campaign impact and attributable sales.

There are two measurement purposes: Featured and Halo. Each supports different Item Set types.

Featured Measurement Item Sets

Featured Measurement Item Sets measure the products directly advertised in a campaign.

They answer:

How did this campaign impact the products being advertised?

Supported Item Set type: Item only.

Featured Measurement Item Sets cannot use Brand, Category, or Hybrid types.

⚠️

Attribution requirement

Campaigns without a Featured Measurement Item Set cannot generate attributable sales metrics.

Halo Measurement Item Sets

Halo Measurement Item Sets measure the secondary impact of a campaign across additional products.

They answer:

How did this campaign influence sales across the broader brand or category?

Supported Item Set types: Item, Brand, Category.

Hybrid is not supported for Halo Measurement Item Sets.

Choosing how to create a Halo Item Set

Halo Item Sets can be created directly or automatically through the Item Set Association APIs.

Choose how to create a Halo Item Set

Select the approach that best fits your measurement requirements.

Create a custom Halo Item Set

Create an Item Set using a supported Item, Brand, or Category type to define the products included in expanded measurement.

Auto-create a Halo Item Set

Use the Item Set Association APIs to automatically create a brand- or category-based Halo Item Set when configuring campaign measurement.

Halo association options

The Item Set Association APIs support the following Halo configurations:

ValueDescriptionMeasurement behavior
noneNo Halo Item Set associatedNo expanded measurement
brandAuto-created using products from the same brand(s)Measures broader brand impact
categoryAuto-created using products from the same brand(s) and category(s)Measures category-level influence
customUses a manually created Halo Item SetProvides control over included products

These Halo association options are separate from the type field used when creating an Item Set.

Targeting Item Sets

Targeting Item Sets are used to build custom audiences based on products, brands, categories, or combinations of these criteria.

Supported Item Set types: Item, Brand, Category, Hybrid.

Targeting Item Sets support:

  • Rule-based audiences
  • Propensity audiences
  • Category affinity audiences

They help advertisers reach shoppers who demonstrate interest in specific products, brands, or categories.

Item Set ownership and sharing

Owned Item Sets

Created and managed within the advertiser account.

Shared Item Sets

Shared from another advertiser account within the same organization.

Item Set lifecycle

Item Sets are processed asynchronously after creation or update.

Create / Update

Submit the Item Set configuration.

Pending

Request accepted for processing.

Building

Item Set is being processed.

Built

Item Set is ready for use.

Build status requirements

StatusMeaning
DRAFTItem set has been created but not yet submitted for building
PENDINGThe item set is queued for processing but not yet being built
BUILDINGThe system is currently constructing/validating the item set.
FAILEDThe item set build process failed due to some system issue and will be retried.
BUILTThe item set was successfully built and is ready for use. This is a terminal state.
INVALIDThe itemset is invalid and unusable (due to issues with the items/brand/taxonomies in the itemset definition, expression inconsistencies, conflicts in underlying data etc.). This is a terminal state

Item Sets must reach BUILT before they can be used in measurement, audience, or targeting workflows.

Common workflows

Campaign measurement
  1. Create a Featured Measurement Item Set using the Item type.
  2. Optionally create a Halo Measurement Item Set using a supported type, or auto-create one through the Item Set Association APIs.
  3. Confirm manually created Item Sets have reached BUILT.
  4. Configure Item Set associations with the campaign.
  5. Launch the campaign.
  6. Review attributable sales reporting.
Audience creation
  1. Create a Targeting Item Set using a supported type.
  2. Confirm status=BUILT.
  3. Use the Item Set to create an eligible custom audience.
  4. Wait for audience processing to complete.
  5. Apply the audience to ad group targeting.

Item Set management endpoints

Use these APIs to create and update Item Sets.

WorkflowEndpointTechnical specifications
Create Item SetPOST /api/v1/itemsetView
Update Item SetPUT /api/v1/itemsetView

Common issues

  • Using an Item Set before status=BUILT
  • Creating a Featured Measurement Item Set using a type other than Item
  • Attempting to use Hybrid for Halo Measurement
  • Confusing Item Set type with Featured, Halo, or Targeting purpose
  • Including unrelated products in Featured Measurement Item Sets
  • Forgetting that Featured products are excluded from Halo measurement
  • Attempting to activate audiences before Item Set processing completes
Best practice

Choose a supported Item Set type for your intended workflow, then validate that the Item Set has reached BUILT status before using it for campaign measurement, audience creation, or targeting.

Related pages

Updated about 23 hours ago

Did this page help you?