<!--
{
  "availability" : [
    "Search Ads: 5.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Apple_Ads",
  "identifier" : "/documentation/apple_ads/Update-an-Ad-Group",
  "metadataVersion" : "0.1.0",
  "role" : "Web Service Endpoint",
  "symbol" : {
    "kind" : "Web Service Endpoint",
    "modules" : [
      "Apple Ads"
    ],
    "preciseIdentifier" : "rest:apple_ads:put:v5-campaigns-{}-adgroups-{}"
  },
  "title" : "Update an Ad Group"
}
-->

# Update an Ad Group

Updates an ad group with an ad group identifier.

## Discussion

To update ad groups, use the associated `campaignId` and `adgroupId` in the resource path.

In the request, specify [`TargetingDimensions`](/documentation/apple_ads/TargetingDimensions) and apply it to ad groups. If you’re not updating [`TargetingDimensions`](/documentation/apple_ads/TargetingDimensions), don’t include them in the payload. Use partial updates as necessary. For more information, see the Use Partial Updates section of [Using Apple Ads API Functionality](/documentation/Apple_Ads/using-apple-search-ads-api-functionality).

> Note:
> You can’t create or update ad groups with geotargeting for campaigns with multiple countries or regions. Use ``doc://com.apple.appleads/documentation/apple_ads/UpdateCampaignRequest`` to clear your geotargeting parameters. Then apply ``doc://com.apple.appleads/documentation/apple_ads/TargetingDimensions`` in the request payload.

### Payload example: Update an ad group with targeting

**Request:**

```http
PUT https://api.searchads.apple.com/api/v5/campaigns/{campaignId}/adgroups

{
  "targetingDimensions": {
    "age": {
      "included": [
        {
          "minAge": 20,
          "maxAge": 25
        }
      ]
    },
    "gender": {
      "included": [
        "F",
        "M"
      ]
    },
    "country": {
      "included": [
        "US"
      ]
    },
    "adminArea": {
      "included": [
        "US|CA"
      ]
    },
    "locality": {
      "included": [
        "US|CA|Cupertino"
      ]
    },
    "deviceClass": {
      "included": [
        "IPAD",
        "IPHONE"
      ]
    },
    "daypart": {
      "userTime": {
        "included": [
          1,
          3,
          22
        ]
      }
    }
  }
}
```

**Response:**

```json
{
  "id": 542370539,
  "campaignId": 542370539,
  "name": "ad group with targeting",
  "cpaGoal": {
    "amount": "100",
    "currency": "USD"
  },
  "startTime": "2025-04-08T16:20:31.650",
  "endTime": "2025-04-09T19:33:31.650",
  "automatedKeywordsOptIn": false,
  "defaultBidAmount": {
    "amount": "100",
    "currency": "USD"
  },
  "pricingModel": "CPC",
  "targetingDimensions": {
    "age": {
      "included": [
        {
          "minAge": 20,
          "maxAge": 25
        }
      ]
    },
    "gender": {
      "included": [
        "M",
        "F"
      ]
    },
    "country": {
      "included": [
        "US"
      ]
    },
    "adminArea": {
      "included": [
        "US|CA"
      ]
    },
    "locality": {
      "included": [
        "US|CA|Cupertino"
      ]
    },
    "deviceClass": {
      "included": [
        "IPAD",
        "IPHONE"
      ]
    },
    "daypart": {
      "userTime": {
        "included": [
          1,
          3,
          22
        ]
      }
    },
    "appDownloaders": null
  },
  "orgId": 40669820,
  "modificationTime": "2025-04-08T17:15:56.956",
  "status": "ENABLED",
  "servingStatus": "NOT_RUNNING",
  "servingStateReasons": [
    "START_DATE_IN_THE_FUTURE"
  ],
  "displayStatus": "ON_HOLD",
  "deleted": `false`
}
```

### Payload example: Update an ad group without targeting

**Request:**

```http
PUT https://api.searchads.apple.com/api/v5/campaigns/{campaignId}/adgroups/{adgroupId}

{
  "name": "ad group without targeting",
  "startTime": "2025-05-08T17:00:00.000"
}
```

**Response:**

```json
{
    "data": {
        "id": 585885654,
        "campaignId": 585885088,
        "name": "ad group without targeting",
        "cpaGoal": null,
        "startTime": “2025-05-08T17:00:00.000”,
        "endTime": null,
        "automatedKeywordsOptIn": false,
        "targetingDimensions": {
            "age": null,
            "gender": null,
            "country": null,
            "adminArea": null,
            "locality": null,
            "deviceClass": {
                "included": [
                    "IPHONE",
                    "IPAD"
                ]
            },
            "daypart": null,
            "appDownloaders": null
        },
        "orgId": 39879640,
        "creationTime": "2025-05-04T20:49:47.286",
        "pricingModel": "CPC",
        "modificationTime": "2025-05-04T20:49:47.286",
        "status": "ENABLED",
        "servingStatus": "NOT_RUNNING",
        "servingStateReasons": [
            "START_DATE_IN_THE_FUTURE"
        ],
        "displayStatus": "ON_HOLD",
        "deleted": false,
        "defaultBidAmount": {
            "amount": "1",
            "currency": "USD"
        }
    },
    "pagination": null,
    "error": null
}
```

### Payload example: Update an ad group CPA goal

**Request:**

```http
PUT https://api.searchads.apple.com/api/v5/campaigns/{campaignId}/adgroups/{adgroupId}

{
  "campaignId": 585885088,
  "name": "update CPA goal",
  "cpaGoal": {
    "amount": "5.00",
    "currency": "USD"
  },
  "startTime": "2025-05-08T10:00:00.000",
  "endTime": "2025-05-09T10:00:00.000",
  "automatedKeywordsOptIn": false,
  "pricingModel": "CPC",
  "defaultBidAmount": {
    "amount": "1",
    "currency": "USD"
  },
  "orgId": 39879640,
  "status": "ENABLED"
}
```

**Response:**

```json
{
  "data": {
    "id": 585887393,
    "campaignId": 585886890,
    "name": "update CPA goal",
    "cpaGoal": {
      "amount": "5.00",
      "currency": "USD"
    },
    "startTime": "2025-05-08T10:00:00.000",
    "endTime": "2025-05-09T10:00:00.000",
    "automatedKeywordsOptIn": false,
    "targetingDimensions": {
      "age": null,
      "gender": null,
      "country": null,
      "adminArea": null,
      "locality": null,
      "deviceClass": {
        "included": [
          "IPHONE",
          "IPAD"
        ]
      },
      "daypart": null,
      "appDownloaders": null
    },
    "orgId": 39879640,
    "creationTime": "2025-05-04T23:33:33.211",
    "pricingModel": "CPC",
    "modificationTime": "2025-05-04T23:33:33.211",
    "status": "ENABLED",
    "servingStatus": "NOT_RUNNING",
    "servingStateReasons": [
      "START_DATE_IN_THE_FUTURE"
    ],
    "displayStatus": "ON_HOLD",
    "deleted": false,
    "defaultBidAmount": {
      "amount": "1",
      "currency": "USD"
    },
    "biddingStrategy": "MANUAL_CPT",
    "automatedKeywordsRequired": false
  },
  "pagination": null,
  "error": null
}
```

### Payload example: Update an ad group Search March setting

Only the name field can be updated in automated ad groups.

- `defaultBidAmount` cannot be changed to a non-zero/non-null value.
- `cpaGoal` cannot be set to a non-null value.
- `biddingStrategy` is read-only.
- `automatedKeywordsOptIn` can be toggled true/false.
- `automatedKeywordsRequired` is read-only.

**Request:**

```http
PUT https://api.searchads.apple.com/api/v5/campaigns/{campaignId}/adgroups/{adgroupId}

{
    "automatedKeywordsOptIn": false
}
```

**Response:**

```json
{
  "data": {
    "id": 585887393,
    "campaignId": 585886890,
    "name": "update search match",
    "cpaGoal": {
      "amount": "5.00",
      "currency": "USD"
    },
    "startTime": "2025-05-08T10:00:00.000",
    "endTime": "2025-05-09T10:00:00.000",
    "automatedKeywordsOptIn": false,
    "automatedKeywordsRequired": false,
    "orgId": 39879640,
    "creationTime": "2025-05-04T23:33:33.211",
    "pricingModel": "CPC",
    "modificationTime": "2026-05-04T23:33:33.211",
    "status": "ENABLED",
    "servingStatus": "NOT_RUNNING",
    "servingStateReasons": [
      "START_DATE_IN_THE_FUTURE"
    ],
    "displayStatus": "ON_HOLD",
    "deleted": false,
    "defaultBidAmount": {
      "amount": "0",
      "currency": "USD"
    },
    "biddingStrategy": "MAX_CONVERSIONS",
    "automatedKeywordsRequired": true
  },
  "pagination": null,
  "error": null
}
```

### Payload example: Update an ad group default bid amount

Only the name field can be updated in automated ad groups.

- `defaultBidAmount` cannot be changed to a non-zero/non-null value.
- `cpaGoal` cannot be set to a non-null value.
- `automatedKeywordsOptIn` can be toggled true/false.
- `biddingStrategy` is read-only.
- `automatedKeywordsRequired` is read-only.

**Request:**

```http
PUT https://api.searchads.apple.com/api/v5/campaigns/{campaignId}/adgroups/{adgroupId}

{
  "defaultBidAmount": {
    "amount": "5.00",
    "currency": "USD"
  }
}
```

**Response:**

```json
{
  "data": {
    "id": 585887393,
    "campaignId": 585886890,
    "name": "update Default Bid Amount",
    "cpaGoal": {
      "amount": "null",
      "currency": "USD"
    },
    "startTime": "2025-05-08T10:00:00.000",
    "endTime": "2025-05-09T10:00:00.000",
    "automatedKeywordsOptIn": false,
    "orgId": 39879640,
    "creationTime": "2026-05-04T23:33:33.211",
    "pricingModel": "CPC",
    "modificationTime": "2026-05-04T23:33:33.211",
    "status": "ENABLED",
    "servingStatus": "NOT_RUNNING",
    "servingStateReasons": [
      "START_DATE_IN_THE_FUTURE"
    ],
    "displayStatus": "ON_HOLD",
    "deleted": false,
    "defaultBidAmount": {
      "amount": "5.00",
      "currency": "USD"
    }
    "biddingStrategy": "MANUAL_CPT",
    "automatedKeywordsRequired": `false`
  },
  "pagination": null,
  "error": null
}
```

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)