Create ad group

Learn to create Onsite Display ad groups with targeting, bidding, and delivery settings.

Overview

Ad groups define how and where Display ads are delivered within a campaign.

Each ad group controls:

  • Targeting tactic
  • Bid strategy
  • Budget (when managed at the ad group level)
  • Schedule (when managed at the ad group level)
  • Creative rotation
  • Creative associations

A campaign may contain multiple ad groups, each with its own delivery strategy and configuration.

This guide explains how to create ad groups, configure targeting, manage budgets and schedules, and prepare ad groups for delivery.

Availability

Supported for Onsite Display only.

Offsite Display (Walmart DSP) ad group management is not currently supported via our API. Learn more about what's supported for offsite display here.


How ad groups fit into delivery

Campaign

Campaign defines overall delivery objectives.

Create Ad Group

Configure delivery strategy and targeting.

Configure Targeting

Select one primary targeting tactic.

Budget & Schedule

Apply delivery controls if managed at the ad group level.

Associate Creative

Attach at least one approved creative.

Delivery

Ad group becomes eligible to serve.


How it works

When creating an ad group, you must:

  • Select exactly one primary targeting tactic
  • Define bidding configuration
  • Determine where budget and schedule are managed
  • Configure ad serving behavior

Delivery rule

An ad group must have at least one Approved creative associated before it can serve impressions.

Configuration rule

Budget, schedule, and delivery settings must be managed at either the campaign level or the ad group level — not both.


Before you begin

  • Valid advertiserId
  • Valid campaignId
  • Budget and schedule configuration model selected
  • Understanding of the targeting tactic being used

Review the Targeting Object Guide before creating ad groups.


Endpoint

POST /api/v1/adGroups


Request details

How this request is used

Creates an ad group within an existing campaign and defines how delivery occurs.

Key fields and behaviors

  • name
    Identifies the ad group in reporting and management workflows.

  • campaignId
    Associates the ad group with the parent campaign.

  • Budget configuration
    Controls spending when budget is managed at the ad group level.

  • Schedule
    Controls delivery timing when schedule is managed at the ad group level.

  • Targeting
    Determines who is eligible to see the ad.

  • maxBid
    Defines the maximum bid for delivery.

  • Ad serving settings
    Controls creative rotation and frequency caps.

  • outOfStockProtection
    Enables the opt-in/opt-in of out of stock protection. Default: true


Configuration placement

Budget and schedule can be managed at either the campaign level or the ad group level.

Campaign-Level Control

  • All ad groups inherit the same settings
  • Shared budget management
  • Shared scheduling

Ad Group-Level Control

  • Independent budgets
  • Independent schedules
  • Greater testing flexibility

For a complete explanation, see Campaign vs Ad Group Configuration Rules.


Targeting configuration

Each ad group supports exactly one primary targeting tactic.

Behavioral

Reach audiences based on historical Walmart shopping behavior.

Contextual

Serve ads on relevant product and content pages.

Keyword

Reach shoppers searching for specific terms.

Run of Site

Broad delivery across eligible inventory.

Targeting rules

  • Exactly one primary targeting tactic per ad group
  • Geotargeting may be combined with any targeting tactic
  • Targeting IDs with isDisabled=true cannot be used
  • Ad groups using the keyword targeting tactic must have at least one approved keyword it will begin delivering impressions.

Geotargeting

Geotargeting may be combined with any targeting tactic using AND logic.

Geotargeting rules

  • Geotargeting is optional
  • US targeting is applied by default if omitted
  • Only one geotargeting type may be used per ad group

Supported geotargeting types include country, state, city, DMA, and zip code.

Geotargeting object structure

{ "geoTargets": [ { "id": 123 } ]
}

or

{ "geoTargets": [ { "zipCode": "35004" } ]
}

Budget

Budget is required only when budget is managed at the ad group level.

budgetTypedailyBudgettotalBudgetdeliverySpeed
dailyRequiredN/AN/A
totalN/ARequiredRequired (frontloaded or evenly)

Schedule

Use ad group-level scheduling when delivery timing should vary by ad group.

Schedule rules

  • Dates must use ISO 8601 format
  • Dates are normalized to Eastern Time
  • Unlimited end dates are supported (use 9999-12-30T00:00:00Z as the end date to implement)
  • Unlimited end dates cannot be combined with total budget

Bidding

Bidding controls competitive delivery.

Bid rules

  • maxBid must be at least $0.01
  • Bid values determine delivery competitiveness

Ad serving behavior

Ad serving is controlled using:

Creative rotation

  • OPTIMIZE_PERFORMANCE
  • ROTATE_EVENLY

Frequency caps

  • frequencyCapDay
  • frequencyCapWeek
  • frequencyCapMonth

Use these controls to manage creative distribution and customer exposure frequency.


Out of stock protection

Out-of-Stock Protection is designed to optimize ad spend by preventing Onsite Display ads from serving when there are no products in stock on the advertised landing page, or when the available products cannot be shipped, delivered, or picked up in a store near the customer.

