PIpinterest
ad_groups

Create ad groups

Changed on

Create multiple new ad groups. All ads in a given ad group will have the same budget, bid, run dates, targeting, and placement (search, browse, other).

For more information, click here.

Notes:

  • bid_in_micro_currency and budget_in_micro_currency should be expressed in microcurrency amounts based on the currency field set in the advertiser's profile.

Microcurrency is used to track very small transactions, based on the currency set in the advertiser's profile. A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser's profile.

Equivalency equations, using dollars as an example currency:

  • $1 = 1,000,000 microdollars
  • 1 microdollar = $0.000001

To convert between currency and microcurrency, using dollars as an example currency:

  • To convert dollars to microdollars, multiply dollars by 1,000,000

  • To convert microdollars to dollars, divide microdollars by 1,000,000

  • Ad groups belong to ad campaigns. Some types of campaigns (e.g. budget optimization) have limits on the number of ad groups they can hold. If you exceed those limits, you will get an error message.

  • Certain organizations with closed beta access can set start_time and end_time at the ad group level for campaigns with Campaign Budget Optimization (CBO) objectives: TRAFFIC, AWARENESS, WEB_CONVERSIONS, and CATALOG_SALES. All other organizations can set these scheduling parameters for non-CBO campaigns only.

  • If the parent ad campaign has start and end times set, ad group start and end times must occur within the parent campaign schedule.

post/ad_accounts/{ad_account_id}/ad_groups

Request

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Request body

auto_targeting_enabledboolean

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' required

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 required

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.

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 required

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
          ]
        }
      ]
    },
    "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

  • v5b698c180678aRevision changes
    • breaking

      added the new required request property /

    • breaking

      added the new required request property /

    • 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 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

  • v5537bde5a50b1Revision 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