Guides

Update Existing Ad Group - PATCH

📘

URL: PATCH /api/v1/adGroups


  • 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.

  • 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. Attempting to alter the "level" at which they are set via a PATCH request will result in a validation error.

  • Supports both expression-based and flattened targeting structure. Only one of expression based or flattened structure should be used in a request. More details here

  • Fields can be explicitly cleared or unset by passing null.

  • Delta Targeting Update: This endpoint uniquely supports an add and remove schema for targeting, allowing you to modify keyword or audience lists without uploading the entire list again. More details

    here

  • For details on updatable fields through PUT and PATCH operations, refer to this link

    Request Parameters

ParametersNotesTypeRequiredPossible Values
advertiserIdID of advertiserintegerYUnique numeric identifier
adGroupIdIdentifier of ad group to updateintegerYUnique numeric identifier
nameThe name of the ad group.
Maximum length: 255 characters		stringNRelevant string value representing the ad group
startDateDate on which the ad group is set to go livestringConditional
Required if set at ad group level.
  • All timestamp values 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).
endDateThe date when ad group endsdateConditional
Required if set at ad group level.
  • All timestamp values must be in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX (e.g., "2025-07-20T19:10:10-05:00")
  • 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 in one case:
    • If you set endDate to 00:00 (e.g., "2025-07-20T00:00:00-05:00"), the system will interpret it as the end of the previous day (2025-07-19T23:59:00-05:00), allowing you to schedule a campaign through the full day.
rateTypeRate type refers to the pricing structurestringNcpm
budgetTypeType of budget allocationstringConditional
Required if not set at the campaign level		Values: daily, total
Ad groups scheduled to run indefinitely must use a daily budget.
dailyBudgetDaily budget of the ad group.doubleConditional
Required if budgetType is set to daily.		The value of daily budget should at least be $0.01
totalBudgetTotal budget of the ad group.doubleConditional
Required if budgetType is set to total.		The value of total budget should at least be $0.01
deliverySpeedDetermines pacing of ad deliverystringConditional. Required if not set at the campaign level.Values:
frontloaded, evenly
Note: frontloaded pacing is not supported if budgetType is daily
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
frequencyCapDayThe number of times the ad from specific adgroup should be shown to the same user on a daily basis
To clear frequencyCapDay pass null		integerNInteger values between 1 and 511
frequencyCapWeekThe number of times the ad from specific adgroup should be shown to the same user on a weekly basis
To clear frequencyCapWeek pass null		integerNInteger values between 3 and 511
frequencyCapMonthThe number of times the ad from specific adgroup should be shown to the same user on a monthly basis
To clear frequencyCapMonth pass null		integerNInteger values between 5 and 511
maxBidmax bid value for the ad group
Can be cleared/unset only in the draft state		doubleNValue of max bid
Minimum value: $0.01
targetingPlease find targeting object details herestringNThe 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


Targeting Objects

The targeting object can either be replaced fully or can be incrementally updated using add and remove arrays.

For Ad Groups with Keywords and Negative Keywords Targeting

ParameterParameter DescriptionTypeRequiredPossible Values
keywordTextText that defines the keywordstringYAdvertiser ID for which the campaign needs to be updated for delivery status
matchTypeMatching criteria for the keywordsstringYbroad, exact
For negative keywords only exact matchType is allowed

For Ad Groups with Contextual Targeting

ParameterParameter DescriptionTypeRequiredPossible Values
idID of the contextual nodeintegerY
reachDetermines contextual reach.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 ]
stringY
  • tier_1
  • tier2
  • tier_3
  • tier_4
  • tier_5
  • tier_6
  • tier_7

For Ad Groups with Behavioral Targeting

ParameterParameter DescriptionTypeRequiredPossible Values
idID of the audience obtained from List targeting endpointintegerY
audienceTypeType of audiencestringY
  • retail
  • brand
  • persona
  • custom
  • demographic
attributeAttribute of the audiencestringY
  • For category:
    • historical
    • predictive
  • For brand:
    • historical
    • predictive
    • lapsed_buyers
  • For persona:
    • lifestyle
    • lifestage
    • auto
    • shopping_habits
    • food_beverages
  • For demographic:
    • age
    • gender
    • household_income

For Ad Groups with ROS Targeting

ParameterParameter DescriptionTypeRequiredPossible Values
runOfSiteIndicates whether run‑of‑site targeting is enabledbooleanY
  • true
  • false