Out-of-Stock Protection is enabled by default (outOfStockProtection=true) for applicable ad groups within existing and new Onsite Display auction campaigns. Learn more about this capability here.


Sample requests

Expression-based and flattened targeting support

This endpoint supports both expression-based and flattened targeting structure. Only one of expression based or flattened structure should be used in a request. Review the Targeting object guide to learn more.

Behavioral targeting (expression schema)
curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --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 ' [ {
"campaignId": 1,
"advertiserId": 1,
"name": "Ad group 1" ,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "total",
"totalBudget": 5000,
"deliverySpeed" : "evenly",
"creativeRotationMode": "OPTIMIZE_PERFORMANCE"", "frequencyCapDay" : 1,
"frequencyCapWeek" : 3,
"frequencyCapMonth" : 5,
"maxBid" : 0.5,   "outOfStockProtection": true,
"targeting": { "and": [ { "and": [ { "behavioral": [ { "audienceType": "retail", "attribute": "historical", "id": 134 }, { "audienceType": "retail", "attribute": "historical", "id": 243234 } ] }, { "not": [                { "behavioral": [ { "audienceType": "retail", "attribute": "historical", "id": 134 }, { "audienceType": "retail", "attribute": "historical", "id": 243234 } ] } ] }, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } }
]'
Behavioral targeting (flattened schema)
curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --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 ' [ {
"campaignId": 1,
"advertiserId": 1,
"name": "Ad group 1" ,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "total",
"totalBudget": 5000,
"deliverySpeed" : "evenly",
"creativeRotationMode": "OPTIMIZE_PERFORMANCE"", "frequencyCapDay" : 1,
"frequencyCapWeek" : 3,
"frequencyCapMonth" : 5,
"maxBid" : 0.5,   "outOfStockProtection": false,
"targeting": {    "behavioral": { "include": [ { "audienceType": "retail", "attribute": "historical", "id": 134 }, { "audienceType": "retail", "attribute": "historical", "id": 234 } ], "exclude": [ { "audienceType": "retail", "attribute": "historical", "id": 123 }, { "audienceType": "retail", "attribute": "historical", "id": 111 } ] }, "geoTargets": { "include": [{ "id": 123 }, { "id": 234 } ] }
}  
}
]'
Contextual targeting (expression schema)
curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --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 ' [ {
"campaignId": 1,
"advertiserId": 1,
"name": "Ad group 1" ,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "daily",
"dailyBudget": 500,
"deliverySpeed" : "evenly",
"creativeRotationMode":"OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 1, "frequencyCapWeek" : 3, "frequencyCapMonth" : 5,
"maxBid" : 0.5,
"outOfStockProtection": true,
 "targeting" : { "and": [ { "contextual": [ { "id": 3452, "reach": "tier_2" }, { "id": 2343, "reach": "tier_3" } ] }, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } }
]'
Contextual targeting (flattened schema)
curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --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 ' [ {
"campaignId": 1,
"advertiserId": 1,
"name": "Ad group 1" ,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "daily",
"dailyBudget": 500,
"deliverySpeed" : "evenly",
"creativeRotationMode":"OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 1, "frequencyCapWeek" : 3, "frequencyCapMonth" : 5,
"outOfStockProtection": false,
"maxBid" : 0.5, "targeting": {    "contextual": { "include": [         { "id": 3452, "reach": "tier_2" },   { "id": 3453, "reach": "tier_1" }         ] },  "geoTargets": { "include": [{ "id": 123 }, { "id": 234 } ] }
}   }
]'
Keyword targeting (expression schema)
curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --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 '[    { "campaignId": 1, "advertiserId": 1, "name": "Ad group 1" , "startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z", "rateType": "cpm", "budgetType": "daily", "dailyBudget": 500, "deliverySpeed": "evenly", "creativeRotationMode": "OPTIMIZE_PERFORMANCE", "frequencyCapDay": 1, "frequencyCapWeek": 3, "frequencyCapMonth": 5, "maxBid": 0.5, "outOfStockProtection": true,
    "targeting": { "and": [ { "and": [ { "keywords": [ { "keywordText": "test-keyword-1", "matchType": "broad" }, { "keywordText": "test-keyword-2", "matchType": "broad" } ] }, { "not": [ { "keywords": [ { "keywordText": "test-keyword-3", "matchType": "exact" } ] } ] } ] }, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } } ]'
Keyword targeting (flattened schema)
curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --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 '[    { "campaignId": 1, "advertiserId": 1, "name": "Ad group 1" , "startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z", "rateType": "cpm", "budgetType": "daily", "dailyBudget": 500, "deliverySpeed": "evenly", "creativeRotationMode": "OPTIMIZE_PERFORMANCE", "frequencyCapDay": 1, "frequencyCapWeek": 3, "frequencyCapMonth": 5, "maxBid": 0.5,   "outOfStockProtection": false,  
    "targeting": { "keywords": { "include": [ { "matchType": "BROAD", "keywordText": "running shoes" }, { "matchType": "PHRASE", "keywordText": "trail sneakers" } ], "exclude": [ { "matchType": "EXACT", "keywordText": "free shoes" }, { "matchType": "EXACT", "keywordText": "cheap shoes" }       ] }, "geoTargets": { "include": [{ "id": 123 }, { "id": 234 } ] } }     } ]'
