Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Start using campaign objective type simplification

We are rolling out an update to simplify campaign objective types, making it easier to leverage product catalogs along with standard creative across a wider range of conversion goals.
You should have received an email from the Pinterest team about this change, which involves migration to improved campaign objective logic and will require you to take actions.

What has changed as of now?

These changes, previously only available in Sandbox, are now available in production.
These changes, previously only available in Sandbox, are now available in production.
We are deprecating
WEB_CONVERSION
and
CATALOG_SALES
objectives, and introducing two objectives to take on their functionality:
  • The
    SALES
    objective optimizes toward transactional conversion events, such as
    add_to_cart
    and
    checkout
    .
  • The
    LEADS
    objective optimizes toward non-transactional conversion events, such as
    signup
    and
    lead
    .
To signal your use of this objective type simplification, we are introducing an optional
intended_promotion_type
parameter, which allows you to create ads derived from either Pins or Product Group Promotions under the
SALES
and
CONSIDERATION
objectives.
For these campaigns, you can create catalog-based promotions under the ad group level by referencing the ad group ID and the relevant catalog/product group identifiers.
The
WEB_CONVERSION
and
CATALOG_SALES
objectives remain available for legacy campaigns, supporting both transactional and non-transactional outcomes until February 1, 2027. See the timeline of milestones.

Use objective simplification in campaigns

Endpoints

POST
Create campaigns
PATCH
Update campaigns

Parameters relevant to objective simplification changes

Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.
Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.
Objective type simplification parameters
ParameterDescriptionValid inputs
objective_type

non-nullable string
Required
Intended result of the campaign.
You can only update objectives for draft campaigns.
AWARENESS

CONSIDERATION

VIDEO_COMPLETION

SALES

LEADS

CATALOG_SALES
(Deprecated)
WEB_CONVERSION
(Deprecated)
WEB_SESSIONS
(Deprecated)
VIDEO_VIEW
(Deprecated; use
VIDEO_COMPLETION
as an alternative.)
intended_promotion_type

non-nullable string
Optional but necessary for this use case
Signals your use of the objective type simplification and create ads derived from either Pins or product groups under the
SALES
and
CONSIDERATION
objectives.
You can only update this parameter for draft campaigns.
If you do not pass this parameter, the default is:
  • LEGACY
    for
    CATALOG_SALES
    and
    WEB_CONVERSION
  • STANDARD_AD
    for other objective types
Some default values will change at on February 1, 2027 (See following table).
STANDARD_AD
  • For ads derived from Pins.
  • Supported for all objective types except for current
    CATALOG_SALES
    , which is being deprecated.
CATALOG
  • For creating product group promotions.
  • Supported for
    CONSIDERATION
    and
    SALES
    objective types.
LEGACY
  • Intended only for maintaining backward compatibility with these objective types:
  • Must be used for
    CATALOG_SALES
    .
  • Supported for
    WEB_CONVERSION
    objective type.

Allowed and default values for intended_promotion_type

Changing defaults
Objective
intended_promotion_type

allowed value(s)
intended_promotion_type

current default
intended_promotion_type

default after February 1, 2027
AWARENESS
STANDARD_AD
STANDARD_AD
STANDARD_AD
CONSIDERATION
STANDARD_AD
CATALOG
STANDARD_AD
STANDARD_AD
WEB_CONVERSION
STANDARD_AD
LEGACY
LEGACY
Creation disabled
SALES
STANDARD_AD
CATALOG
STANDARD_AD
STANDARD_AD
LEADS
STANDARD_AD
CATALOG
STANDARD_AD
STANDARD_AD
CATALOG_SALES
LEGACY
LEGACY
Creation disabled
VIDEO_COMPLETION
STANDARD_AD
STANDARD_AD
STANDARD_AD
APP_INSTALL
STANDARD_AD
STANDARD_AD
STANDARD_AD

Example request

curl --request POST \
  --url https://api.pinterest.com/v5/ad_accounts/123456789012/campaigns \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '[
  {
    "name": "Example campaign",
    "daily_spend_cap": 500000000,
    "is_campaign_budget_optimization": true,
    "is_flexible_daily_budgets": true,
    "objective_type": "LEADS",
    "intended_promotion_type": "STANDARD_AD",
    "is_performance_plus": false,
    "is_top_of_search": false
  }
]'

Example response

{
  "items": [
    {
      "data": {
        "id": "626747269410",
        "ad_account_id": "123456789012",
        "name": "Example campaign",
        "objective_type": "LEADS",
        "lifetime_spend_cap": 0,
        "daily_spend_cap": 500000000,
        "order_line_id": null,
        "tracking_urls": null,
        "is_flexible_daily_budgets": true,
        "default_ad_group_budget_in_micro_currency": null,
        "is_automated_campaign": false,
        "created_time": 1778794803,
        "updated_time": 1778794803,
        "type": "campaign",
        "summary_status": "RUNNING",
        "is_campaign_budget_optimization": true,
        "start_time": 1778794803,
        "end_time": null,
        "is_performance_plus": false,
        "is_top_of_search": false,
        "bid_options": null,
        "ext_features": null,
        "status": "ACTIVE",
        "intended_promotion_type": "STANDARD_AD"
      },
      "exceptions": []
    }
  ]
}

Set conversion events for SALES and LEADS campaigns

