📘
URL: POST/api/v1/adGroups

Note:

This API supports batch operations with a max batch size of 10. For bulk operation, the advertiserId must be the same across all requests in the payload
Creating multiple ad groups with different targeting types is supported in Bulk. For example: A single bulk payload can include one ad group Create request with keyword targeting and another ad group create request with contextual targeting
You must set all of: budgetType, dailyBudget, totalBudget, startDate, endDate, and deliverySpeed parameters at same level i.e. either at campaign level or ad group level

Request Body

Core Parameters

Parameter	Description	Required	Data Type	Possible Values / Notes
advertiserId	ID of the advertiser for whom the ad group(s) should be created.	Y	Integer	A valid advertiser ID
campaignId	ID of the campaign this ad group belongs to.	Y	Integer	A valid campaign ID
name	Name of the ad group. Maximum length: 255 characters.	Y	String	Valid name of the ad group
startDate	Date on which the ad group is set to go live.	Conditional	String	Required if not set at the ad group level Must be ISO 8601 format: `yyyy-MM-dd'T'HH:mm:ss.SSSXXX` Campaigns must start on the hour Minutes and seconds are truncated (e.g., 23:45 → 23:00)
endDate	Date when the ad group ends.	Conditional	String	Required if not set at the ad group level Must be ISO 8601 format: `yyyy-MM-dd'T'HH:mm:ss.SSSXXX` Use `9999-12-30T00:00:00Z` for indefinite run Campaigns must end on the hour Minutes and seconds are truncated (e.g., 23:45 → 23:00) Campaigns cannot end before 12:00 PM ET, except: If `endDate` is set to 00:00 (e.g., `2025-07-20T00:00:00-05:00`), it is interpreted as the end of the previous day (`2025-07-19T23:59:00-05:00`)
isInventoryAware	Opt in or out of inventory-aware delivery at the ad group level.	N	Boolean	true / false
rateType	Pricing structure for the ad group.	N	String	cpm
budgetType	Type of budget allocation.	Conditional	String	daily total Required if not set at the campaign level Ad groups scheduled to run indefinitely must use a daily budget
dailyBudget	Daily budget of the ad group.	Conditional	Double	Required if `budgetType` is `daily` Minimum value: $0.01
totalBudget	Total budget of the ad group.	Conditional	Double	Required if `budgetType` is `total` Minimum value: $0.01
deliverySpeed	Determines pacing of ad delivery.	Conditional	String	frontloaded evenly Required if not set at the campaign level Frontloaded pacing is not supported when `budgetType` is `daily`

Additional Parameters

Parameter	Description	Required	Data Type	Possible Values
creativeRotationMode	Rotation strategy for creatives during delivery.	N	String	OPTIMIZE_PERFORMANCE (default) ROTATE_EVENLY
frequencyCapDay	Max impressions per user per day.	N	Integer	Valid range: 1–511
frequencyCapWeek	Max impressions per user per week.	N	Integer	Valid range: 3–511
frequencyCapMonth	Max impressions per user per month.	N	Integer	Valid range: 5–511
baseBid	Starting bid for the ad group.	N	Double	Minimum value: $0.01
maxBid	Maximum bid for the ad group.	N	Double	Minimum value: $0.01
targeting	Nested targeting object, see Targeting Object section below for more details.	N	JSON object	Contains targeting parameters, see Targeting Object section below for more details.

Targeting Object

Type: Object
Required: No

Nested targeting object. An ad group may use only one of the following tactics, optionally combined with geo targeting using an AND relation.

keywords: Ads shown based on search or browsing terms. Each entry requires keywordText and matchType. Negative keywords support only exact match. Keyword targeting is not supported for Video campaigns.
contextual: Ads placed on pages relevant to content themes. Requires a contextual taxonomy node ID and optional reach tier.
behavioral: Targets users based on shopping behavior or intent signals using audience segments.
runOfSite: Enables site-wide delivery with no specific targeting constraints. Other targeting types must not be set.
geoTargets: Restricts ad delivery to specific geographic regions.

Targeting Object Structure

Keywords and Negative Keywords

