Overview

Predictive audiences use Walmart machine learning models to identify customers who are likely to take a future action based on shopping behavior, browsing activity, and audience similarity signals.

Unlike rule-based audiences, predictive audiences use modeled behavior rather than historical qualification rules.

Predictive audiences are commonly used for:

• Customer acquisition
• Product launches
• Incremental reach
• Seasonal campaigns
• Growth-focused media strategies

Availability

Supported for Onsite Display only.

How predictive audiences work

Predictive audiences are created by submitting audience criteria that Walmart uses to train and validate machine learning models.

Predictive audience lifecycle

Choosing a predictive audience type

Use the table below to determine which predictive audience strategy best matches your objective.

Common campaign patterns

Before you begin

• Valid advertiserId

• Supporting assets validated based on audience type:

  • Targeting Item sets in BUILT status
  • Seed audience IDs
  • Valid taxonomy hierarchy

Endpoint

POST /api/v1/audiences

View technical specifications

Request details

How this request is used

Creates a predictive custom audience for use in Onsite Display targeting.

Key fields and behaviors

• attribute
  Predictive audience type:

  • BRAND_AFFINITY
  • ITEM_PROPENSITY
  • LOOKALIKE

Audience definition behavior

All predictive audiences use the same high-level structure.

The contents of audienceCriteria vary depending on the predictive audience type.

{ "audienceDefinition": { "audienceCriteria": { "predictiveCriteria": { "predictiveSpecificFields": {} } } }, "audienceType": "CUSTOM"
}

Predictive audience types

Taxonomy hierarchy and category

Both Brand Affinity and Item Propensity custom audiences defintitions require an understanding of Walmart's retail taxonomy and how these categories are used in requests.

Taxonomy hierarchy

Category objects define where products exist within Walmart's retail taxonomy.

Audience definition

Brand Affinity audiences use the brandAffinityCriteria object within audienceDefinition.audienceCriteria to define the targeting logic.

The object contains three required parameters:

• brands
  List of brands to target. Customers matching any listed brand are included using OR logic.
• brandAffinityType
  Determines whetther the audience targets BRAND_SWITCHERS, BRAND_LOYALISTS, or BRAND_PROSPECTS
• categories

Category hierarchy requirements

Each Brand Affinity audience request must include the full three-level category hierarchy.

Each categories entry contains a category object with name and level values representing the hierarchy.

Important rules:

• All three hierarchy levels (1, 2, and 3) are required.
• At least one complete category hierarchy must be provided.
• Each specified category must be valid for at least one brand in the brands array.
• Requests containing categories that are not associated with any selected brand are invalid.

For the shared Create Audience request fields and endpoint behavior, see Create Custom Audience.

Sample request

 curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/audiences' \ --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 '{ "name": "Test brand affinity audience", "description": "example description", "advertiserId": 190000, "audienceType": "CUSTOM", "audienceObjective": ["REACH"], "attribute": "BRAND_AFFINITY", "audienceDefinition": { "audienceCriteria": { "brandAffinityCriteria": { "brands": ["brand1", "brand2"], "brandAffinityType": "BRAND_SWITCHERS", "categories": [ { "category": [ { "level": 1, "name": "Books, Music & Movies" }, { "level": 2, "name": "Books" }, { "level": 3, "name": "Example Books Category" } ] } ] } } } }' 

Item Propensity Audience Configuration

The rules below apply only when attribute=ITEM_PROPENSITY .

Build methods

Audience definition

Item Propensity audiences use the propensityCriteria object within audienceDefinition.audienceCriteria to define the targeting logic.

The object contains the following parameters:

• strategy
  Defines the optimization strategy for the audience ( PROMOTE_SEASONAL_PRODUCTS , PROMOTE_BRAND_NEW_PRODUCTS , IMPROVE_ROAS )
• itemsetIds
  Array of item set IDs used to identify products or categories for audience creation
• categories
  Array of category objects defining the product taxonomy used to build the audience

You must provide either itemsetIds or categories, but not both. Requests that include both parameters or omit both will result in an error.

Using item sets

Use itemsetIds when you want to build an Item Propensity audience from existing item sets.

Supported item sets must meet the following requirements:

