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 ruleAn ad group must have at least one Approved creative associated before it can serve impressions.
Configuration ruleBudget, 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
POST /api/v1/adGroupsRequest 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.
Targeting rules
- Exactly one primary targeting tactic per ad group
- Geotargeting may be combined with any targeting tactic
- Targeting IDs with
isDisabled=truecannot 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.
| budgetType | dailyBudget | totalBudget | deliverySpeed |
|---|---|---|---|
daily | Required | N/A | N/A |
total | N/A | Required | Required (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:00Zas the end date to implement) - Unlimited end dates cannot be combined with total budget
Bidding
Bidding controls competitive delivery.
Bid rules
maxBidmust be at least $0.01- Bid values determine delivery competitiveness
Ad serving behavior
Ad serving is controlled using:
Creative rotation
OPTIMIZE_PERFORMANCEROTATE_EVENLY
Frequency caps
frequencyCapDayfrequencyCapWeekfrequencyCapMonth
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 supportThis 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 supportAd group creation supports batch requests. Batch requests are limited to 10 objects and one
advertiserIdper 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:
- Associate at least one Approved creative
- Validate targeting configuration
- Review delivery settings
- Activate delivery
Related pages
Updated 25 days ago
