Update Existing Ad Group

📘
URL: PUT/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.
Updating multiple ad groups with different targeting types is supported in Bulk. For example: A single bulk payload can include one ad group update request with keyword targeting and another ad group update request with contextual targeting.
PUT API requests will overwrite all current values and are not intended to be used as incremental updates like PATCH operations
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	integer	Y	Unique numeric identifier
adGroupId	The ID of the ad group	integer	Y	Unique numeric identifier
name	The name of the ad group	string	Y	Relevant string value representing the ad group
description	Campaign description Note: Limit on length of campaign description is 240 characters	string	N	Provide valid description corresponding to campaign type
objective	Campaign objective	string	N	Values: • awareness • engagement • conversion Note: Default value for objective will be awareness, unless specified
campaignType	The type of the campaign Note: - You can not update campaignType - Only value supported currently is 'ngd'	string	N	Values of campaignType: ngd
startDate	date on which the ad group is set to go live Note: - it must be set either at campaign or ad group level - You can update startDate only for DRAFT and SCHEDULED ad groups - You can not update startDate when ad group is LIVE	date	N	Date should be in format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
endDate	The date when ad group ends Note: it must be set either at campaign or ad group level	date	N	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’
budgetType	The type of budget allocation you want to choose for your campaign _Note: - it must be set either at campaign or ad group level_ - You can not update budgetType - Ad groups scheduled to run indefinitely must use a daily budget	string	N	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 daily budget can be rolled over to the following day - it must be set either at campaign or ad group level - Ad groups scheduled to run indefinitely must use a daily budget	double	Conditional.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 campaign 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
creativeRotationMode	Specifies the rotation strategy for creatives within an ad group during delivery. Creatives can either be automatically rotated and prioritized based on performance (OPTIMIZE_PERFORMANCE), or distributed evenly with equal weight (ROTATE_EVENLY)	string	N	Enum Values: •OPTIMIZE_PERFORMANCE (Default value) •ROTATE_EVENLY
deliverySpeed	Determines pacing of ad delivery _Note: - it must be set either at campaign or ad group level_ - You can update it only for campaigns in DRAFT state - You cannot update deliverySpeed when ad group is LIVE - You can update deliverySpeed only for DRAFT ad groups	string	Conditional. Required only if not set at campaign level. Cannot be changed to campaign level later	Values: - frontloaded - evenly Note: frontloaded pacing is not supported if budgetType is daily
frequencyCapDay	The number of times the ad from specific adgroup should be shown to the same user on a daily basis	integer	N	Integer values between 1 and 511
frequencyCapWeek	The number of times the ad from specific adgroup should be shown to the same user on a weekly basis	integer	N	Integer values between 3 and 511
frequencyCapMonth	The number of times the ad from specific adgroup should be shown to the same user on a monthly basis	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 For persona: lifestyle lifestage id: integer data type runOfSite ONLY APPLICABLE FOR ROS TARGETING. string data type, Value: true geoTargets id: is used for Country, State, City or DMA targets. integer data type zipCode: is used for zip code targeting. We only support ZIP codes within the USA currently, string data type Note: 1. In an ad group, geo targeting can be set to one of: Country State, City DMA Zip code Refer to the sample requests for creating an Ad Group with ROS to see how zip codes are used in geo-targeting. 2. You cannot combine different geo-targeting types within a single ad group 3. If Geo targeting is not specified, the default Country (US) level targeting will be applied 4. You can update targeting tactic (contextual, behavioral, keyword, ROS) only when ad group is in DRAFT state 5. IDs with isDisabled = true from POST/api/v1/targeting/list cannot be used for targeting	string	N	The values: • keywords • contextual • behavioral • runOfSite • geoTargets

Note:

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, not both

Sample Request

curl -X PUT \
'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_CONSUMER.ID: abcde-v123-fa2r-a1fs-asd45f6qef' \
--header 'WM_SEC.KEY_VERSION: 1' \
--header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '[ { "campaignId": 1, "advertiserId": 1, "adGroupId": 1, "name": "string", "startDate": "string", "endDate": "string", "rateType" : "cpm", "budgetType": "string", "dailyBudget": 0.0, "totalBudget": 0.0, "deliverySpeed": "frontloaded", "creativeRotationMode": "OPTIMIZE_PERFORMANCE", "frequencyCapDay": 0, "frequencyCapWeek": 0, "frequencyCapMonth": 0, "baseBid": 0.0, "maxBid": 0.0, "targeting": { "and": [ { "contextual": [ { "id": 3454, "reach": "tier_1" }, { "id": 245245, "reach": "tier_2" } ] }, { "geoTargets": [
{ "id": 134 }, { "id": 356 }, { "id": 23233 } ] } ] } }
]'

Sample Request (Batch Operation)

curl -X PUT \
'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_CONSUMER.ID: abcde-v123-fa2r-a1fs-asd45f6qef' \
--header 'WM_SEC.KEY_VERSION: 1' \
--header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '[ { "campaignId": 1, "advertiserId": 1, "adGroupId": 1, "name": "string", "startDate": "string", "endDate": "string", "rateType" : "string", "budgetType": "string", "dailyBudget": 0.0, "totalBudget": 0.0, "deliverySpeed": "frontloaded", "creativeRotationMode": "OPTIMIZE_PERFORMANCE", "frequencyCapDay": 0, "frequencyCapWeek": 0, "frequencyCapMonth": 0, "baseBid": 0.0, "maxBid": 0.0, "targeting": { "and": [ { "contextual": [ { "id": 3454, "reach": "tier_1" }, { "id": 245245, "reach": "tier_2" } ] }, { "geoTargets": [
{ "id": 134 }, { "id": 356 }, { "id": 23233 } ] } ] } }, { "campaignId": 1, "advertiserId": 1, "adGroupId": 2, "name": "string", "startDate": "string", "endDate": "string", "rateType": "string", "budgetType": "string", "dailyBudget": 0.0, "totalBudget": 0.0, "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": [ { "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
adGroupId	ID of the Ad Group being updated	integer

Sample Response

[ { "code": "success", "details":"string", "adGroupId": 11 } ]

Sample Response (Batch Operation)

[ { "code": "success", "details": "string", "adGroupId": 11 }, { "code": "failure", "details": ["string"], "adGroupId": 12 } ]

📘URL: PUT/api/v1/adGroups

Request Parameters

Sample Request

Sample Request (Batch Operation)

Response

Sample Response

Sample Response (Batch Operation)

📘
URL: PUT/api/v1/adGroups