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


Request 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:

    • pause
    • resume
    • archive
    • unarchive

Supported actions by ad group status

ActionDraftScheduledLivePausedCompletedArchived
Pause❌❌✅❌❌❌
Resume❌❌❌✅❌❌
Archive✅❌❌❌❌❌
Unarchive❌❌❌❌❌✅
  • ✅ = action supported
  • ❌ = action not supported
ℹ️

Archiving campaigns and ad groups

Campaigns 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

Pause

Temporarily stops delivery for scheduled or live ad groups.

Use when:

  • pausing spend
  • stopping delivery temporarily
  • controlling pacing manually
Resume

Resumes delivery for paused ad groups.

Use when:

  • restarting delivery
  • resuming campaign pacing
  • reactivating paused spend
Archive

Moves draft ad groups into an archived state.

Archived ad groups:

  • do not deliver
  • are hidden from active workflows
  • retain historical configuration
Unarchive

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.

Pause

  • Stops ad group delivery
  • Prevents new impressions from serving
  • Preserves all configuration

Resume

  • Restores delivery eligibility
  • Does not guarantee impressions immediately

Delivery dependency

Resuming 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 advertiserId per 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:

  1. Re-sync lifecycle state in partner tools
  2. Validate delivery behavior
  3. Confirm campaign and creative eligibility
  4. Monitor pacing after resume actions
  5. Continue downstream campaign workflows

Related pages


Did this page help you?