Marketing API

Advantage+ Shopping Campaigns

Advantage+ shopping campaigns is a solution that enables ecommerce and retail direct-to-consumer and brand advertisers to potentially achieve better performance, greater personalization and more efficiency. These campaigns provide greater flexibility to control levers such as creative, targeting, placements and budget, and more opportunities to optimize campaigns that drive conversions.

Instead of running several campaigns with segmented audiences, Advantage+ shopping campaigns lets you combine all your audiences for a given market into a single campaign structure. This is designed to simplify creation and management, while reducing audience overlap.

Manual Campaign Setup Compared to Advantage+ Shopping Campaigns

Manual BAU Campaign SetupAdvantage+ Shopping Campaign

Multiple BAU campaigns

BAU portfolio replacement


Manual Targeting with 7 Targeting levers


Automated targeting, automation to increase setup efficiency with 1 country input


Strict budget allocations in multiple campaigns


Budget liquidity within 1 campaign


Test up to 50 creative combinations


Allows both dynamic and static ads with up to 150 creative combinations


This document outlines the steps you need to follow to set up your integration for Advantage+ shopping campaigns. You will need to:

  1. Define Existing Customers
  2. Create Campaign
  3. Verify Campaign Creation
  4. Create Ad Set
  5. Provide Creative and Create Ads
  6. Set Minimum Age Constraint and Geo Exclusion (See Ad Account Controls reference doc)

Learn more about Cross-Channel Conversion Optimization for Advantage+ shopping campaigns.

Step 1: Define Your Existing Customers

Advantage+ shopping campaigns allows you to define your existing customers as a collection of custom audience IDs. Your existing customers are users who are already familiar with your business/product. Once this definition is set up, you can use this to segment your budget for Advantage+ shopping campaigns to limit spend on existing customers. We will also provide you with metrics reporting the performance of your campaigns among these different segments.

You can define your ad by posting to the /act_{ad_account_id} endpoint. You will need to include the following parameter to set up this definition:

ParameterDescription

existing_customers

Array<string>

Array of custom audience IDs that the ad account has access to. Currently the supported sources for the custom audience are website, app activity, customer list, catalog and offline activity.


For information on how to create a custom audience, refer to this page.

Example

curl -X POST \
  -F 'existing_customers=[<CUSTOM_AUDIENCE_ID>, <CUSTOM_AUDIENCE_ID>]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>

For more information on tracking new and existing audiences in third-party tracking tools, see Audience Type URL Parameters.

Step 2: Create Campaign

Start by creating your ad campaign. To do this, make a POST request to /act_{ad_account_id}/campaigns.

Parameters


ParameterDescription

name
string

Required
Name for the Advantage+ shopping campaign

objective
enum

Required
Campaign's objective. Specify CONVERSIONS or OUTCOME_SALES for this type of ad

special_ad_categories

list<Object>

Required
Special ad categories associated with the Advantage+ shopping campaign

adlabels

list<Object>

Optional
Ad Labels associated with the Advantage+ shopping campaign

buying_type
string

Optional
Advantage+ shopping campaigns only support the value AUCTION

execution_options

list<enum>

Optional
Default value: set. Other options are:

  • validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
  • include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.

If the call passes validation or review, the response will be {"success": true}. If the call does not pass, an error will be returned with more details.

smart_promotion_type
enum

Required
To specify this is an Advantage+ shopping campaign, the smart promotion type should be set to AUTOMATED_SHOPPING_ADS

status
enum

Optional
Valid options are: PAUSED and ACTIVE.


If this status is PAUSED, all its active ad sets and ads will be paused and have an effective status CAMPAIGN_PAUSED

Campaign Create Example

curl -X POST \
  -F 'name=Advantage+ Shopping Campaign' \
  -F 'objective=OUTCOME_SALES' \
  -F 'status=ACTIVE' \
  -F 'special_ad_categories=[]' \
  -F 'smart_promotion_type=AUTOMATED_SHOPPING_ADS' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/campaigns