• Item set type must be item or category (hybrid is not supported)
• Item set status must be BUILT.
• Item set must be a targeting item set
• Item sets containing brand inclusions are not supported.

Multiple item set IDs can be included in a single request.

Using categories

Use categories when you want to define the audience using Walmart's product taxonomy instead of existing item sets.

Important rules:

• At least one category object is required when using categories.
• Department-level targeting requires level 1.
• Category-level targeting requires levels 1 and 2.
• Subcategory-level targeting requires levels 1, 2, and 3.
• Each hierarchy must contain valid department, category, and subcategory names as applicable.

For shared Create Audience request fields and endpoint behavior, see Create Custom Audience.

Sample requests

curl -X POST \
'https://developer.api.us.walmart.com/api-proxy/service/display/api/v1/api/v1/audiences' \
--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 '{ "name": "sadadsads", "description": "dcsdfc", "advertiserId": 16273800, "audienceType": "CUSTOM", "audienceObjective": [ "REACH" ], "attribute": "ITEM_PROPENSITY", "audienceObjectiveText": "", "audienceDefinition": { "audienceCriteria": { "propensityCriteria": { "strategy": "PROMOTE_SEASONAL_PRODUCTS", "itemsetIds": [ 12345789, 23456789 ] } } } }'

curl -X POST \
'https://developer.api.us.walmart.com/api-proxy/service/display/api/v1/api/v1/audiences' \
--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 '{ "name": "sadadsads", "description": "dcsdfc", "advertiserId": 10000000, "audienceType": "CUSTOM", "audienceObjective": [ "REACH" ], "attribute": "ITEM_PROPENSITY", "audienceObjectiveText": "", "audienceDefinition": { "audienceCriteria": { "propensityCriteria": { "strategy": "PROMOTE_SEASONAL_PRODUCTS", "categories": [ { "category": [ { "name": "Wheelchair Accessories", "level": 3 }, { "name": "Mobility Equipment Accessories", "level": 2 }, { "name": "Health", "level": 1 } ] }, { "category": [ { "name": "Novel", "level": 3 }, { "name": "Fiction", "level": 2 }, { "name": "Books", "level": 1 } ] } } } }' 

Lookalike Audience Configuration

The rules below apply only when attribute=LOOKALIKE .

Choosing a seed audience

Lookalike audiences are built using an existing audience as the seed. The seed audience determines the shopper characteristics used to identify similar customers.

Only the following audience types are supported as seeds:

Audience definition

Lookalike audiences use the lookAlikeCriteria object within audienceDefinition.audienceCriteria to define the targeting logic.

The object contains one required parameter:

Seed audience eligibility

The selected seed audience must meet the following requirements:

For shared Create Audience request fields and endpoint behavior, see Create Custom Audience.

Sample request

curl -X POST \
'https://developer.api.us.walmart.com/api-proxy/service/display/api/v1/api/v1/audiences' \
--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 '{ "name": "placeholder name", "description": "example description", "advertiserId": 123, "audienceType": "CUSTOM", "audienceObjective": ["REACH"], "attribute": "LOOKALIKE", "audienceObjectiveText": "", "audienceDefinition": { "audienceCriteria": { "lookAlikeCriteria": { "seedAudienceId": 1234 } } } }' 

Response details

What this response returns

A successful response confirms the predictive audience request was created.

Key fields to use

• audienceId
• name
• details
• code
• message
• errors

Sample response

{ "code": "success", "audienceId": 12345678, "name": "abc", "details": [" AUDIENCE_CREATE_REQUEST_SUCCESS"] }

[ { "code": "failure", "details": [ "string" ],    "message": "string",
    "errors": [ { "field": "string", "errorType": "string", "description": "string" } ] }
]

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.

Common issues

The following issues may occur when creating predictive audiences.

What happens next

After audience creation:

1. Audience processing begins
2. Models are trained and validated
3. Audience status progresses through lifecycle states
4. Audience becomes AVAILABLE
5. Audience can be applied to Behavioral Targeting
6. Audience is activated at the ad group level

Related pages

- Audience Overview
- Rule-Based Audiences
- Advanced Targeting Audiences
- Audience Status Overview
- Audience Size API
- Audience Intelligence API
- List Taxonomies
- List Item Sets