PIpinterest
campaigns

Update campaigns

Changed on

Update multiple ad campaigns based on campaign_ids.

Note:

  • The values for lifetime_spend_cap and daily_spend_cap are microcurrency amounts based on the currency field set in the advertiser's profile (e.g. USD).

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
patch/ad_accounts/{ad_account_id}/campaigns

Request

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Request body

ad_account_idstring

Setting this field does nothing. The ad account ID gets set from the path parameter.

app_idstring

Closed beta

The store ID of the mobile app for APP_INSTALL campaigns.

app_platform'IOS' | 'ANDROID'

Closed beta

Platform of the mobile app for an APP_INSTALL campaign.

daily_spend_capinteger nullable

Note: The default for this field is null, which is treated the same as 0. For campaign budget optimization, a daily or lifetime spend cap must be set, but not both. For ad group level budgets, this field must be 0 or unset.

default_ad_group_budget_in_micro_currencyinteger nullable

Setting this field does nothing.

end_timeinteger nullable

Note: To clear this field on update, set the end time to -1. Timestamp in Unix format for scheduling when ads in the campaign stop appearing. Must occur after any end times for child ad groups. If end_time is not specified for the campaign, ads run indefinitely unless you update the campaign, changing their status to paused. Learn about scheduling campaigns. Different end times can be set for the campaign's child ad groups, but they cannot occur after an end_time specified for the campaign.

  • If your campaign has a child ad group with an end time specified, and if you update that campaign with an end_time that is earlier than that of the ad group, the campaign end_time will supersede the ad group end_time, and the request will not return an error.
  • In this scenario, if you call List campaigns or List ad groups, the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence.
idstring required

Campaign ID, must be associated with the ad account ID provided in the path.

intended_promotion_type'LEGACY' | 'STANDARD_AD' | 'CATALOG'

Specifies the intended promotion type for the campaign.

Note: This field is immutable unless the campaign is in draft status.

STANDARD_AD

  • For ads derived from Pins.
  • Supported for all objective types except for current CATALOG_SALES and WEB_CONVERSION, which are being deprecated.
  • For simplified objective types.

CATALOG

  • For creating product group promotions.
  • Supported for CONSIDERATION and SALES objective types.
  • For simplified objective types.

LEGACY

  • Intended only for maintaining backward compatibility.
  • Must be used for CATALOG_SALES and WEB_CONVERSION.
  • Supported for CATALOG_SALES and WEB_CONVERSION objective types.

If you do not provide this parameter, the default is:

  • LEGACY for CATALOG_SALES and WEB_CONVERSION
  • STANDARD_AD for other objective types
is_automated_campaignboolean nullable

Note: This field is immutable unless the campaign is in draft status. Specifies whether the campaign was created in the automated campaign flow. When using Automated Campaigns, a daily spend cap must be set, and Pinterest Performance+ may not be used. The following objective types are supported:

  • CONSIDERATION
  • WEB_CONVERSION
  • SALES
  • LEADS
  • CATALOG_SALES
is_campaign_budget_optimizationboolean nullable

Note: This field is immutable unless the campaign is in draft status. Determines if a campaign automatically generates ad-group level budgets given a campaign budget to maximize campaign outcome. When using campaign budgets with a lifetime spend cap, the end time must be provided.

is_flexible_daily_budgetsboolean nullable

Determine if a campaign has setup for flexible daily budgets, also known as "Pinterest Performance+ budgets". Flexible daily budgets are only supported for campaign budget optimization with a daily spend cap, and not a lifetime spend cap.

is_ltv_optimizedboolean

Specifies whether the campaign is optimized for Lifetime Value (LTV). Only available for eligible advertisers.

is_performance_plusboolean

Note: This field is immutable unless the campaign is in draft status. You can only use this feature with the following objectives:

  • CONSIDERATION
  • WEB_CONVERSION
  • SALES
  • LEADS
  • CATALOG_SALES
  • APP_INSTALL Enable Pinterest Performance+ for your campaign. To learn more, see Pinterest Performance+ Setup
is_top_of_searchboolean

Note: This field is immutable unless the campaign is in draft status. Restricted Have your ads and content appear at the top of search result lists in Pinterest. You can only use this feature with the following objectives:

  • CONSIDERATION
  • WEB_CONVERSION
  • SALES
  • LEADS
  • CATALOG_SALES You cannot use this feature with Pinterest Performance+ or Premiere Spotlight enabled.
lifetime_spend_capinteger nullable

Note: The default for this field is null, which is treated the same as 0. For campaign budget optimization, a daily or lifetime spend cap must be set, but not both. For ad group level budgets, this field must be 0 or unset.

namestring

Campaign name - 255 chars max.

objective_type'AWARENESS' | 'CONSIDERATION' | 'WEB_CONVERSION' | 'CATALOG_SALES' | 'VIDEO_COMPLETION' | 'APP_INSTALL' | 'SALES' | 'LEADS' | 'CTV_CONSIDERATION'

Intended result of the campaign. You can only update objectives for draft campaigns. WEB_SESSIONS and VIDEO_VIEW objectives are deprecated. We recommend using VIDEO_COMPLETION as an alternative for the latter.

