Update ad group delivery status
Learn to pause, resume, archive, and unarchive Onsite Display ad groups.
Overview
Use this endpoint to pause, resume, archive, or unarchive an ad group.
Unlike Ad Group Update APIs, this endpoint changes an ad group's delivery state rather than its configuration.
Use Ad Group Status APIs when you need to:
- Pause active delivery
- Resume paused delivery
- Archive unused ad groups
- Restore archived ad groups
- Manage delivery state programmatically
Availability
Supported for Onsite Display only.
Ad group status updates vs ad group updates
Ad group lifecycle actions and ad group configuration updates are separate workflows.
Status Updates
- Pause delivery
- Resume delivery
- Archive ad groups
- Unarchive ad groups
- Change lifecycle state
Configuration Updates
- Update targeting
- Update bids
- Update budgets
- Update schedules
- Update frequency caps
How ad group lifecycle works
Ad group lifecycle actions are governed by the current ad group status.
Not every action is valid for every state.
Draft
Configuration in progress. Platform-driven.
Scheduled
Waiting for future start date. Platform-driven.
Live
Eligible to deliver. Platform-driven.
Paused
Delivery temporarily stopped.
Completed
Flight dates ended. Platform-driven.
Archived
Removed from active workflows.
This endpoint:
- Updates delivery state synchronously
- Supports single and batch requests
- Processes each ad group independently
- Does not modify ad group configuration
Before you begin
- Valid
advertiserId - Valid
adGroupId - Ad group in an eligible lifecycle state
- Understanding of which action is supported for the current state
Endpoint
PUT /api/v1/adGroups/action
PUT /api/v1/adGroups/actionRequest details
How this request is used
Use this endpoint to:
- Pause active delivery
- Resume paused delivery
- Archive unused draft ad groups
- Restore archived ad groups
- Execute batch lifecycle updates
- Manage delivery state programmatically
Key fields and behaviors
-
adGroupId
Unique ad group identifier. -
action
Lifecycle action:pauseresumearchiveunarchive
Supported actions by ad group status
| Action | Draft | Scheduled | Live | Paused | Completed | Archived |
|---|---|---|---|---|---|---|
| Pause | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
| Resume | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| Archive | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Unarchive | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
- ✅ = action supported
- ❌ = action not supported
Archiving campaigns and ad groupsCampaigns and all associated ad groups must be in Draft status to be archived. Scheduled or live campaigns and ad groups cannot be archived.
Lifecycle action behavior
Temporarily stops delivery for scheduled or live ad groups.
Use when:
- pausing spend
- stopping delivery temporarily
- controlling pacing manually
Resumes delivery for paused ad groups.
Use when:
- restarting delivery
- resuming campaign pacing
- reactivating paused spend
Moves draft ad groups into an archived state.
Archived ad groups:
- do not deliver
- are hidden from active workflows
- retain historical configuration
Restores archived ad groups back into editable draft state.
Use when:
- reusing archived setup
- restoring historical configurations
- restarting paused planning workflows
Delivery impact
Status updates affect delivery immediately.
Delivery dependencyResuming an ad group does not guarantee delivery.
Delivery still depends on:
- Campaign status
- Approved creatives
- Targeting eligibility
- Inventory availability
Batch update behavior
This endpoint supports batch operations.
Each ad group action is processed independently.
Batch requests:
- Are not transactional
- May partially succeed
- Return per-object success or failure results
- Max batch size=10 and one
advertiserIdper request
See the Batch Requests Guide for retry guidance and partial-success handling.
Sample requests
Pause ad group
curl -X PUT \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups/action' \ --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": 1, "action": "pause" }
] 'Batch operation
curl -X PUT \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups/action' \ --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": 1, "action": "pause" }, { "advertiserId": 1, "adGroupId": 2, "action": "resume" }, { "advertiserId": 1, "adGroupId": 3, "action": "archive" }, { "advertiserId": 1, "adGroupId": 4, "action": "unarchive" } ]' Response details
What this response returns
The response confirms whether each lifecycle action succeeded or failed.
Key fields to use
-
adGroupId
Ad group associated with the lifecycle action. -
code
Operation result (success,failure) -
details
Validation messages or lifecycle transition errors. -
message
Optional. High-level, human-readable summary of the error when available. -
errors
Detailed information about one or more errors. This is an array object with fields:field,errorType,description
Error Handling
If the request or an individual item fails, the response includes error information to help identify the issue and determine the corrective action. Use errorType for the error condition, field for the affected request field when applicable, and description for an explanation of the error and, when available, guidance on how to resolve it.
For the complete error response schema and endpoint-specific response definitions, see the API Reference. For guidance on HTTP status codes and how clients should handle them, see API status codes and error handling.
How to interpret results
Successful actions
A successful response confirms the lifecycle transition completed successfully.
Failed actions
A failed response indicates the requested lifecycle transition was not allowed.
Batch operations
Batch requests may contain both successful and failed actions.
Always validate responses at the individual ad group level.
Sample responses
Single ad group
[ { "code": "success", "details": ["string"], "adGroupId": 1 }
]Multiple ad groups
[ { "code": "success", "details": ["string"], "adGroupId": 1 }, { "code": "success", "details": ["string"], "adGroupId": 2 },
{ "code": "success", "details": ["string"], "adGroupId": 3 },
{ "code": "success", "details": ["string"], "adGroupId": 4 } ]Sample response - failure
[ { "code": "failure", "adGroupId": 1, "details": [ "string" ], "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ] }
]Common issues
- Attempting unsupported lifecycle transitions
- Trying to archive scheduled or live ad groups
- Attempting to resume non-paused ad groups
- Using invalid ad group IDs
- Mixing advertiser IDs in batch requests
- Assuming resumed ad groups automatically begin serving
What happens next
After a successful status update:
- Re-sync lifecycle state in partner tools
- Validate delivery behavior
- Confirm campaign and creative eligibility
- Monitor pacing after resume actions
- Continue downstream campaign workflows
Related pages
Updated 15 days ago