Geo targeting 

Can be set to one of: 

  • Country
  • State,City
  • DMA
  • Zip code

If omitted will be default set to country (US). You cannot combine different geo-targeting types within a single ad group

ParameterParameter DescriptionTypeRequiredPossible Values
idis used for Country, State, City or DMA targetsintegerY
zipCodeis used for zip code targeting.We only support ZIP codes within the USA currentlystringY

Headers

Header NameDescriptionRequiredValues
AuthorizationThe token will provide you the access to the API. It is same for all advertisers you access through the API.YPlease utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
Content-TypeFormat of the message bodyYapplication/json
WM_CONSUMER.IDUnique ID for consumer. We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.   YPlease 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_SIGNATUREAuth signature as an API key.YUse the signature generator code from Getting Started Guide to generate this value
WM_SEC.KEY_VERSIONKey version. We will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API.Y1
WM_CONSUMER.intimestampTimestamp for which the auth signature is generated. Use Unix epoch format for the timestamp.YUse the signature generator code from Getting Started Guide to generate this value


📌

Rules

  • startDate >= today’s date
  • startDate <= endDate
  • total and daily budget should be >= max bid
  • You can only set either dailyBudget or totalBudget
  • To set daily budget, you must choose value of budgetType as “daily” and then define dailyBudget.
  • To set total budget, you must choose value of budgetType as “total” and then define totalBudget.
  • 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, not both
  • IDs with isDisabled = true from POST/api/v2/targeting/list cannot be used for targeting
  • Campaigns must be homogeneous; if mediaType is VIDEO, all ad groups will be VIDEO; if mediaType is BANNER, all ad groups will be BANNER. Mixing VIDEO and BANNER ad groups within the same campaign is not allowed.
  • mediaType, if included in the request payload, is ignored and has no effect on processing.
  • The update rules for PATCH are similar to the update rules for PUT
📌

Targeting Rules

  • Only one of keywords, contextual, behavioral, or runOfSite is allowed.
  • geoTargets can be combined with the selected targeting tactic.
  • Patch supports both expression based targeting structure and flattened targeting structure, and the user should pass only one of them in the request body.
  • For geo targeting (Refer to the sample requests for creating an Ad Group with ROS to see how zip codes are used in geo-targeting):
    • In an ad group, geo targeting can be set to one of:
      • Country
      • State, City
      • DMA
      • Zip code
    • You cannot combine different geo-targeting types within a single ad group
    • If geo targeting is not specified, the default Country (US) level targeting will be applied
  • When setting up targeting for Video Ad Groups, the following restrictions apply:
    • Keywords targeting is not supported for ad groups in campaigns with mediaType = VIDEO.
    • Ad groups with runOfSite targeting will not serve on Item Page placement.
    • Ad groups with contextual targeting will not serve on Homepage Feature_4
  • Mixing replace (plain array) and delta (add/remove object) in the same targeting request is not allowed and returns HTTP 400

Sample Request 1 - Update name, frequencyCapDay, frequencyCapWeek and targeting for an ad group(Expression based Targeting Structure)

curl -X PATCH \
'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 '[ { "advertiserId": 1, "adGroupId": 11, "name": "Ad Group 1", "frequencyCapDay": 1, "frequencyCapWeek": 3, "targeting": { "and": [ { "contextual": [ { "id": 3452, "reach": "tier_2" }, { "id": 2343, "reach": "tier_3" } ] }, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } }
]'

Sample Request 2 - Update name, frequencyCapDay, frequencyCapWeek and targeting for an ad group(Flattened Targeting Structure)

curl -X PATCH \
'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 '[ { "advertiserId": 1, "adGroupId": 11, "name": "Ad Group 1" , "frequencyCapDay": 1, "frequencyCapWeek": 3, "targeting": { "contextual": { "include": [ { "id": 3455, "reach": "tier_2" }, { "id": 3455, "reach": "tier_2" } ] } }, "geoTargets": { "include": [ { "id": 123 }, { "id": 122 } ] } } } ]'

Sample Request 3 - Update multiple adGroups (Expression based Targeting Structure)

Fields being patched

In adgroup 11:

  • frequencyCapDay
  • frequencyCapWeek
  • frequencyCapMonth

In adgroup 12:

  • endDate
  • frequencyCapMonth