Updating

You can update a Campaign by making a POST request to /{campaign_id}.

Parameters


ParameterDescription

name
string

Name for the Advantage+ shopping campaign

special_ad_categories

list<Object>

Special ad categories associated with the Advantage+ shopping campaign

adlabels

list<Object>

Ad Labels associated with the Advantage+ shopping campaign

execution_options

list<enum>

Default value: set. Other options are:

  • validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
  • include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.

If the call passes validation or review, the response will be {"success": true}. If the call does not pass, an error will be returned with more details.

topline_id
numeric string or integer

Topline ID

status
enum

You can use the following status for an update API call:

  • ACTIVE
  • PAUSED
  • DELETED
  • ARCHIVED

If an ad campaign is set to PAUSED, its active child objects will be paused and have an effective status CAMPAIGN_PAUSED.

Campaign Update Example

curl -X POST \
  -F 'name=Advantage+ Shopping Update Sample Campaign' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<CAMPAIGN_ID>

Step 3: Verify Campaign Creation

To verify that you have successfully created an Advantage+ shopping campaign, you can make a GET request to /<AD_CAMPAIGN_ID> with the field smart_promotion_type.

A valid Advantage+ shopping campaign will return the field value AUTOMATED_SHOPPING_ADS.

Example

curl -X GET -G \
  -d 'fields=smart_promotion_type' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_CAMPAIGN_ID>

Response

{
  "smart_promotion_type": "AUTOMATED_SHOPPING_ADS",
  "id": <AD_CAMPAIGN_ID>
}

Step 4: Create Ad Set

Once you have an ad campaign, create your ad set. Each Advantage+ shopping campaign can only have one ad set associated with it.

To create an ad set, make a POST request to /act_{ad_account_id}/adsets.

Parameters


ParameterDescription

campaign_id
numeric string or integer

Required
A valid Advantage+ shopping campaign you wish to add this ad set to.

name
string

Required
Name for the Advantage+ shopping campaign

promoted_object
Object

Required
The object this ad set is promoting across all its ads. For Advantage+ shopping campaigns, provide:

  • pixel_id and
  • custom_event_type: Advantage+ shopping ad set supports the following events: PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, ADD_TO_WISHLIST, CONTENT_VIEW, COMPLETE_REGISTRATION, DONATE, START_TRIAL, SUBSCRIBE, SEARCH, OTHER. Customer conversion events are not supported.

Learn more about cross-channel conversion optimization for Advantage+ shopping campaigns.

targeting
Targeting object

Required
An Advantage+ shopping ad set’s targeting structure. Only geo_locations are allowed to be specified.

geo_locations
array

Required
Used to limit the audience of the ad set by

  • countries — Country targeting. Requires an array of 2-digit ISO 3166 format codes.
    Example:
    {
  "geo_location": {
    "countries": [“US”]
  },
}
  • regions — State, province, or region. See Targeting Search, Regions for available values. Limit: 200.
    Example:
    {
  "geo_location": {
    "regions": [{"key":"3847"}]
  },
}

daily_budget
int64

Optional
The daily budget defined in your account currency, allowed only for ad sets with a duration (difference between end_time and start_time) longer than 24 hours.


Either daily_budget or lifetime_budget must be greater than 0.

lifetime_budget
int64

Optional
Lifetime budget, defined in your account currency. If specified, you must also specify an end_time.


Either daily_budget or lifetime_budget must be greater than 0.

end_time
datetime

Required when lifetime_budget is specified.
When creating an ad set with a daily_budget, specify end_time=0 to set the ad set as ongoing with no end date. UTC UNIX timestamp


Example: 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT.

optimization_goal
enum

Optional
Select OFFSITE_CONVERSIONS as the optimization goal to maximize number of conversions. Select VALUE as the optimization goal if you want to maximize value of conversions. In Ads Manager, we display Highest Value as your bid strategy.

bid_strategy
enum

