ad_accounts14

ad_groups13

ads10

advanced_auction2

audience_insights2

audience_sharing7

audiences4

billing11

boards11

bulk3

business_access_assets12

business_access_invite6

business_access_relationships9

campaigns8

catalog_feeds8

catalog_items3

catalog_product_groups10

catalog_reports3

catalog_supplemental7

catalogs3

conversion_deletion_requests4

conversion_eqs1

conversion_events1

conversion_tags5

conversions4

customer_list_uploads3

customer_lists4

customer_segment3

integrations7

keywords5

labels5

lead_ads4

lead_forms5

leads_export2

media3

msot_events1

notification1

oauth3

order_lines2

pins8

product_group_promotions5

product_tags3

promotions5

resources6

schedules3

search3

targeting_template3

terms2

terms_of_service1

trends4

user_account14

ad_groups

Update ad groups

Changed on Jun 4, 2026

Update multiple existing ad groups.

patch/ad_accounts/{ad_account_id}/ad_groups

Request

Base URL
https://api.pinterest.com/v5
Auth
OAuth 2
Authorization codehttps://www.pinterest.com/oauth/
Token URLhttps://api.pinterest.com/v5/oauth/token
Scopesads:write
TypeScript
https://skmtc.dev/pinterest/apis/pinterest-rest-api/docs/ad_accounts/:ad_account_id/ad_groups/patch.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Request body

auto_targeting_enabledboolean nullable

Enable auto-targeting for ad group. Default value is True. Also known as "Performance+ targeting".

bid_in_micro_currencyinteger nullable

Bid price in micro currency. This field is REQUIRED for the following campaign objective_type/billable_event combinations: AWARENESS/IMPRESSION, CONSIDERATION/CLICKTHROUGH, CATALOG_SALES/CLICKTHROUGH, VIDEO_VIEW/VIDEO_V_50_MRC.

bid_multipliernumber

Open beta Bid multiplier for ad group. This value is a double between 0.1 and 10.0. Enter 0 to remove the bid multiplier. - Not currently supported for Performance+ campaigns.

bid_strategy_type'AUTOMATIC_BID' | 'MAX_BID' | 'TARGET_AVG' | 'null' nullable

Bid strategy type. For Campaigns with Video Completion objectives, the only supported bid strategy type is AUTOMATIC_BID, also known as "Pinterest Performance+ bidding".

billable_event'CLICKTHROUGH' | 'IMPRESSION' | 'VIDEO_V_50_MRC'

Ad group billable event type. For update, only draft ad groups may update billable event.

budget_in_micro_currencyinteger nullable

Budget in micro currency. This field is REQUIRED for non-CBO (campaign budget optimization) campaigns. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. A CBO campaign is limited to 70 or less ad groups.

budget_type'DAILY' | 'LIFETIME' | 'CBO_ADGROUP'

Budget type. If DAILY, an ad group's daily spend will not exceed the budget parameter value. If LIFETIME, the end_time parameter is REQUIRED, and the ad group spend is spread evenly between the ad group start_time and end_time range. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. For CBO campaigns, only "CBO_ADGROUP" is allowed. For WEB_SESSIONS campaigns, only "LIFETIME" is allowed. For update, only draft ad groups may update budget type.

campaign_idstring

Campaign ID of the ad group.

customer_segment_idstring

end_timeinteger nullable

Timestamp in Unix format for scheduling when ads in the ad group stop appearing. If not specified, ads run indefinitely unless you update the ad group by changing their status to paused. Cannot occur after end_time for parent campaign (if specified). Learn about scheduling ads. For certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO.

feed_profile_idstring

Feed Profile ID associated to the adgroup.

idstring required

Ad group ID.

is_creative_optimizationboolean nullable

Enable creative optimization for the ad group, default value is FALSE. When enabled, you allow Pinterest to automatically turn your product Pins into ads in different formats (collections and shopping) and deliver those ads to users at scale.

is_local_inventoryboolean

Indicates whether the ad group should use the local inventory.

lifetime_frequency_capinteger

Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. A CPM ad group has an IMPRESSION billable_event value. This field REQUIRES the end_time field.

local_inventory_radius_in_milesnumber