{ "targeting": { "and": [ { "and": [ { "keywords": [{ "keywordText": "...", "matchType": "..." }] }, { "not": [{ "keywords": [{ "keywordText": "...", "matchType": "..." }] }] } ] }, { "geoTargets": [ ... ] } ] }
}

Field	Description	Required	Data Type	Notes
keywordText	Text defining the keyword	Yes	String	—
matchType	Matching criteria	Yes	String	broad, exact (negative keywords: exact only)

Contextual Targeting

{ "targeting": { "and": [ { "contextual": [{ "id": ..., "reach": "..." }] }, { "geoTargets": [ ... ] } ] }
}

Field	Description	Required	Data Type	Notes
id	Contextual taxonomy node ID	Yes	Integer	—
reach	Contextual reach tier	Yes	String	tier_1 tier_2 tier_3 tier_4 tier_5 tier_6 tier_7

Behavioral Targeting

{ "targeting": { "and": [ { "behavioral": [{ "id": ..., "audienceType": "...", "attribute": "..." }] }, { "geoTargets": [ ... ] } ] }
}

audienceType: retail, brand, persona, custom, demographic
attribute:
- Category: historical, predictive
- Brand: historical, predictive, lapsed_buyers
- Persona: lifestyle, lifestage, auto, shopping_habits, food_beverages
- Demographic: age, gender, household_income

Run of Site (ROS) Targeting

{ "targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ ... ] } ] }
}

Field	Description	Required	Data Type
runOfSite	Enables ROS targeting	Yes	Boolean

Geo Targeting

Country
State, City
DMA
Zip Code (USA only)

If geo-targeting is omitted, Country (US) is applied by default.
Only one geo-targeting type may be used per ad group, not both.

For example:

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

Or:

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

Rules

startDate must be today or later
startDate must be less than or equal to endDate
Daily or total budget must be greater than or equal to max bid
Only one of dailyBudget or totalBudget may be set
Budget, schedule, and delivery speed must be set at the same level (campaign or ad group)
Targeting IDs marked isDisabled = true cannot be used
Campaigns must be homogeneous: all VIDEO or all BANNER
mediaType, if provided, is ignored

Targeting Rules

Only one targeting tactic is allowed: keywords, contextual, behavioral, or runOfSite
Geo targeting may be combined using AND logic
All targeting must use the and array structure
Video Ad Group restrictions:
- Keyword targeting is not supported
- Run-of-site ads do not serve on Item Page placement
- Contextual ads do not serve on Homepage Feature_4

Headers

Header Name	Description	Required	Values
Authorization	The token will provide you the access to the API. It is same for all advertisers you access through the API.	Y	Please utilize the generated `auth_token` shared with you at the time of partner onboarding from the Getting Started Guide
Content-Type	application/json	Y	n/a
WM_CONSUMER.ID	We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.	Y	Please use the generated `ConsumerId` shared with you at the time of partner onboarding. Refer to the Getting Started Guide for more information
WM_SEC.AUTH_SIGNATURE	Auth signature as an API key.	Y	Use the signature generator code from Getting Started Guide to generate this value
WM_SEC.KEY_VERSION	We will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API.	Y	1
WM_CONSUMER.intimestamp	Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp.	Y	Use the signature generator code from Getting Started Guide to generate this value

Sample Request: Create Ad Group with Keyword Targeting

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": name1,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "daily",
"dailyBudget": 500, "totalBudget": 5000, "deliverySpeed" : "evenly", "creativeRotationMode": "OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 0, "frequencyCapWeek" : 0, "frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "keywords": [ { "keywordText": "test-keyword-1", "matchType": "broad" }, { "keywordText": "test-keyword-2", "matchType": "exact" } ], "not": [ { "keywords": [ { "keywordText": "test-keyword-negative", "matchType": "exact" } ] } ] }, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } }
]'

Sample Request: Create Ad Group with Contextual Targeting

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": name1,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "daily",
"dailyBudget": 500,
"totalBudget": 5000,
"deliverySpeed" : "evenly",
"creativeRotationMode":"OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 0, "frequencyCapWeek" : 0, "frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "contextual": [ { "id": 3452, "reach": "tier_2" }, { "id": 2343, "reach": "tier_3" } ]
}, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } }
]'