Optional

  • LOWEST_COST_WITHOUT_CAP: Facebook automatically bids on your behalf and gets you the lowest cost results. Automatically increase your effective bid as needed to get the results you want based on your given optimization_goal. This is the default bid_strategy when optimization_goal is OFFSITE_CONVERSION or VALUE.
  • LOWEST_COST_WITH_MIN_ROAS: Specific bidding option for value optimization. You must specify a roas_average_floor, which is the minimum return wanted from ads spend. See Minimum Return on Advertiser Spend Bidding.
  • COST_CAP: Get the most results possible while we strive to meet the cost per action you set. You must provide a cap number in the bid_amount field. Note: Adherence to cost cap limits is not guaranteed. See Cost Cap.

bid_amount

Required if bid_strategy is COST_CAP.

bid_constraints
JSON object

Optional

  • optimization_goal must be VALUE.
  • bid_strategy must be LOWEST_COST_WITH_MIN_ROAS.
  • Min ROAS bidding uses bid_constraints to pass the "ROAS floor", but you cannot use with bid_constraints, use roas_average_floor instead. See Minimum Return on Advertiser Spend Bidding.
  • The valid range of roas_average_floor is [100, 10000000], inclusive. This means that the valid range of "minimum ROAS" is [0.01, 1000.0] or [1%, 100000.0%], inclusive.

billing_event
enum

Required
A billing event for the ad set. Only IMPRESSIONS is supported for Advantage+ shopping campaigns.

existing_customer_budget_percentage
number

Optional
Specifies the maximum percentage of the budget that can be spent on the existing customers associated with this ad account. Lower values may lead to higher costs per conversion. Valid values are between 0-100.

adlabels

list<Object>

Optional

Specifies a list of labels to be associated with this object.

start_time
datetime

Optional.
The start time of the set. UTC UNIX timestamp


Example: 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT.

time_start
datetime

Optional

Time start

time_stop
datetime

Optional

Time stop

attribution_spec

list<JSON Object>

Optional
Conversion attribution spec used for attributing conversions for optimization.

Ad Set Create Example

curl -X POST \
  -F 'name=Advantage+ Shopping Sample Ad Set' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'promoted_object={ "pixel_id": "<PIXEL_ID>", "CUSTOM_EVENT_TYPE": "PURCHASE" }' \
  -F 'daily_budget=<NUM>' \
  -F 'existing_customer_budget_percentage=<NUM>' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'targeting={"geo_locations": {"countries": ["US"]}}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/adsets

Updating

You can update an Ad Set by making a POST request to /{ad_set_id}.

Parameters


ParameterDescription

adlabels

list<Object>

Specifies a list of labels to be associated with this object. This field is optional.

daily_budget
int64

The daily budget defined in your account currency, allowed only for ad sets with a duration (difference between end_time and start_time) longer than 24 hours.


Either daily_budget or lifetime_budget must be greater than 0.

existing_customer_budget_percentage
number

Specifies the maximum percentage of the budget that can be spent on the existing customers associated with this ad account. Lower values may lead to higher costs per conversion. Valid values are between 0-100.

end_time
datetime

End time, required when lifetime_budget is specified.


Example: 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT


When creating an ad set with a daily budget, specify end_time=0 to set the ad set as ongoing with no end date.


UTC UNIX timestamp.

execution_options

list<enum>

Default value: set. Other options are:

  • validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
  • include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.

If the call passes validation or review, the response will be {"success": true}. If the call does not pass, an error will be returned with more details.

start_time
datetime

The start time of the set. Must be provided in UTC UNIX timestamp.


Example: 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT.

status
enum

Available options for updates:

  • ACTIVE
  • PAUSED
  • DELETED
  • ARCHIVED

If it is set to PAUSED, all its active ads will be paused and have an effective status ADSET_PAUSED.

lifetime_budget
int64

Lifetime budget, defined in your account currency. If specified, you must also specify an end_time.


Either daily_budget or lifetime_budget must be greater than 0.

time_start
datetime

Time start

time_stop
datetime

Time stop

targeting
Targeting object