curl -X PATCH \
'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 '[ { "advertiserId": 1, "adGroupId": 11, "frequencyCapDay": null, "frequencyCapWeek": null, "frequencyCapMonth": null, "targeting": { "and": [ { "and": [ { "keywords": [ { "keywordText": "running shoes", "matchType": "BROAD" } ] }, { "not": [ { "keywords": [ { "keywordText": "cheap shoes", "matchType": "EXACT" } ] } ] } ] }, { "geoTargets": [ { "id": 234 }, { "id": 235 } ] } ] } }, { "advertiserId": 1, "adGroupId": 12, "endDate": "2023-12-09T12:00:00Z", "frequencyCapMonth": 5, "targeting": { "and": [ { "behavioral": [ { "id": 134, "audienceType": "retail", "attribute": "historical" } ] }, { "geoTargets": [ { "id": 234 }, { "id": 235 } ] } ] } }
] '

Sample Request 4 - Update multiple adGroups and add/remove keywords (Flattened Targeting Structure)

curl -X PATCH \
'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 '[ { "advertiserId": 1, "adGroupId": 11, "frequencyCapDay": null, "frequencyCapWeek": null, "frequencyCapMonth": null, "targeting": { "keywords": { "include": { "add": [ { "matchType": "BROAD", "keywordText": "running shoes" }, { "matchType": "PHRASE", "keywordText": "trail sneakers" } ], "remove": [ { "matchType": "BROAD", "keywordText": "old broad term" }, { "matchType": "BROAD", "keywordText": "new broad term" } ] }, "exclude": { "add": [ { "matchType": "EXACT", "keywordText": "free shoes" }, { "matchType": "EXACT", "keywordText": "nike shoes" } ], "remove": [ { "matchType": "EXACT", "keywordText": "cheap shoes" }, { "matchType": "EXACT", "keywordText": "old shoes" } ] } } }, "geoTargets": { "include": [ { "id": 234 }, { "id": 235 } ] } } }, { "advertiserId": 1, "adGroupId": 12,= "endDate": "2023-12-09T12:00:00Z", "frequencyCapMonth": 5, "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": 234 }, { "id": 235 } ] } } }
]'

Sample Request 5 - Update ad group end date

curl -X PATCH \
'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 '[     { "advertiserId": 1, "adGroupId": 11, "endDate": "2024-12-09T12:00:00Z" } ]'

Sample Request 6 - Partial success example for adGroup batch update

curl -X PATCH \
'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 '[ { "advertiserId": 1, "adGroupId": 11, "frequencyCapDay": null, "frequencyCapWeek": null, "frequencyCapMonth": null, "targeting": { "keywords": { "include": { "add": [ { "matchType": "BROAD", "keywordText": "running shoes" }, { "matchType": "PHRASE", "keywordText": "trail sneakers" } ], "remove": [ { "matchType": "BROAD", "keywordText": "old broad term" } ] }, "exclude": { "add": [ { "matchType": "EXACT", "keywordText": "free shoes" } ], "remove": [ { "matchType": "EXACT", "keywordText": "cheap shoes" } ] } } }, "geoTargets": { "include": [{"id": 234},{"id": 235}] }
} },
{ "advertiserId": 1, "adGroupId": 12, "endDate": "2023-12-09T12:00:00Z", "frequencyCapMonth": 5, "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": 234 }, { "id": 235 } ] } }
}
]'

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 Success - Update name, frequencyCapDay, frequencyCapWeek and targeting for an ad group(Expression based Targeting Structure)

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

Sample Response 1 Failure - Update name, frequencyCapDay, frequencyCapWeek and targeting for an ad group(Expression based Targeting Structure)


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

Sample Response 2 Success - Update name, frequencyCapDay, frequencyCapWeek and targeting for an ad group(Flattened Targeting Structure)

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

Sample Response 2 Failure - Update name, frequencyCapDay, frequencyCapWeek and targeting for an ad group(Flattened Targeting Structure)

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

Sample Response 3 Success - Update multiple adGroups (Expression based Targeting Structure)

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

Sample Response 3 Failure - Update multiple adGroups (Expression based Targeting Structure)

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

Sample Response 4 Success - Update multiple adGroups and add/remove keywords (Flattened Targeting Structure)

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

Sample Response 4 Failure- Update multiple adGroups and add/remove keywords (Flattened Targeting Structure)

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