Run of Site targeting (expression schema)
curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --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 ' [ {
"campaignId": 1,
"advertiserId": 1,
"name": "Ad group 1" ,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "total",
"totalBudget": 5000,
"deliverySpeed" : "evenly",
"creativeRotationMode": "OPTIMIZE_PERFORMANCE"", "frequencyCapDay" : 1, "frequencyCapWeek" : 3, "frequencyCapMonth" : 5,
"maxBid" : 0.5,
"outOfStockProtection": true,
 "targeting" : { "and": [ { "runOfSite": true }, { "geoTargets": [ { "zipCode": "35004" } ] } ]
}  
}
]'
Run of Site targeting (flattened schema)
curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --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 ' [ {
"campaignId": 1,
"advertiserId": 1,
"name": "Ad group 1" ,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "total",
"totalBudget": 5000,
"deliverySpeed" : "evenly",
"creativeRotationMode": "OPTIMIZE_PERFORMANCE"", "frequencyCapDay" : 1, "frequencyCapWeek" : 3, "frequencyCapMonth" : 5,
"maxBid" : 0.5,
"outOfStockProtection": false,
  "targeting": { "runOfSite": true, "geoTargets": { "include": [ { "zipCode": 35004 } ] } }
}
]'
Batch operation
 curl -X POST \
'https: //developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \
--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 '[ { "campaignId": 1, "advertiserId": 1, "name": "Ad group 1", "startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z", "rateType": "cpm", "budgetType": "daily", "dailyBudget": 500, "deliverySpeed": "evenly", "creativeRotationMode": "OPTIMIZE_PERFORMANCE", "frequencyCapDay": 1, "frequencyCapWeek": 3, "frequencyCapMonth": 5, "maxBid": 0.5,                "outOfStockProtection": false,  
        "targeting": { "and": [ { "and": [ { "keywords": [ { "keywordText": "test-keyword-1", "matchType": "broad" }, { "keywordText": "test-keyword-2", "matchType": "broad" } ] }, { "not": [ { "keywords": [ { "keywordText": "test-keyword-3", "matchType": "exact" } ] } ] } ] }, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } }, { "campaignId": 2, "advertiserId": 1, "name": "Ad group 2", "startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z", "rateType": "cpm", "budgetType": "daily", "dailyBudget": 500, "deliverySpeed": "evenly", "creativeRotationMode": "OPTIMIZE_PERFORMANCE", "frequencyCapDay": 1, "frequencyCapWeek": 3, "frequencyCapMonth": 5, "maxBid": 0.5, "outOfStockProtection": true,
        "targeting": { "and": [ { "contextual": [ { "id": 3452, "reach": "tier_2" }, { "id": 2343, "reach": "tier_3" } ] }, { "geoTargets": [ { "zipCode": "35004" } ] } ] } }
]'

Batch support

Ad group creation supports batch requests. Batch requests are limited to 10 objects and one advertiserId per batch.

See the Batch Requests Guide for limits, retry behavior, and partial success handling.


Response details

What this response returns

The response confirms ad group creation and returns the identifiers required for downstream workflows.

Key fields to use

  • name
    Confirms the ad group created.

  • campaignId
    Identifies the parent campaign.

  • adGroupId
    Required for creative association, status updates, future ad group updates.

  • code
    Indicates if creation request was successful 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

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.

How to interpret results

  • A successful response confirms the ad group exists.
  • The ad group cannot serve until an Approved creative is associated.
  • Batch requests may return mixed success and failure results.

Sample responses

Single ad group
[ { "code": "success", "details": ["string"], "name": "string", "campaignId": 1, "adGroupId": 1234 }
]
Multiple ad groups
[ { "code": "success", "details": "string", "name": "string1", "campaignId": 1, "adGroupId": 1234,     "message": "string", "errors": [ { "field": "string", "errorType": "string", "description": "string" } ]
  }, { "code": "failure", "details": ["string"], "name": "string1", "campaignId": 2, "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ]
 } ]
Sample response - failure
[ { "code": "failure", "details": [ "string" ],    "message": "string",
    "errors": [ { "field": "string", "errorType": "string", "description": "string" } ] }
]

Common issues

  • Mixing multiple targeting tactics in a single ad group
  • Using disabled targeting IDs
  • Combining incompatible geotargeting types
  • Omitting Approved creatives after creation
  • Using budget configuration inconsistent with campaign inheritance rules

What happens next

After creating an ad group:

  1. Associate at least one Approved creative
  2. Validate targeting configuration
  3. Review delivery settings
  4. Activate delivery

Related pages


Did this page help you?