Create advanced targeting audiences
Learn how to build an audience using advanced targeting with the create audience endpoint.
Overview
Advanced targeting audiences allow you to create highly specific audience segments by combining existing audiences using Boolean logic.
These audiences are built using:
- Include logic
- Exclude logic
- AND conditions
- OR conditions
Advanced targeting is commonly used to:
- Narrow audience overlap
- Exclude existing customers
- Combine high-intent segments
- Build layered targeting strategies
- Create highly customized audience definitions
Availability
Supported for Onsite Display only.
How advanced audiences work
Advanced audiences do not create new behavioral signals. Instead, they combine existing audiences into a new audience definition using Boolean logic.
Advanced audience workflow
Select Audiences
Choose existing audiences to combine.
Build Logic
Define include and exclude conditions.
Create Audience
Submit the advanced audience definition.
Processing
Audience validation and build begins.
Activate
Apply the audience once available.
Audience creation is asynchronous.
After submission:
- The audience build begins
- Walmart validates referenced audiences
- Boolean logic is processed
- Audience progresses through build statuses
- Audience becomes available for targeting
Audience design framework
Use the following framework when designing advanced audiences.
Choose Audiences
Select source audiences where status=AVAILABLE.
Include Logic
Define qualification rules.
Exclude Logic
Remove unwanted users.
Validate Reach
Confirm audience size remains viable.
Create
Build the audience.
Common audience design patterns
Narrow to highly qualified users
Combine multiple audiences together so users must match all conditions.
Expand audience reach
Broaden audience size by allowing users to qualify from multiple audience pools.
Exclude existing customers
Prevent existing purchasers or low-value users from qualifying for the audience.
AND NOT Existing Buyers
Combine behavioral signals
Layer multiple audience types together for more precise targeting.
AND Persona Audience)
Audience size considerations
As advanced audiences become more complex, audience reach typically decreases.
Broader Logic
More OR conditions generally increase audience size and reach.
Narrower Logic
More AND conditions and exclusions generally reduce audience size and increase precision.
Before you begin
- Valid
advertiserId - Valid seed audiences
Endpoint
POST /api/v1/audiences
POST /api/v1/audiencesRequest details
The below only applies when attribute=ADVANCED .
How this request is used
Creates a custom audience using Boolean combinations of existing audience IDs.
Audience definition
The advancedCriteria object within audienceDefinition.audienceCriteria defines which audiences to include and optionally exclude.
Advanced targeting criteria
advancedCriteria
Contains the audience targeting logic throughincludeand optionalexcludesectionsinclude
Array ofmatchAnygroups defining which seed audiences qualify for inclusionexclude
Array ofmatchAnygroups defining which seed audiences should be excludedmatchAny
Array of seed audience IDs. A shopper matching any ID within the group satisfies that group.
How inclusion and exclusion logic works
Advanced Targeting uses AND of OR logic for both inclusion and exclusion.
- OR within a group: A shopper must match at least one audience ID in a
matchAnygroup. - AND across groups: A shopper must satisfy every
matchAnygroup within the same section. - Exclusions: Shoppers satisfying all groups in the
excludesection are removed from the qualifying audience.
Inclusion example
"include": [ { "matchAny": [123, 456] }, { "matchAny": [789] }
]This includes shoppers matching:
(123 OR 456) AND 789
Exclusion example
"exclude": [ { "matchAny": [888, 999] }, { "matchAny": [555] }
]This excludes shoppers matching:
(888 OR 999) AND 555
The exclusion applies to shoppers who satisfy both exclusion groups, not every shopper appearing in any excluded seed audience.
Seed audience requirements
All seed audience IDs referenced in include or exclude must meet the following requirements:
| Requirement | Rule |
|---|---|
| Audience access | Seed audiences must belong to the advertiser or be shared with the advertiser. |
| Audience recency | Seed audiences must have been built within the last 40 days or be used in an active campaign. |
| Audience identifier | Each matchAny entry must contain valid integer audience IDs. |
The 40-day eligibility window is calculated as:
Current date - Audience build date ≤ 40 days
An audience built more than 40 days ago may still qualify if it is currently used in an active campaign.
Seed audience eligibilityAdvanced Targeting audiences can only reference seed audiences owned by or shared with the advertiser.
Each seed audience must also have been built within the last 40 days or be used in an active campaign. These requirements apply to audiences in both
includeandexcludegroups.
For shared Create Audience request fields and endpoint behavior, see Create Custom Audience.
Sample requests
Simple audience
Logic
Audience A OR Audience B{ "advancedCriteria": { "include": [ { "matchAny": [123,456] } ] }
}Intermediate audience
Logic
(Audience A OR Audience B)
AND
Audience C{ "advancedCriteria": { "include": [ { "matchAny": [123,456] }, { "matchAny": [789] } ] }
}Complex audience
Note: This example builds an advanced targeting audience with the following boolean combination of audience IDs: {(123 OR 345) AND (456 OR 789)} AND [NOT { (888 OR 999) AND (555 OR 444) } ]
Include with or/and + Exclude with or/and
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 '{ "advertiserId": 1, "name": "advancedtargeting1", "audienceType": "CUSTOM", "attribute": "ADVANCED", "description": "advanced targeting 1", "audienceDefinition": { "audienceCriteria": { "advancedCriteria": { "include": [ { "matchAny": [ 123, 345 ] }, { "matchAny": [ 456, 789 ] } ], "exclude": [ { "matchAny": [ 888, 999 ] }, { "matchAny": [ 555, 444 ] } ] } } } }'Response details
What this response returns
A successful response confirms the advanced audience request was created.
Key fields to use
audienceIdnamedetailscodemessageerrors
Important behaviorA successful response does not mean the audience is ready for targeting. Always confirm
status=AVAILABLEbefore applying the audience to ad groups.
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
Request submission successful
{ "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" } ] }
]## 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.<br />For the complete error response schema and endpoint-specific response definitions, see the <Anchor target="_blank" href="https://walmart-marketplace-group.readme.io/advertising-partners/reference/createaudience">API Reference</Anchor>. For guidance on HTTP status codes and how clients should handle them, see <Anchor target="_blank" href="https://developer.walmart.com/advertising-partners/docs/api-status-codes-and-error-handling">API status codes and error handling</Anchor>.Common audience-building mistakes
Over-Segmentation
Using too many AND conditions can dramatically reduce audience size.
Conflicting Logic
Including and excluding highly overlapping audiences can unintentionally remove most users.
Expired Audiences
Using audiences that no longer meet eligibility requirements will cause validation failures.
What happens next
After creation:
- Audience processing begins
- Audience validation occurs
- Audience status progresses through lifecycle states
- Audience becomes
AVAILABLE - Use the Audience Size API to validate reach before activation
- Audience can be applied to Behavioral Targeting
- Activate audience in an ad group
Related pages
- Audience Overview
- Rule-Based Audiences
- Predictive Audiences
- Audience Status Overview
- Audience Size API
- Audience Intelligence API
- List Taxonomies
- List Item Sets
Updated 28 days ago