Under objective simplification, conversion campaigns use the
SALES
or
LEADS
objective instead of
WEB_CONVERSION
or
CATALOG_SALES
. Set the conversion you want to optimize for at the ad group level, in
optimization_goal_metadata.conversion_tag_v3_goal_metadata
. The
conversion_event
must match the campaign objective:
  • CHECKOUT
    or
    ADD_TO_CART
    for
    SALES
  • SIGNUP
    or
    LEAD
    for
    LEADS

Endpoints

POST
Create ad groups
PATCH
Update ad groups

Pair conversion and reporting events

With objective simplification, the conversion event that Pinterest delivers and bids for is separate from the event that appears in reports. Bid and delivery optimization is supported for
CHECKOUT
,
ADD_TO_CART
,
SIGNUP
, or
LEAD
events, but Ads Manager and reporting endpoints also support more specific events such as
INITIATE_CHECKOUT
. In ad groups, set
conversion_event
to the event you want to optimize for and
reporting_event
to the event you want to report on. For example, a
SALES
campaign can report
INITIATE_CHECKOUT
rather than only
ADD_TO_CART
.
The
conversion_event
parameter also accepts the
APP_INSTALL
event, which does not map to a more specific
reporting_event
. See App install campaigns.
The
conversion_event
parameter also accepts the
APP_INSTALL
event, which does not map to a more specific
reporting_event
. See App install campaigns.
Use this table to pair events for conversion and reporting.
conversion_event and reporting_event mappings for SALES and LEADS
For this campaign objective type......pair this reporting event......with this conversion event
SALES
CHECKOUT
CHECKOUT
SALES
ADD_TO_CART
ADD_TO_CART
SALES
INITIATE_CHECKOUT
ADD_TO_CART
SALES
ADD_PAYMENT_INFO
ADD_TO_CART
SALES
ADD_TO_WISHLIST
ADD_TO_CART
SALES
CUSTOMIZE_PRODUCT
ADD_TO_CART
LEADS
SIGNUP
SIGNUP
LEADS
SUBSCRIBE
SIGNUP
LEADS
SUBMIT_APPLICATION
SIGNUP
LEADS
START_TRIAL
SIGNUP
LEADS
LEAD
LEAD
LEADS
SCHEDULE
LEAD
LEADS
CONTACT
LEAD
LEADS
FIND_LOCATION
LEAD

Example

To optimize for
initiate_checkout
, send:
{
  "optimization_goal_metadata": {
    "conversion_tag_v3_goal_metadata": {
      "conversion_tag_id": "2614324385652",
      "conversion_event": "ADD_TO_CART",
      "reporting_event": "INITIATE_CHECKOUT"
    }
  }
}
Include
conversion_tag_id
when
conversion_event
is
CHECKOUT
,
ADD_TO_CART
,
SIGNUP
, or
LEAD
. The parameter is optional, but omitting it for those four events returns a validation error. Pinterest cannot optimize toward those events without the ID. Get it from
GET
List conversion tags
.
Send
conversion_tag_id
even if you only use the Conversions API and not Pinterest Tag. The Conversions API still sends those events to the conversion tag on the ad account.

App install campaigns

For campaigns with the
APP_INSTALL
objective, set
conversion_event
to
APP_INSTALL
and omit
reporting_event
.
APP_INSTALL
does not map to a more specific reporting event. When you omit the parameter, the API stores it as unset and leaves it out of the response.

Timeline of objective simplification milestones:

Dates are subject to change as we work to ensure a smooth transition for our partners. We will post any updates.

Right now

We recommend that you start using objective simplification features:
  • Update
    CATALOG_SALES
    campaigns to
    SALES
    or
    CONSIDERATION
    objectives.
  • Update
    WEB_CONVERSION
    campaigns that optimize for
    checkout
    or
    add_to_cart
    events to the
    SALES
    objective.
  • Update
    WEB_CONVERSION
    campaigns that optimize for non-transactional conversion events, such as
    signup
    and
    lead
    , to the
    LEADS
    objective.
  • If you use Ads Manager to create campaigns for
    CATALOG_SALES
    , or
    WEB_CONVERSION
    campaigns optimized for
    add_to_cart
    or
    checkout
    , the new objectives logic is available in Ads Manager.
  • You can continue to use the
    CATALOG_SALES
    campaign and
    WEB_CONVERSION
    campaigns optimized for
    add_to_cart
    or
    checkout
    . And any campaigns created through the API and using the pre-simplified objective logic can still be edited in Ads Manager if required. However, we highly recommend for consistency that you start switching over to the new objective types.

As of February 1, 2027

  • You will no longer be able to create new
    CATALOG_SALES
    campaigns or
    WEB_CONVERSION
    campaigns optimized for
    add_to_cart
    or
    checkout
    through the API.
  • You will be able to update and continue running any campaigns that were created with these objectives before February 1, 2027.

As of April 30, 2027

We will archive campaigns with
CATALOG_SALES
and
WEB_CONVERSION
objectives.

Get help

If you have any questions or need help during the migration process, please reach out to your Sales or Business Development Partner, or submit a Support request:
  1. Go to Get more help in the Help Center.
  2. Under Pinterest API and Developer Tools, select API Technical Support and click Continue.
  3. On the next page, select Pinterest API v5 and click Continue.
  4. Provide requested information.
Was this page helpful?