Guides

Create item set

Create Item Sets for campaign measurement or audience targeting and track build status.

Overview

Use this endpoint to create item sets for campaign measurement or audience targeting. Select the Item Set's class, type, and product selection criteria based on how the Item Set will be used.

For an introduction to Item Set purposes, supported types, and measurement concepts, see Item Set Management Overview.

Availability

Supported for Onsite Display only.

How it works

1

Configure Item Set

Select the class, type, and applicable product criteria.

2

Create Item Set

Submit the request and store the returned itemsetId.

3

Check build status

Use List Item Sets to confirm processing is complete.

4

Use Item Set

Add the item set to a campaign or build a custom audience after status reaches BUILT.

Before you begin

  • Valid advertiserId
  • Determine whether the Item Set will be used for measurement or targeting
  • Select a supported type for the intended purpose
  • Prepare the required item identifiers, brand names, or category criteria
  • Use the List Items API or List Taxonomies API when needed to retrieve valid catalog identifiers or category information

Endpoint

POST /api/v1/itemset

View technical specifications

Request details

How this request is used

Use this endpoint to create Featured Measurement, Custom Halo Measurement, or Targeting Item Sets.

The request uses three fields to determine how the Item Set is configured:

  • class determines whether the Item Set supports measurement or targeting.
  • itemsetType distinguishes Featured from Halo Measurement.
  • type determines how products are selected for inclusion.

Key fields and behaviors

  • class
    Defines whether the item set is used for measurement (default) or targeting.
  • itemsetType
    Identifies featured or halo when class=measurement. Defaults to featured.
  • type
    Defines how products are selected: item, brand, category, or hybrid.
  • editable
    Indicates whether the item set is configured to support edits post-creation
  • items
    List of items to be used when item set type=item (if no item-based expression is supplied). Required for item sets where class=measurement and itemsetType=featured.
  • brands
    List of brands to be used when item set type=brand (if no brand-based expression is supplied).
  • expression
    Defines product selection using logical OR clauses. Required when neither items nor brands is supplied.

For complete parameter definitions and validation requirements, see the Create Item Set API reference.

Configure class and itemsetType

These fields determine the Item Set's intended purpose.

PurposeclassitemsetType
Featured Measurementmeasurementfeatured
Halo Measurementmeasurementhalo
TargetingtargetingNot applicable

Important behavior

  • If class is omitted, the default is measurement.
  • If itemsetType is omitted for a measurement Item Set, the default is featured.
  • itemsetType is ignored when class=targeting.

Specify the measurement purpose

When creating a Halo Measurement Item Set, explicitly set itemsetType to halo. Otherwise, the default measurement type is featured.

Configure type

The type field controls how products are selected.

typeProduct selectionSupported purposes
itemSpecific products identified individuallyFeatured, Halo, Targeting
brandProducts associated with selected brandsHalo, Targeting
categoryProducts matching retail taxonomy categoriesHalo, Targeting
hybridCombination of items, brands, and categoriesTargeting only

Type compatibility rules

  • Featured Measurement: item only.
  • Halo Measurement: item, brand, or category. Hybrid is not supported.
  • Targeting: All four types.

For more information about choosing a type, see Item Set Management APIs guide.

Configure product selection

The fields used to define included products depend on type.

Item-based selection

Use items to provide specific product identifiers. Item can be defined as an array or an expression.

Each item object includes:

  • id — identifies the product.
  • itemType — identifies the catalog identifier type.

Supported itemType values are gtin, upc, stores, and online.

How to find items
Use the List Items API to get a list of items associated with an advertisers's account.

Catalog rules

  • For products returned with catalog=UNIVERSAL by the List Items API, use GTIN identifiers.
  • For other catalog types, the supported identifier types include stores, online, and upc.

Expression-based selection

Use expression when defining product selection through logical OR clauses.

Each clause includes:

  • type — item, brand, or category.
  • value — the selection criteria for that clause.

The expression.or array must contain at least one clause.

Expression behavior

  • Item clauses identify individual products.
  • Brand clauses identify products by brand.
  • Category clauses identify products by taxonomy criteria.
  • Hybrid expressions combine different clause types.