Targeting structure for your ad set. Valid values for targeting are geo_locations.

geo_locations
array

Required
Used to limit the audience of the ad set by

  • countries — Country targeting. Requires an array of 2-digit ISO 3166 format codes.
    Example:
    {
  "geo_location": {
    "countries": [“US”]
  },
}
  • regions — State, province, or region. See Targeting Search, Regions for available values. Limit: 200.
    Example:
    {
  "geo_location": {
    "regions": [{"key":"3847"}]
  },
}

attribution_spec

list<JSON Object>

Optional
Conversion attribution spec used for attributing conversions for optimization.

Ad Set Update Example

curl -X POST \
  -F 'name=Advantage+ Shopping Sample Updated Ad Set' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_SET_ID>

Step 5: Provide Creative and Create Ads

Once you have an ad set, you can create your ad by posting to the /act_{ad_account_id}/ads endpoint. You may include the following parameters

Parameters


ParameterDescription

name
string

Required
Name of the ad

adset_id
int64

Required
The ID of the ad set, required on creation.

creative
AdCreative

Required
The creative spec or the ID of the ad creative to be used by this ad. Valid fields are:

  • object_story_spec
  • product_set_id
  • use_page_actor_override
  • creative_id

You can read more about creatives here


Provide the creative in the following format: {"creative_id": <CREATIVE_ID>}


Or provide a creative spec:

{
        "creative": {
          "name": <NAME>, 
          "object_story_spec": <SPEC>,
          "product_set_id": <PRODUCT_SET_ID>
        }
}

status
enum

Optional
Only ACTIVE and PAUSED are valid during creation. During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

adlabels

list<Object>

Optional
Ad Labels associated with this ad

execution_options

list<enum>

Optional
Default value: set.

  • validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
  • synchronous_ad_review: this option should not be used by itself. It should always be specified with validate_only. When these options are specified, the API call will perform Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
  • include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.

If the call passes validation or review, the response will be {"success": true}. If the call does not pass, an error will be returned with more details.

Ad Create Example

curl -X POST \
  -F 'name=Advantage+ Shopping campaign Sample Ad' \
  -F 'adset_id=<ADSET_ID>' \
  -F 'creative={"name": <NAME>, "object_story_spec": <SPEC>}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/ads

Creative Fields

For a full list of Ad Creative fields, see here.

FieldDescription

object_story_spec
AdCreativeObjectStorySpec

Required
Use if you want to create a new unpublished page post and turn the post into an ad. The Page ID and the content to create a new unpublished page post.

use_page_actor_override
AdCreative

Required
If true, we display the Facebook page associated with the Advantage shopping ads.

Create Creative Example

curl -X POST \
  -F 'object_story_spec=<SPEC>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/adcreatives

Updating

You can update an Ad by making a POST request to /{ad_id}.

Parameters


ParameterDescription

name
string

New name of the ad

adlabels

list<Object>

Ad labels associated with this ad.

execution_options

list<enum>

Default value: set. Other options are:

  • validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
  • synchronous_ad_review: this option should not be used by itself. It should always be specified with validate_only. When these options are specified, the API call will perform Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
  • include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.

If the call passes validation or review, the response will be {"success": true}. If the call does not pass, an error will be returned with more details.

status
enum

Options are:

  • ACTIVE
  • PAUSED
  • DELETED
  • ARCHIVED

During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

creative
AdCreative

The creative spec of the ad creative to be used by this ad. Valid fields are object_story_spec, asset_feed_spec, and use_page_actor_override and can be viewed here. You can read more about creatives here


Provide the creative in the following format:

{
    "creative": {
      "name": <NAME>, 
      "object_story_spec": <SPEC>,
      "product_set_id": <PRODUCT_SET_ID>
    }
}

Ad Update Example

curl -X POST \
  -F 'name=Advantage+ Shopping campaign Sample Update Ad' \
  -F 'creative={"name": <NAME>, "object_story_spec": <SPEC>}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_ID>

Learn More