The targeting radius of the local inventory ads in miles.

namestring

Ad group name.

pacing_delivery_type'STANDARD' | 'ACCELERATED'

Ad group pacing delivery type. With ACCELERATED, an ad group budget is spent as fast as possible. With STANDARD, an ad group budget is spent smoothly over a day. When using CBO, only the STANDARD pacing delivery type is allowed.

placement_group'ALL' | 'SEARCH' | 'BROWSE' | 'OTHER'

Campaign placement group type

placement_traffic_type'ALL' | 'TWO_COLUMN_FEED' | 'FULLSCREEN_FEED' | 'null' nullable

A targeting option that enables advertisers to choose whether to run ads in fullscreen feed, two column feed, or both.

promotion_application_level'NONE' | 'ITEM' | 'AD_GROUP' | 'null' nullable

Specify if the promotion is applied at ad group or item level.

promotion_idstring nullable

Promotion ID. To clear this field, set to null.

promotion_idsstring[]

Promotion IDs list. To clear this field, set to an empty array [].

start_timeinteger nullable

Timestamp in Unix format for scheduling when ads in the ad group start to appear. If not specified, ads appear during parent campaign's start_time. Cannot precede start_time for parent campaign (if specified). Learn about scheduling ads. For certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO.

status'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT'

Entity status

targeting_template_idsPinterestLibIntegerFormatType[] nullable

Targeting template IDs applied to the ad group. We currently only support 1 targeting template per ad group. To use targeting templates, do not set any other targeting fields: targeting_spec, tracking_urls, auto_targeting_enabled, placement_group. To clear all targeting template IDs, set this field to ['0'].

Example request

[
  {
    "billable_event": "CLICKTHROUGH",
    "budget_type": "DAILY",
    "pacing_delivery_type": "STANDARD",
    "placement_group": "ALL",
    "status": "ACTIVE",
    "targeting_spec": {
      "SHOPPING_RETARGETING": [
        {
          "lookback_window": 30,
          "exclusion_window": 14,
          "tag_types": [
            0,
            6
          ]
        }
      ]
    },
    "targeting_spec_operations": [
      {
        "values": [
          {
            "lookback_window": 30,
            "exclusion_window": 14,
            "tag_types": [
              0,
              6
            ]
          }
        ]
      }
    ],
    "tracking_urls": {
      "impression": [
        "URL1",
        "URL2"
      ],
      "click": [
        "URL1",
        "URL2"
      ],
      "engagement": [
        "URL1",
        "URL2"
      ],
      "buyable_button": [
        "URL1",
        "URL2"
      ],
      "audience_verification": [
        "URL1",
        "URL2"
      ]
    }
  }
]

Response

The request has succeeded.

Example response

{
  "items": [
    {
      "data": {
        "billable_event": "CLICKTHROUGH",
        "placement_group": "ALL",
        "status": "ACTIVE",
        "targeting_spec": {
          "SHOPPING_RETARGETING": [
            {
              "lookback_window": 30,
              "exclusion_window": 14,
              "tag_types": [
                0,
                6
              ]
            }
          ]
        },
        "tracking_urls": {
          "impression": [
            "URL1",
            "URL2"
          ],
          "click": [
            "URL1",
            "URL2"
          ],
          "engagement": [
            "URL1",
            "URL2"
          ],
          "buyable_button": [
            "URL1",
            "URL2"
          ],
          "audience_verification": [
            "URL1",
            "URL2"
          ]
        }
      },
      "exceptions": [
        {
          "code": 2,
          "message": "Advertiser not found."
        }
      ]
    }
  ]
}

Changes

Jun 4, 2026v5b698c180678a Revision changes
- breaking
  added the new required request property /
- warning
  removed subschema #2 from the request property allOf list
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added to the // response property allOf list for the response status
- info
  removed subschema #2 from the // response property allOf list for the response status
- info
  the response property became required for the status
- info
  the response property //// became required for the status
Dec 11, 2025v5537bde5a50b1 Revision changes
- breaking
  the ///////// response property's minItems was decreased from 100 to 0 for the response status
- breaking
  the ///////// response property's minItems was decreased from 100 to 0 for the response status

Operation history (14 revisions)