Category expression attributes

Category expressions support additional attributes that refine which products are included in an Item Set. Use the optional attributes object within a category expression to apply supported product criteria beyond the category name and hierarchy level.

Expression attributes are only available for select categories at this time. Use the List Taxonomies API to get the attributes and supported values for a category.

How attributes are applied

  • Attributes are defined within the applicable category expression.
  • Each attribute must use a supported field name and value.
  • Category names and hierarchy levels must match the Walmart Connect retail taxonomy.

Configure editable

The editable field indicates whether the Item Set is configured for post-creation edits.

The live documentation contains additional restrictions on which fields can be updated based on Item Set status. These restrictions are covered in the Update Item Set guide.

The class, type, and editable fields cannot be changed after creation.

Sample requests

The following examples demonstrate the supported Item Set configurations.

Item-based Item Set

Create an item-based Item Set
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --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, "name": "string", "description": "itemset description", "class": "measurement", "type": "item", "editable": true, "items": [ { "id": 123456789, "itemType": "gtin" }, { "id": 123456790, "itemType": "gtin" } ] } ]'

Brand-based Item Set

Create a brand-based Item Set
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --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, "name": "string", "description": "itemset description", "class": "measurement", "type": "brand", "editable": true, "brands": ["abc", "xyz"] } ]'

Brand expression Item Set

Create a brand expression Item Set
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --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, "name": "string", "description": "itemset description", "class": "targeting", "type": "brand", "editable": true, "expression": { "or": [ { "type": "brand", "value": { "name": "pepsi" } }, { "type": "brand", "value": { "name": "red bull" } } ] } } ]'

Category expression Item Set

Create a category expression Item Set
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --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, "name": "string", "description": "itemset description", "class": "targeting", "type": "category", "editable": true, "expression": { "or": [ { "type": "category", "value": { "name": "baby food", "level": 1 } }, { "type": "category", "value": { "name": "Quilting Basting Guns", "level": 1 } } ] } } ]'

Hybrid expression Item Set

Create a targeting Item Set using a hybrid expression
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemset' \ --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, "name": "string", "description": "itemset description", "class": "targeting", "type": "hybrid", "editable": true, "expression": { "or": [ { "type": "item", "value": { "itemId": "12389", "itemType": "gtin" } }, { "type": "item", "value": { "itemId": "12589", "itemType": "gtin" } }, { "type": "brand", "value": { "name": "pepsi" } }, { "type": "category", "value": { "name": "baby food", "level": 1 } } ] } } ]'

Response details

What this response returns

A successful response confirms that the Item Set creation request was accepted and returns an identifier for the new Item Set.

Key fields to use

FieldDescription
codeIndicates whether the creation request succeeded or failed.
detailsProvides additional information about the request, including errors when applicable.
itemsetIdIdentifies the newly created Item Set. Store this value for subsequent requests.

How to interpret the response

  • success indicates the Item Set was created and processing can begin.
  • failure indicates the creation request was unsuccessful.
  • A returned itemsetId does not mean the Item Set has finished building.

Creation is not build completion

Item Sets are processed asynchronously. After a successful create request, use the List Item Sets API to confirm status=BUILT before using the Item Set.

Sample responses

Successful creation
[ { "code": "success", "details": "string", "itemsetId": 1234 }
]
Creation failed
{ "code": "failure", "details": ["error code"]
}

Common issues

  • Using an unsupported combination of class, itemsetType, and type
  • Omitting itemsetType=halo when creating a Halo Measurement Item Set
  • Using Brand, Category, or Hybrid for Featured Measurement
  • Using Hybrid for Halo Measurement
  • Providing items or brands that do not match the selected type
  • Omitting the required items, brands, or expression definition
  • Using an unsupported item identifier for the product's catalog type
  • Using category names that do not match the exact taxonomy values
  • Attempting to create more than one item sets in a call

What happens next

After creating an Item Set:

  1. Store the returned itemsetId.
  2. Use List Item Sets to check build status.
  3. Wait until status=BUILT.
  4. Continue with the applicable measurement or targeting workflow.

Related pages

Updated about 11 hours ago

Did this page help you?