Overview

Partially update existing Onsite Display ad groups.

PATCH updates modify only the eligible fields included in the request payload. Unlike PUT requests, PATCH updates do not require resubmitting the entire ad group object.

PATCH is generally the preferred update method when only a subset of ad group attributes must change because it:

• Reduces payload size
• Minimizes the risk of unintended changes
• Simplifies operational updates
• Supports efficient batch updates

This endpoint supports both single-ad-group and batch update workflows.

Availability

Supported for Onsite Display only.

Why use PATCH?

PATCH is designed for incremental updates.

Use PATCH when you need to:

• Update bids
• Extend end dates
• Adjust budgets
• Update targeting IDs
• Modify geotargeting
• Update keyword lists
• Adjust frequency caps
• Update creative rotation settings

PATCH updates only the fields you include in the request.

How PATCH updates work

PATCH updates allow you to modify specific ad group attributes without replacing the full ad group configuration.

PATCH update workflow

Before you begin

• Valid advertiserId
• Valid adGroupId
• Ad group in an eligible lifecycle state
• Understanding of which fields are independent versus dependent
• Confirmation that the update does not violate targeting or configuration rules

Endpoint

PATCH /api/v1/adGroups

View technical specifications

Request details

PATCH behavior

Batch update behavior

This endpoint supports batch operations.

Batch requests:

• Are not transactional
• May partially succeed
• Return one response object per ad group
• Require a consistent advertiserId
• Max batch size=10

See the Batch Requests Guide for retry strategies and partial success handling.

Sample requests

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 } ] } ] } } ]'

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}]       } ] }
} ]'

Response details

What this response returns

The response confirms whether each ad group update succeeded or failed. Batch requests return one response object per ad group.

Key fields to use

• adGroupId
  Unique ad group identifier associated with the update result.

• code
  Overall operation result (success, failure)

• details
  Validation messages, processing feedback, or failure details

How to interpret results

Successful updates

A successful response confirms the specified fields were updated successfully.

Batch operations

Batch requests may contain both successful and failed updates. Always validate results at the individual ad group level.

Sample responses

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

[ { "code": "failure", "details": ["string"], "adGroupId": 11,    "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ]
     } { "code": "failure", "details": ["string"], "adGroupId": 12,    "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ]
     } ]

Common issues

• Attempting to change targeting tactics after scheduling
• Updating immutable fields
• Updating budget at the wrong configuration level
• Forgetting to extend endDate before editing completed ad groups
• Using targeting IDs where isDisabled=true
• Sending conflicting targeting structures
• Attempting unsupported negative keyword match types

What happens next

After updating ad groups:

1. Store updated ad group metadata
2. Re-sync partner interfaces if needed
3. Review failed update results
4. Continue creative association workflows
5. Revalidate targeting configuration where applicable

Related pages

• Update Ad Groups Overview
• Overwrite Ad Groups (PUT)
• Update Ad Group Status
• Targeting Object Guide
• Ad Group Creative Associations
• Campaign vs Ad Group Configuration Rules
• Batch Requests
• Lifecycle States & Statuses