Sample Response 5 Success - Update ad group end date

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

Sample Response 5 Failure - Update ad group end date

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

Sample Response 6 Success - Partial success example for adGroup batch update

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

Delta Targeting Update

Update targeting criteria - Full Replacement (PUT/PATCH) 

When creating or fully updating an ad group, pass arrays of objects to the include and exclude keys.

include: replaces all existing included keywords/audiences/contextual nodes
exclude : replaces all existing excluded keywords/audiences/contextual nodes

"targeting": { "keywords": { "include": [ { "keywordText": "running shoes", "matchType": "broad" }, { "keywordText": "trail sneakers", "matchType": "exact" } ], "exclude": [ { "keywordText": "sandals", "matchType": "exact" } ] }, "geoTargets": { "include": [ { "zipCode": "35004" } ] }
}

Update targeting criteria - Delta Updates (PATCH Only)

When using the PATCH endpoint, the Flattened Structure supports incremental updates. Instead of passing an array to include or exclude, you pass an object containing add and/or remove arrays . This allows you to update massive keyword or audience lists without re-uploading the entire list.

Note: You cannot mix array replacement and add/remove delta patching in the same request.

  • include.add: Adds new keywords/audiences/contextual nodes to inclusion list

  • include.remove: Removes keywords/audiences/contextual nodes from inclusion list

  • exclude.add: Adds keywords/audiences/contextual nodes to exclusion list

  • exclude.remove: Removes keywords/audiences/contextual nodes from exclusion list

"targeting": { "behavioral": { "include": { "add": [ { "id": 134, "audienceType": "retail", "attribute": "historical" } ], "remove": [ { "id": 234, "audienceType": "retail", "attribute": "historical" } ] } }
}

Reference Schema:

keywords tactic - Full Replacement (PUT/PATCH) 

"targeting": { "keywords": { "include": [ { "matchType": "...", "keywordText": "..." }, { "matchType": "...", "keywordText": "..." } ], "exclude": [ { "matchType": "...", "keywordText": "..." } ] }, "geoTargets": { "include": [ ... ] }
}

keywords tactic - Delta Updates (PATCH Only)

"targeting": { "keywords": { "include": { "add": [ { "matchType": "...", "keywordText": "..." }, { "matchType": "...", "keywordText": "..." } ], "remove": [ { "matchType": "...", "keywordText": "..." } ] }, "exclude": { "add": [ { "matchType": "...", "keywordText": "..." } ], "remove": [ { "matchType": "...", "keywordText": "..." } ] } } }, "geoTargets": { "include": [ ... ] }
}

contextual tactic - Full Replacement (PUT/PATCH) 

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

contextual tactic - Delta Updates (PATCH Only)

"targeting": { "contextual": { "include": { "add": [ {{"id": ..., "reach": "..."}} ], "remove": [ {{"id": ..., "reach": "..."}} ] } }, "geoTargets": { "include": [ ... ] }
}

behavioral tactic - Full Replacement (PUT/PATCH) 

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

behavioral tactic - Delta Updates (PATCH Only)

"targeting": { "behavioral": { "include": { "add": [{ "id": ..., "audienceType": "...", "attribute": "..." }], "remove": [{ "id": ..., "audienceType": "...", "attribute": "..." }] }, "exclude": { "add": [{ "id": ..., "audienceType": "...", "attribute": "..." }], "remove": [{ "id": ..., "audienceType": "...", "attribute": "..." }] } } }, "geoTargets": { "include": [ ... ] }
}

runOfSite tactic - Full Replacement (PUT/PATCH) 

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

runOfSite tactic - Delta Updates (PATCH Only)

NA

geoTargets tactic - Full Replacement (PUT/PATCH), using ID

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

geoTargets tactic - Delta Updates (PATCH Only), using ID

{ "geoTargets": "include": {"add": [{ "id": ... },{ "id": ... }], "remove": [{ "id": ... },{ "id": ... }] }
}

geoTargets tactic - Full Replacement (PUT/PATCH), using zipCode:

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

geoTargets tactic - Delta Updates (PATCH Only), using zipCode:

{ "geoTargets": "include": {"add": [{ "zipCode": ... },{ "zipCode": ... }], "remove": [{ "zipCode": ... },{ "zipCode": ... }] }
}

Updated about 13 hours ago