Sample Request: Create Ad Group with Behavioral Targeting

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": name1,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z", "rateType" : "cpm",
"budgetType" : "daily",
"dailyBudget": 500,
"totalBudget": 5000,
"deliverySpeed" : "evenly",
"creativeRotationMode": OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 0,
"frequencyCapWeek" : 0,
"frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "behavioral": [ { "audienceType": "retail", "attribute": "historical", "id": 134 }, { "audienceType": "retail", "attribute": "historical", "id": 243234 } ]
}, { "geoTargets": [ { "id": 123 }, { "id": 134 }, { "id": 1233 } ] } ] } }
]'

Sample Request: Create Ad Group with ROS

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": name1,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "daily",
"dailyBudget": 500,
"totalBudget": 5000,
"deliverySpeed" : "evenly",
"creativeRotationMode": OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 0, "frequencyCapWeek" : 0, "frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "runOfSite": true }, { "geoTargets": [ { "zipCode":"35004" } ] } ] } }
]'

Sample Request (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": "string",
"startDate": "string",
"endDate": "string",
"rateType" : "string",
"budgetType" : "string",
"dailyBudget": 0.0, "totalBudget": 0.0, "deliverySpeed" : "string", "deliverySpeed" : "string", "creativeRotationMode": "OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 0,
"frequencyCapWeek" : 0,
"frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "keywords": [ { "keywordText": "test-keyword-1", "matchType": "broad" }, { "keywordText": "test-keyword-2", "matchType": "exact" } ], "not": [ { "keywords": [ { "keywordText": "test-keyword-negative", "matchType": "broad" } ] } ] }, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } }, { "campaignId": 1,
"advertiserId": 1,
"name": string1,
"startDate": "string", "endDate": "string",
"rateType" : "string",
"budgetType" : "string",
"dailyBudget": 0.0,
"totalBudget": 0.0,
"deliverySpeed" : "string",
"creativeRotationMode": "string", "frequencyCapDay" : 0, "frequencyCapWeek" : 0, "frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "contextual": [ { "id": 3452, "reach": "tier_2" }, { "id": 2343, "reach": "tier_3" } ] }, { "geoTargets": [ { "zipCode":"35004" } ] } ] } } ]'

Response

Element	Description	Type
code	The response code can have following values: success failure Click here for more information about Status Codes and Errors	string
details	Details will populate success or error message depending upon value of code	string
name	Name of the campaign	string
adGroupId	ID of the Ad Group. This will be returned only when code=success	integer
campaignId	ID of the campaign. This will be returned only when code=success	integer

Sample Response

[ { "code": "success", "details": "string", "name": "string1", "campaignId": 1, "adGroupId": 1234 }
]

Sample Response (Batch Operation)

[ { "code": "success", "details": "string", "name": "string1", "campaignId": 1, "adGroupId": 1234 }, { "code": "failure", "details": ["string"], "name": "string1", "campaignId": 1 } ]

Create New Ad Group

📘
URL: POST/api/v1/adGroups

Request Body

Core Parameters

Additional Parameters

Targeting Object

Targeting Object Structure

Keywords and Negative Keywords

Contextual Targeting

Behavioral Targeting

Run of Site (ROS) Targeting

Geo Targeting

Rules

Targeting Rules

Headers

Sample Request: Create Ad Group with Keyword Targeting

Sample Request: Create Ad Group with Contextual Targeting

Sample Request: Create Ad Group with Behavioral Targeting

Sample Request: Create Ad Group with ROS

Sample Request (Batch Operation)

Response

Sample Response

Sample Response (Batch Operation)

📘URL: POST/api/v1/adGroups

Request Body

Core Parameters

Additional Parameters

Targeting Object

Targeting Object Structure

Keywords and Negative Keywords

Contextual Targeting

Behavioral Targeting

Run of Site (ROS) Targeting

Geo Targeting

Rules

Targeting Rules

Headers

Sample Request: Create Ad Group with Keyword Targeting

Sample Request: Create Ad Group with Contextual Targeting

Sample Request: Create Ad Group with Behavioral Targeting

Sample Request: Create Ad Group with ROS

Sample Request (Batch Operation)

Response

Sample Response

Sample Response (Batch Operation)

📘
URL: POST/api/v1/adGroups