order_line_idstring nullable

Note: To clear this field on update, set the order line ID to 0. Order line ID that appears on the invoice. The order line must not be expired.

start_timeinteger nullable

Timestamp in Unix format for scheduling when ads in the campaign start to appear. Must precede any start times set for child ad groups. Defaults to current time if no time is specified. Learn about scheduling campaigns. Different start times can be set for the campaign's child ad groups, but they cannot occur before a start_time specified for the campaign.

  • If your campaign has a child ad group with a start time specified, and if you update that campaign with a start_time that is later than that of the ad group, the campaign start_time will supersede the ad group start_time, and the request will not return an error.
  • In this scenario, if you call List campaigns or List ad groups, the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence.
status'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT'

Entity status

Example request

[
  {
    "ad_account_id": "549755885175",
    "app_id": "429047995",
    "bid_options": {
      "age_bucket_multipliers": {
        "18-24": 0.9,
        "25-34": 1.1,
        "35-44": 1.2
      },
      "app_type_multipliers": {
        "android_mobile": 1.1,
        "android_tablet": 1.1,
        "ipad": 1.2,
        "iphone": 1.2,
        "web": 0.9,
        "web_mobile": 0.8
      },
      "audience_multipliers": {
        "123": 1.1,
        "456": 1.2
      },
      "frequency_multipliers": {
        "0": 1.5,
        "1": 1.3,
        "2": 0.8
      },
      "gender_multipliers": {
        "female": 2.1,
        "male": 0.8
      },
      "placement_multipliers": {
        "browse": 0.9,
        "search": 1.2,
        "related_pins": 1.1
      }
    },
    "daily_spend_cap": 1432744744,
    "end_time": 1644023526,
    "id": "549755885175",
    "is_automated_campaign": true,
    "is_campaign_budget_optimization": true,
    "is_flexible_daily_budgets": true,
    "is_ltv_optimized": true,
    "is_performance_plus": true,
    "is_top_of_search": true,
    "lifetime_spend_cap": 1432744744,
    "name": "ACME Tools",
    "order_line_id": "549755885175",
    "start_time": 1580865126,
    "status": "ACTIVE",
    "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": {
        "ad_account_id": "549755885175",
        "bid_options": {
          "age_bucket_multipliers": {
            "18-24": 0.9,
            "25-34": 1.1,
            "35-44": 1.2
          },
          "app_type_multipliers": {
            "android_mobile": 1.1,
            "android_tablet": 1.1,
            "ipad": 1.2,
            "iphone": 1.2,
            "web": 0.9,
            "web_mobile": 0.8
          },
          "audience_multipliers": {
            "123": 1.1,
            "456": 1.2
          },
          "frequency_multipliers": {
            "0": 1.5,
            "1": 1.3,
            "2": 0.8
          },
          "gender_multipliers": {
            "female": 2.1,
            "male": 0.8
          },
          "placement_multipliers": {
            "browse": 0.9,
            "search": 1.2,
            "related_pins": 1.1
          }
        },
        "created_time": 1432744744,
        "daily_spend_cap": 1432744744,
        "end_time": 1644023526,
        "id": "549755885175",
        "is_automated_campaign": true,
        "is_campaign_budget_optimization": true,
        "is_carting": true,
        "is_flexible_daily_budgets": true,
        "is_ltv_optimized": true,
        "is_performance_plus": true,
        "is_top_of_search": true,
        "lifetime_spend_cap": 1432744744,
        "name": "ACME Tools",
        "order_line_id": "549755885175",
        "start_time": 1580865126,
        "status": "ACTIVE",
        "tracking_urls": {
          "impression": [
            "URL1",
            "URL2"
          ],
          "click": [
            "URL1",
            "URL2"
          ],
          "engagement": [
            "URL1",
            "URL2"
          ],
          "buyable_button": [
            "URL1",
            "URL2"
          ],
          "audience_verification": [
            "URL1",
            "URL2"
          ]
        },
        "type": "campaign",
        "updated_time": 1432744744
      },
      "exceptions": [
        {
          "code": 2,
          "message": "Advertiser not found."
        }
      ]
    }
  ]
}

Changes

  • v5b698c180678aRevision changes
    • breaking

      added the new required request property /

    • warning

      removed subschema #3 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

      removed from the response body allOf list for the response 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 non-success response with the status

    • info

      added the required property to the response with the status

  • v543134ca41f18Revision changes
    • breaking

      removed the enum value VIDEO_VIEW of the request property //////

    • breaking

      removed the enum value WEB_SESSIONS of the request property //////

    • warning

      removed the request property //

    • info

      added the new optional request property //////

    • info

      added the new optional request property //

    • info

      added the optional property //////////// to the response with the status

    • info

      added the optional property //////////// to the response with the status

    • info

      removed the VIDEO_VIEW enum value from the //////////// response property for the response status

    • info

      removed the VIDEO_VIEW enum value from the //////// response property for the response status

    • info

      removed the WEB_SESSIONS enum value from the //////////// response property for the response status

    • info

      removed the WEB_SESSIONS enum value from the //////// response property for the response status