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
How rule-based audiences come together
Combine behavioral signals, logic, and optional filters before submission.
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
BUILTstatus - Defined lookback strategy
- Clear inclusion and exclusion logic
Endpoint
POST /api/v1/audiences
POST /api/v1/audiencesRequest 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 frequency
- Spend percentile
- Purchase recency
- Reaching existing customers likely to convert
- Win-back and retention campaigns
- Efficiency-focused performance campaigns
- Audiences where purchase history matters most
- Browse activity
- Search behavior
- Activity frequency
- Capturing in-market shoppers with recent intent
- Product discovery and consideration campaigns
- Seasonal or time-sensitive promotions
Choosing a signal
| Goal | Recommended Signal |
|---|---|
| Reach existing customers | Purchase |
| Improve conversion efficiency | Purchase |
| Re-engage previous buyers | Purchase |
| Reach active shoppers | Browse |
| Product discovery | Browse |
| Seasonal campaigns | Browse |
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
| Value | Description |
|---|---|
OMNI | All channels (recommended default) |
ONLINE | Walmart.com purchases |
STORES | In-store purchases |
ACC | Auto 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:
90targets the top 90% of purchasers.
Lookback window strategies
Customers who purchased within the last 90 days
Customers who purchased during Black Friday week last year
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
| Signal | Typical Intent |
|---|---|
| Browse Activity | Product consideration |
| Search Activity | Stronger purchase intent |
| Browse + Search | Highest 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:
genderageRangeincome
Rules
- Only one gender value (M, F) may be selected
- Omit gender entirely for broad targeting
ageRange values
| enum | Description |
|---|---|
| A | Ages 18-24 |
| B | Ages 25-34 |
| C | Ages 35-44 |
| D | Ages 45-54 |
| E | Ages 55-64 |
| F | Ages 65+ |
To include all ages, omit the ageRange field.
Omit ageRange entirely
Rules
Selected ranges must be continuous; gaps between values for age are not allowed;
Valid:
["B","C"] (25–34 and 35–44; continuous age range)
Invalid:
["A","C"] (18–24 and 35–44; not allowed due to skipped age ranges)
income values
| enum | Description |
|---|---|
| A | $0-$24,999 |
| B | $25,000-$49,999 |
| C | $50,000-$74,999 |
| D | $75,000-$99,999 |
| E | $100,000-$149,999 |
| F | $150,000-$199,999 |
| G | $200,000+ |
The selected values must be continuous; gaps between values for income are not allowed.
Valid:
["B","C"] ($25,000-$49,999 and $50,000-$74,999; continuous income range)
Invalid:
["A","C"] ($0-$24,999 and $50,000-$74,999; not allowed due to income age ranges)
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
audienceIdname
Name of the campaign. Returned only when code=success.code
Indicates if request wassuccessorfailure.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
ImportantA 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
BUILTstatus. - 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:
- Audience processing begins
- Audience status transitions to
IN_PROGRESS - Audience can be used within Behavioral Targeting tactic when
status=AVAILABLE - Audience is activated at the ad group level
Related pages
Updated 27 days ago
