Create New Ad Group

📘
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 Parameters

Parameters	Notes	Type	Required	Possible Values
campaignId	ID of the campaign this ad group belongs to	integer	Y	Unique numeric identifier
advertiserId	ID of advertiser for whom the ad group(s) should be created	integer	Y	Unique numeric identifier
name	The name of the ad group	string	Y	Relevant string value representing the ad group
startDate	date on which the ad group is set to go live Note: startDate must be set either at campaign or ad group level	date. ISO 8601 timezone	This field is required only if it is not set at campaign level	Date should be in format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
endDate	The date when ad group ends Note: endDate must be set either at campaign or ad group level	date. ISO 8601 timezone	This field is required only if it is not set at campaign level	Date should be in format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX To run campaign indefinitely, set its value as "9999-12-30T00:00:00Z"
rateType	rate type refers to the pricing structure	string	N	cpm
budgetType	The type of budget allocation you want to choose for the ad group Note: it must be set either at campaign or ad group level	string	This field is required only if it is not set at campaign level	Values: - daily - total
dailyBudget	Daily budget of ad group Note: • Daily budget cannot exceed your total budget amount • Unspent budget will be rolled over to the next day • Up to 20% of the unspent budget will be rolled over to the following day • it must be set either at campaign or ad group level	double	This field is required only if: -It is not set at campaign level -budgetType is set to be daily	The value of daily budget should at least be $0.01
totalBudget	Total budget of ad group Note: it must be set either at campaign or ad group level	double	This field is required only if: -It is not set at campaign level -budgetType is set to be total	The value of total budget should at least be $0.01
deliverySpeed	Determines pacing of ad delivery Note: it must be set either at campaign or ad group level	string	This field is required only if it is not set at campaign level	Values: • frontloaded • evenly Note: frontloaded pacing is not supported if budgetType is daily
frequencyCapDay	The number of times the ad from specific ad group should be shown to the same user in a day	integer	N	Integer values between 1 and 511
frequencyCapWeek	The number of times the ad from specific ad group should be shown to the same user in a week	integer	N	Integer values between 3 and 511
frequencyCapMonth	The number of times the ad from specific ad group should be shown to the same user in a month	integer	N	Integer values between 5 and 511
baseBid	Starting bid for the ad group	double	N	Value of base bid
maxBid	Max bid value for the ad group	double	N	Value of max bid
targeting	A nested array element with following elements: keywords: ONLY APPLICABLE FOR KEYWORD TARGETING keywordText: string data type matchType: string data type Values: broad, exact Note: only Exact match type is allowed for negative keywords- contexual: ONLY APPLICABLE FOR CONTEXTUAL TARGETING id: integer data type reach: string data type Values: `"tier_1", "tier_2", "tier_3", "tier_4", "tier_5", "tier_6", "tier_7"` Note: This is how tiers in API call map to the representation on ad center UI:` Tier mapping: low = [tier_1, tier_2 ], mid = [tier_3, tier_4 ], high = [tier_5, tier_6, tier_7 ] behavioral: ONLY APPLICABLE FOR BEHAVIORAL TARGETING audienceType: string data type Values: retail brand persona custom attribute: string data type Values: For category: historical predictive For brand: historical predictive lapsed_buyers

Notes:

startDate >= today’s date
startDate <= endDate
total and daily budget should be >= max bid
Budget, Schedule and Delivery speed must be set either at campaign or ad group level
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

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. This key can be repurposed for SP API access as well.
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 further explanation on this
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_CONSUMER.intimestamp	Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp	Y	Use the signature generator code (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

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", "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",
"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",
"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", "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", "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",
"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	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 } ]

📘URL: POST/api/v1/adGroups

Request Parameters

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