Guides

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

ParametersNotesTypeRequiredPossible Values
campaignIdID of the campaign this ad group belongs tointegerYUnique numeric identifier
advertiserIdID of advertiserintegerYUnique numeric identifier
adGroupIdThe ID of the ad groupintegerYUnique numeric identifier
nameThe name of the ad groupstringYRelevant string value representing the ad group
startDatedate 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		dateNDate should be in format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX

Note:
  • All timestamp values must be in ISO 8601 format (e.g., "2025-07-20T19:10:10-05:00").
  • All date-time values are internally converted to Eastern Time (ET) for processing and normalized to the start of the hour. This means minutes and seconds are truncated. Example: "2025-07-20T19:10:10-05:00" becomes "2025-07-20T19:00:00-05:00" in ET

Kindly take these behaviors into consideration when assigning a value to startDate in your request.
endDateThe date when ad group ends
Note: it must be set either at campaign or ad group level		dateNDate 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’

Note:
  • All timestamp values must be in ISO 8601 format (e.g., "2025-07-20T19:10:10-05:00").
  • All date-time values are internally converted to Eastern Time (ET) for processing and normalized to the start of the hour. This means minutes and seconds are truncated. Example: "2025-07-20T19:10:10-05:00" becomes "2025-07-20T19:00:00-05:00" in ET
  • The endDate must be set to a time after 12:00 PM ET. If the provided value is before 12:00 PM ET, the system will return an error.
  • Special Case: If you set endDate to exactly "00:00:00" ET (e.g., "2025-07-20T00:00:00-05:00"), it will be interpreted as the end of the previous day: "2025-07-19T23:59:59-05:00".

Kindly take these behaviors into consideration when assigning a value to startDate in your request.
budgetTypeThe 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		stringNValues:

- daily
- total
dailyBudgetDaily 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		doubleConditional.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
totalBudgetTotal budget of campaign
Note: it must be set either at campaign or ad group level		doubleThis 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
creativeRotationModeSpecifies 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)		stringNEnum Values:

•OPTIMIZE_PERFORMANCE (Default value)
•ROTATE_EVENLY
deliverySpeedDetermines 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		stringConditional. Required only if not set at campaign level. Cannot be changed to campaign level laterValues:

- frontloaded
- evenly
Note: frontloaded pacing is not supported if budgetType is daily
frequencyCapDayThe number of times the ad from specific adgroup should be shown to the same user on a daily basisintegerNInteger values between 1 and 511
frequencyCapWeekThe number of times the ad from specific adgroup should be shown to the same user on a weekly basisintegerNInteger values between 3 and 511
frequencyCapMonthThe number of times the ad from specific adgroup should be shown to the same user on a monthly basisintegerNInteger values between 5 and 511
baseBidstarting bid for the ad groupdoubleNValue of base bid
maxBidmax bid value for the ad groupdoubleNValue of max bid
targetingA 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
      • demographic
    • attribute: string data
      type
      Values:
      • For category(retail ):
        • historical
        • predictive
      • For brand:
        • historical
        • predictive
        • lapsed_buyers
      • For persona:
        • lifestyle
        • lifestage
        • auto
        • shopping_habits
        • food_beverages
      • For demographic:
        • age
        • gender
        • household_income
      • For custom:
        • rule_based
        • propensity
        • brand_affinity
        • lookalike
        • advanced
        • external
    • 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		stringNThe 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

Updatable Ad Group Metadata Fields


The following table describes fields from the ad group metadata that can be updated using PUT /api/v1/adGroups.

