Create rule-based audience

Learn to build rule-based audiences using shopper behavior, filters, and exclusions.

Overview

Rule-based audiences help you reach Walmart customers using historical purchase and browse behavior.

These audiences are best when you want precise control over:

  • Who qualifies for inclusion
  • Who should be excluded
  • Which behaviors matter most
  • How recent or frequent customer activity should be

Rule-based audiences are commonly used for:

  • Customer retention
  • Win-back campaigns
  • Cross-sell and upsell initiatives
  • Consideration campaigns
  • High-efficiency performance marketing

Availability

Supported for Onsite Display only.


How rule-based audiences work

Rule-based audiences are built by combining:

  • Purchase or browse behavior
  • Inclusion and optional exclusion logic
  • Optional demographic filters
  • Optional geotargeting filters

Audience creation is asynchronous.

After submission, audience processing begins automatically and must complete before the audience can be used for targeting.

Audience design framework

Behavior

Select purchase, browse, or both.

Logic

Define inclusion and exclusion rules.

Demographics

Optionally refine the audience.

Geography

Optionally narrow by location.

Audience

Generate the final targetable audience.

Audience build flow

Audience build flow

How rule-based audiences come together

Combine behavioral signals, logic, and optional filters before submission.

1
Choose signals
Purchase, browse, or both.
2
Define logic
Set include and exclude rules.
3
Add filters
Layer demographics or geography.
4
Submit
Build starts automatically.
📌

Dependency

Item sets used in audience rules must already be in BUILT status.


Common audience patterns

The examples below represent common audience design approaches.

Retention

Purchase behavior targeting recent customers.

Win-Back

Historical purchasers excluding recent buyers.

Consideration

Browse and search activity targeting active shoppers.

Acquisition

Browse behavior combined with purchaser exclusions.


Before you begin

  • Valid advertiserId
  • Targeting item sets in BUILT status
  • Defined lookback strategy
  • Clear inclusion and exclusion logic

Endpoint

POST /api/v1/audiences


Request details

How this request is used

Creates a rule-based audience using historical behavioral signals.


Behavioral signals

Rule-based audiences support two primary behavioral signals.

Purchase behavior
Target past purchasers
  • Purchase frequency
  • Spend percentile
  • Purchase recency
Best for
  • Reaching existing customers likely to convert
  • Win-back and retention campaigns
  • Efficiency-focused performance campaigns
  • Audiences where purchase history matters most
Browse behavior
Target shopping intent
  • Browse activity
  • Search behavior
  • Activity frequency
Best for
  • Capturing in-market shoppers with recent intent
  • Product discovery and consideration campaigns
  • Seasonal or time-sensitive promotions

Choosing a signal

GoalRecommended Signal
Reach existing customersPurchase
Improve conversion efficiencyPurchase
Re-engage previous buyersPurchase
Reach active shoppersBrowse
Product discoveryBrowse
Seasonal campaignsBrowse

Purchase behavior configuration

Purchase behavior uses historical transaction data to identify qualifying customers.

The item set IDs included in the request determine which products or categories are used for qualification.

Purchase signals

Purchase targeting supports:

Purchase channel

ValueDescription
OMNIAll channels (recommended default)
ONLINEWalmart.com purchases
STORESIn-store purchases
ACCAuto Care Center purchases

Purchase frequency

The number of qualifying purchases made during the selected lookback period.

Supported range:

  • 1–8 purchases

Purchase percentile

The shopper's purchase rank within the selected audience.

Example:

  • 90 targets the top 90% of purchasers.

Lookback window strategies

Relative window
Rolling timeframe relative to today
Defines customer activity using a rolling number of days from the current date.
Example
Customers who purchased within the last 90 days
Best for: Ongoing campaigns, recent purchase behavior, and evergreen audience targeting.
Absolute window
Fixed calendar date range
Defines customer activity using a specific start and end date.
Example
Customers who purchased during Black Friday week last year
Best for: Seasonal analysis, historical events, and campaign-specific customer cohorts.

Purchase targeting rules


Browse behavior configuration

Browse targeting identifies customers using onsite engagement signals.

Browse signals

Browse targeting supports:

  • Browse activity
  • Search activity
  • Browse + search combined
  • Activity frequency
  • Platform type (BROWSER, IN_APP)

Understanding browse signals

SignalTypical Intent
Browse ActivityProduct consideration
Search ActivityStronger purchase intent
Browse + SearchHighest intent and engagement

