account | DynamicAccount | Yes | - | Select Pinterest Ads account to create the ad group in. |
campaign_id | string or SelectItem | Yes | - | Pinterest campaign ID to create the ad group under. |
ad_group_name | string | Yes | - | Name of the Pinterest ad group. |
billable_event | string or SelectableOption | Yes | - | What the advertiser is billed for. CLICKTHROUGH for clicks, IMPRESSION for impressions (CPM), VIDEO_V_50_MRC for video views. |
status | string or SelectableOption | No | {'value': 'PAUSED', 'label': 'Paused'} | Status when the ad group is created. Options: ACTIVE, PAUSED, or DRAFT. Default: PAUSED. |
budget_type | string or SelectableOption | No | {'value': 'DAILY', 'label': 'Daily'} | Budget type. DAILY or LIFETIME require budget; LIFETIME also requires end_time. Use CBO_ADGROUP when the parent campaign uses Campaign Budget Optimization, which generates ad group budgets automatically; do not set budget with CBO_ADGROUP. Default: DAILY. |
budget | number | No | - | Ad group budget in the ad account’s currency (for example 20 for $20). Markifact converts it to Pinterest microcurrency automatically. Required for DAILY and LIFETIME budget types. |
bid | number | No | - | Bid price in the ad account’s currency, converted to microcurrency automatically. Pinterest requires it for these campaign objective and billable event combinations: AWARENESS with IMPRESSION, CONSIDERATION with CLICKTHROUGH, and CATALOG_SALES with CLICKTHROUGH. |
bid_strategy_type | string or SelectableOption | No | - | Bid strategy. AUTOMATIC_BID (Pinterest Performance+ bidding), MAX_BID, or TARGET_AVG. Video Completion campaigns only support AUTOMATIC_BID. |
performance_plus_value_strategy | enum (NEW_CUSTOMER_ACQUISITION, PRIORITY_PRODUCTS) | No | - | Optional value strategy for the base ad group of a Performance+ campaign: NEW_CUSTOMER_ACQUISITION or PRIORITY_PRODUCTS. Sent as the single entry in Pinterest’s performance_plus_value_strategies array. Pinterest automatically creates corresponding managed ad groups. Omit to leave strategies unset. For subsequent updates, use base_ad_group_id from List Ad Groups. |
start_time | integer or string | No | - | Optional ad group start as a Unix timestamp or ISO datetime string. Must fall within the parent campaign schedule when that is set. |
end_time | integer or string | No | - | Optional ad group end as a Unix timestamp or ISO datetime string. Required for LIFETIME budgets and lifetime_frequency_cap. |
auto_targeting_enabled | boolean | No | True | Pinterest Performance+ targeting: let Pinterest expand the audience automatically. Default true. |
targeting_spec | object or string | No | - | Pinterest targeting spec as a JSON object with uppercase keys, sent to Pinterest as-is. Use the pinterest_ads_search_targeting operation to find valid IDs for interests, locations, regions, languages, devices, and audiences. Omit for broad targeting; every key is optional: - GENDER: list from [“male”,“female”,“unknown”]. - MINIMUM_AGE / MAXIMUM_AGE: strings “18” to “65” (“65+” allowed for maximum only); must be used together. - LOCATION / LOCATION_EXCLUDE: ISO two-letter country codes and/or metro codes, e.g. [“US”,“501”]. - GEO / GEO_EXCLUDE: region codes like “US-CA” or postal codes like “94103” (one method per ad group). - LOCALE: ISO 639-1 language codes, e.g. [“en”]. - APPTYPE: devices from [“iphone”,“ipad”,“android_mobile”,“android_tablet”,“web”,“web_mobile”]. - INTEREST: Pinterest interest IDs. - AUDIENCE_INCLUDE / AUDIENCE_EXCLUDE: audience IDs from pinterest_ads_list_audiences (audiences need 100+ Pinterest users). - TARGETING_STRATEGY: list from [“CHOOSE_YOUR_OWN”,“FIND_NEW_CUSTOMERS”,“RECONNECT_WITH_USERS”]. Example: {“GENDER”: [“female”], “MINIMUM_AGE”: “25”, “MAXIMUM_AGE”: “54”, “LOCATION”: [“US”], “APPTYPE”: [“iphone”, “android_mobile”]} |
conversion_event | string or SelectableOption | No | - | Conversion event to optimize for. Required for conversion campaigns (SALES, LEADS, or legacy WEB_CONVERSION objectives), for example CHECKOUT, ADD_TO_CART, SIGNUP, or LEAD. Does not apply to CONSIDERATION ad groups: their Pin clicks vs outbound clicks optimization cannot be set through the Pinterest API at all, only in Ads Manager. |
reporting_event | string | No | - | Optional event to report on, sent as reporting_event inside optimization_goal_metadata.conversion_tag_v3_goal_metadata. For example, INITIATE_CHECKOUT with conversion_event ADD_TO_CART. Pinterest validates the event and its compatibility with the conversion goal. Omit to use Pinterest’s default reporting behavior. |
conversion_tag_id | string | No | - | Pinterest conversion tag ID to attribute the conversion event to. |
cpa_goal | number | No | - | Optional CPA goal for conversion campaigns in the ad account’s currency, converted to microcurrency automatically. |
placement_group | string or SelectableOption | No | - | Where ads appear: ALL (default), SEARCH, BROWSE, or OTHER. |
pacing_delivery_type | string or SelectableOption | No | - | Budget pacing. STANDARD (default) spends smoothly over the day; ACCELERATED spends as fast as possible and is not allowed with CBO_ADGROUP. |
lifetime_frequency_cap | integer | No | - | Maximum impressions per person over a rolling 30 days. Only for IMPRESSION billable event ad groups, and requires end_time. |
is_creative_optimization | boolean | No | False | Let Pinterest automatically turn product Pins into ads in different formats. Default false. |