API Field NameDisplay Label in MatrixDraftScheduledLivePausedCompleteArchivedNotes
nameAd Group Name✅✅✅✅⚠️❌Updatable only if endDate is extended into future
startDateStart Date✅✅❌❌❌❌—
endDateEnd Date✅✅✅✅✅❌Can be indefinite only in Draft
budgetTypeBudget Type✅❌❌❌❌❌Immutable
dailyBudget, totalBudgetBudget (Daily & Total)✅✅✅✅⚠️❌1. For evergreen campaigns, only Daily budget supported.
2. Extend endDate to edit if Complete
deliverySpeedDelivery Speed✅❌❌❌❌❌Frontloaded pacing not supported if budgetType is daily
frequencyCapDay, frequencyCapWeek, frequencyCapMonthFrequency Cap✅✅✅✅⚠️❌Extend endDate if Complete
baseBid, maxBidBids✅✅✅✅⚠️❌Extend endDate if Complete
targeting.contextualTargeting Tactic – Contextual✅Add/RemoveAdd/RemoveAdd/Remove⚠️❌1. Tactic only changeable in Draft. Else you can only add/remove taxonomies.
2. Extend endDate to edit if Complete
targeting.behavioralTargeting Tactic – Behavioral✅Add/RemoveAdd/RemoveAdd/Remove⚠️❌1. Tactic only changeable in Draft. Else you can only add/remove audiences.
2. Extend endDate to edit if Complete
targeting.keywordsTargeting Tactic – Keywords✅Add/RemoveAdd/RemoveAdd/Remove⚠️❌1. Tactic only changeable in Draft. Else you can only add/remove keywords.
2. Extend endDate to edit if Complete
targeting.runOfSiteTargeting Tactic – ROS✅❌❌❌⚠️❌1. Tactic only changeable in Draft.
2. Extend endDate to edit if Complete
targeting.geoTargetsGeo targeting✅✅✅✅⚠️❌Extend endDate if Complete
creativeRotationModeCreative rotation mode✅✅✅✅⚠️❌Extend endDate if Complete
creativeRotationModeCreative rotation mode✅✅✅✅⚠️❌Extend endDate if Complete
attributesSetOnAdGroupLevel———————Configuration flag; not user-editable
rateTypeRate Type——————Immutable
creationDate, lastUpdatedDate———————Metadata only

If you'd like, I can also:

  • Clean this up for inclusion in your standard endpoint template
  • Normalize duplicate rows (e.g., creativeRotationMode)
  • Add ✔ / ✖ indicators for clarity
  • Export this as .md file format

Sample Request 1 - Update 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, "adGroupId": 11, "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, "baseBid": 0.1, "maxBid": 0.5, "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 } ] } ] } } ]'

Sample Request 2 - Update 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,
"adGroupId": 12,
"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,
"baseBid" : 0.1,
"maxBid" : 0.5, "targeting" : { "and": [ { "contextual": [ { "id": 3452, "reach": "tier_2" }, { "id": 2343, "reach": "tier_3" } ] }, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } }
]'

Sample Request 3 - Update Ad group with Audience 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,
"adGroupId": 13,
"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,
"baseBid" : 0.1,
"maxBid" : 0.5, "targeting" : { "and": [ { "behavioral": [ { "audienceType": "retail", "attribute": "historical", "id": 134 }, { "audienceType": "retail", "attribute": "historical", "id": 243234 } ]
}, { "geoTargets": [ { "id": 123 }, { "id": 134 }, { "id": 1233 } ] } ] } }
]'

Sample Request 4 - Update Ad group with Run of Site 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,
"adGroupId": 14,
"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,
"baseBid" : 0.1,
"maxBid" : 0.5, "targeting" : { "and": [ { "runOfSite": true }, { "geoTargets": [ { "zipCode":"35004" } ] } ] } }
]'

Sample Request 5 - 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, "adGroupId": 11, "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, "baseBid": 0.1, "maxBid": 0.5, "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": 1, "advertiserId": 1, "name": "Ad group 2", "adGroupId": 12, "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, "baseBid": 0.1, "maxBid": 0.5, "targeting": { "and": [ { "contextual": [ { "id": 3452, "reach": "tier_2" }, { "id": 2343, "reach": "tier_3" } ] }, { "geoTargets": [ { "zipCode": "35004" } ] } ] }
} ]'

Response

ElementDescriptionType
codeThe response code can have following values:
  • success
  • failure

Click here for more information about Status Codes and Errors		string
detailsDetails will populate success or error message depending upon value of codestring
adGroupIdID of the Ad Group being updatedinteger

Sample Response 1

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

Sample Response 2

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

Sample Response 3

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

Sample Response 4

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

Sample Response 5

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

Updated 9 days ago