Browse targeting rules


Demographic refinement

Demographic filters can refine purchase or browse audiences.

Use demographic refinement to:

  • Support demographic-specific campaigns
  • Narrow broad behavioral audiences
  • Improve targeting precision

If you do not wish to use demographic refinements, omit demographics from the request.

Supported dimensions:

  • gender
  • ageRange
  • income

Rules

  • Only one gender value (M, F) may be selected
  • Omit gender entirely for broad targeting

Geographic refinement

Geotargeting can be layered onto purchase or browse audiences.

Supported geo types:

  • DMA
  • City
  • State
  • ZIP Code

Geographic rules


Sample requests

Rule-based audience with purchase start/end dates and purchase frequency
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 rule based audience", "description": "Test audience", "advertiserId": 190000, "audienceType": "CUSTOM", "attribute": "RULE_BASED", "audienceObjective": [ "REACH", "OTHER" ], "audienceObjectiveText": "custom objective", "audienceDefinition": { "audienceCriteria": { "include": { "purchaseCriteria": { "purchaseStartOffsetDate": "2025-01-20T06:11:41.702Z", "purchaseEndOffsetDate": "2025-01-20T06:11:41.702Z", "purchaseChannel": "ONLINE", "purchaseFrequency":1, "itemsetIds": [ 1000000 ] }, "browseCriteria": { "userActivityType": "SEARCH", "userActivityStartOffsetDays": 182, "userActivityEndOffsetDays": 0, "userActivityPlatforms": ["BROWSER"], "userActivityFrequency": 1, "itemsetIds": [14021736 ] } }, "exclude": { "purchaseCriteria": { "purchaseStartOffsetDate": "2025-02-25T05:00:00.000Z", "purchaseEndOffsetDate": "2025-02-25T05:00:00.000Z", "purchaseChannel": "ONLINE", "purchaseFrequency": 1, "itemsetIds": [ 1234567 ] }, "browseCriteria": { "userActivityType": "SEARCH", "userActivityStartOffsetDays": 182, "userActivityEndOffsetDays": 0, "userActivityPlatforms": [ "BROWSER" ], "userActivityFrequency": 1, "itemsetIds": [ 1543234 ] } }, "demographics": { "gender": ["M"], "ageRange": ["A", "B", "C"], "income": ["A", "B", "C"] }, "geoTargets": [ { "id": 88888888 } ] } } }' 
Rule-based audience with purchase start/end dates and purchase percentile
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 rule based audience", "description": "Test audience", "advertiserId": 190000, "audienceType": "CUSTOM", "attribute": "RULE_BASED", "audienceObjective": [ "REACH", "OTHER" ], "audienceObjectiveText": "custom objective", "audienceDefinition": { "audienceCriteria": { "include": { "purchaseCriteria": { "purchaseStartOffsetDays": 182, "purchaseEndOffsetDays": 0, "purchaseChannel": "ONLINE", "purchasePercentile":90, "itemsetIds": [10000000] }, "browseCriteria": { "userActivityType": "SEARCH", "userActivityStartOffsetDays": 182, "userActivityEndOffsetDays": 0, "userActivityPlatforms": ["BROWSER"], "userActivityFrequency": 1, "itemsetIds": [10000000] } }, "exclude": { "purchaseCriteria": { "purchaseStartOffsetDays": 182, "purchaseEndOffsetDays": 0, "purchaseChannel": "ONLINE", "purchasePercentile": 90, "itemsetIds": [1000000] }, "browseCriteria": { "userActivityType": "SEARCH", "userActivityStartOffsetDays": 182, "userActivityEndOffsetDays": 0, "userActivityPlatforms": [ "BROWSER" ], "userActivityFrequency": 1, "itemsetIds": [1000000] } }, "demographics": { "gender": ["F"], "ageRange": ["A"], "income": ["A"] }, "geoTargets": [ { "id": 48999999 } ] } } }' 
Rule-based audience with demographic and geotargeting
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 rule based audience", "description": "Test audience", "advertiserId": 190000, "audienceType": "CUSTOM", "attribute": "RULE_BASED", "audienceObjective": [ "REACH", "OTHER" ], "audienceObjectiveText": "custom objective", "audienceDefinition": { "audienceCriteria": { "include": { "purchaseCriteria": { "purchaseStartOffsetDays": 182, "purchaseEndOffsetDays": 0, "purchaseChannel": "ONLINE", "purchasePercentile":90, "itemsetIds": [10000000] }, "browseCriteria": { "userActivityType": "SEARCH", "userActivityStartOffsetDays": 182, "userActivityEndOffsetDays": 0, "userActivityPlatforms": ["BROWSER"], "userActivityFrequency": 1, "itemsetIds": [10000000] } }, "exclude": { "purchaseCriteria": { "purchaseStartOffsetDays": 182, "purchaseEndOffsetDays": 0, "purchaseChannel": "ONLINE", "purchasePercentile": 90, "itemsetIds": [1000000] }, "browseCriteria": { "userActivityType": "SEARCH", "userActivityStartOffsetDays": 182, "userActivityEndOffsetDays": 0, "userActivityPlatforms": [ "BROWSER" ], "userActivityFrequency": 1, "itemsetIds": [1000000] } }, "demographics": { "gender": ["F"], "ageRange": ["A"], "income": ["A"] }, "geoTargets": [ {   "zipcode": "01234"         } ] } } }' 
Rule-based audience with conversion criteria
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 rule based audience", "description": "Test audience", "advertiserId": 190000, "audienceType": "CUSTOM", "attribute": "RULE_BASED", "audienceObjective": [ "REACH", "OTHER" ], "audienceObjectiveText": "custom objective", "audienceDefinition": { "audienceCriteria": { "include": { "conversionCriteria": { "events": ["PRODUCT_VIEW", "ADD_TO_CART"], "frequency": 1, "conversionStartOffsetDate": "2024-11-01T00:00:00.000Z", "conversionEndOffsetDate":"2024-11-01T00:00:00.000Z"               } }, "exclude": { "conversionCriteria": { "events": "PRODUCT_VIEW", "ADD_TO_CART"], "frequency": "1", "conversionStartOffsetDate": "2024-11-01T00:00:00.000Z", "conversionEndOffsetDate": "2024-11-01T00:00:00.000Z"              } }, "demographics": { "gender": ["F"], "ageRange": ["A"], "income": ["A"] }, "geoTargets": [ {   "zipcode": "01234"         } ] } } }' 
Rule-based audience with ad exposure criteria
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 rule based audience", "description": "Test audience", "advertiserId": 190000, "audienceType": "CUSTOM", "attribute": "RULE_BASED", "audienceObjective": [ "REACH", "OTHER" ], "audienceObjectiveText": "custom objective", "audienceDefinition": { "audienceCriteria": { "include": { "adExposureCriteria": { "eventType": "CLICKS",                   "entityRef": { "entityType": "AD_GROUP", "entityId": 12345 },                 "adExposureStartOffsetDate": "2024-11-01T00:00:00.000Z", "adExposureEndOffsetDate":"2024-11-01T00:00:00.000Z"             } }, "exclude": {             "adExposureCriteria": { "eventType": "CLICKS",                   "entityRef": { "entityType": "CAMPAIGN", "entityId": 12345 },                 "adExposureStartOffsetDate": "2024-11-01T00:00:00.000Z", "adExposureEndOffsetDate":"2024-11-01T00:00:00.000Z"             }       }, "demographics": { "gender": ["F"], "ageRange": ["A"], "income": ["A"] }, "geoTargets": [ {   "zipcode": "01234"         } ] } } }' 

Response details

What this response returns

Returns an audience identifier and audience metadata.

Key fields to use

  • audienceId
  • name
    Name of the campaign. Returned only when code=success.
  • code
    Indicates if request was success or failure.
  • details
    Populates success or error message depending upon value of code.
  • 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
📌

Important

A successful response does not mean the audience is immediately targetable. Audience processing continues after creation.

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.


Sample response

Successful response
{ "code": "success", "audienceId": 12345678, "name": "abc", "details": [" AUDIENCE_CREATE_REQUEST_SUCCESS"] }
Sample response - failure
[ { "code": "failure", "details": [ "string" ],    "message": "string",
    "errors": [ { "field": "string", "errorType": "string", "description": "string" } ] }
]

Common issues

  • Using item sets that are not in BUILT status.
  • Using measurement item sets.
  • Using non-continuous demographic ranges
  • Combining incompatible geotargeting types
  • Mixing relative and absolute purchase windows
  • Assuming successful creation means immediate availability

What happens next

After submission:

  1. Audience processing begins
  2. Audience status transitions to IN_PROGRESS
  3. Audience can be used within Behavioral Targeting tactic when status=AVAILABLE
  4. Audience is activated at the ad group level

Related pages


Did this page help you?