update_payload | object or string | Yes | - | Ad group fields to update as a JSON object, sent to Pinterest as-is in a PATCH request; only the fields you include are changed. Common fields: name, status (ACTIVE/PAUSED/ARCHIVED), start_time and end_time (Unix seconds), targeting_spec (uppercase keys; use pinterest_ads_search_targeting for IDs), bid_strategy_type, placement_group, pacing_delivery_type, auto_targeting_enabled, optimization_goal_metadata, lifetime_frequency_cap, tracking_urls. Money fields are raw Pinterest microcurrency integers: budget_in_micro_currency and bid_in_micro_currency (multiply the currency amount by 1,000,000, so $20 is 20000000). Draft ad groups only: billable_event, budget_type. Prefer pinterest_ads_update_ad_group_status and pinterest_ads_rename_ad_group for plain status or name changes. For a Performance+ campaign’s base ad group, set one value strategy with {“performance_plus_value_strategies”: [“NEW_CUSTOMER_ACQUISITION”]} or {“performance_plus_value_strategies”: [“PRIORITY_PRODUCTS”]}. Pinterest automatically creates corresponding managed ad groups; apply updates to the base_ad_group_id, not a managed sibling. optimization_goal_metadata is only writable for conversion objectives (SALES, LEADS, legacy WEB_CONVERSION), using conversion_tag_v3_goal_metadata with conversion_event, reporting_event, conversion_tag_id, cpa_goal_value_in_micro_currency, or attribution_windows. The CONSIDERATION ‘Optimization’ selector in Ads Manager (Pin clicks vs outbound clicks / landing page) CANNOT be changed through the Pinterest API. It is a campaign-wide setting that Ads Manager applies to every ad group in the campaign; the API only reads it back on the ad group as outbound_click_goal_metadata.is_outbound_click_optimized, rejects every attempt to write it there with ‘Invalid parameters’ (create and update), and exposes nothing for it on the campaign, where the same keys are silently dropped with a 200 and nothing changes. Tell the user to change it in Ads Manager; do not retry via pinterest_ads_update_campaign, a success there proves nothing. Writing conversion_tag_v3_goal_metadata into a CONSIDERATION ad group is accepted and echoed back by pinterest_ads_list_ad_groups but does not change that selector, so reading the value back is not proof the setting took effect. Once set, optimization_goal_metadata cannot be cleared: {} is a no-op and null fails with a server error. There is no optimization_type field on an ad group; it exists only on Pinterest’s delivery-estimates endpoint, and Pinterest silently drops it (and any other unknown key) from an update instead of returning an error. Example: {“budget_in_micro_currency”: 20000000, “targeting_spec”: {“LOCATION”: [“US”, “CA”]}} |
