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:

  1. The audience build begins
  2. Walmart validates referenced audiences
  3. Boolean logic is processed
  4. Audience progresses through build statuses
  5. 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

High intent targeting

Narrow to highly qualified users

Combine multiple audiences together so users must match all conditions.

(Audience A AND Audience B)
Best for: conversion-focused campaigns and ROAS optimization.
Reach expansion

Expand audience reach

Broaden audience size by allowing users to qualify from multiple audience pools.

(Audience A OR Audience B)
Best for: awareness campaigns and prospecting.
Audience suppression

Exclude existing customers

Prevent existing purchasers or low-value users from qualifying for the audience.

Include Audience A
AND NOT Existing Buyers
Best for: acquisition campaigns and customer suppression.
Layered targeting

Combine behavioral signals

Layer multiple audience types together for more precise targeting.

(Category Audience
AND Persona Audience)
Best for: combining shopping intent with customer lifestyle signals.

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


Request 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 through include and optional exclude sections
  • include
    Array of matchAny groups defining which seed audiences qualify for inclusion
  • exclude
    Array of matchAny groups defining which seed audiences should be excluded
  • matchAny
    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 matchAny group.
  • AND across groups: A shopper must satisfy every matchAny group within the same section.
  • Exclusions: Shoppers satisfying all groups in the exclude section 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:

RequirementRule
Audience accessSeed audiences must belong to the advertiser or be shared with the advertiser.
Audience recencySeed audiences must have been built within the last 40 days or be used in an active campaign.
Audience identifierEach 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 eligibility

Advanced 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 include and exclude groups.

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

  • audienceId
  • name
  • details
  • code
  • message
  • errors
⚠️

Important behavior

A successful response does not mean the audience is ready for targeting. Always confirm status=AVAILABLE before 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:

  1. Audience processing begins
  2. Audience validation occurs
  3. Audience status progresses through lifecycle states
  4. Audience becomes AVAILABLE
  5. Use the Audience Size API to validate reach before activation
  6. Audience can be applied to Behavioral Targeting
  7. 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


Did this page help you?