Shops Ads Marketing API Guidebook

This guide is for partners and agencies to help them integrate Shops Ads using the Marketing API.

Integrating Shops Ads through the API is similar to the flow of setting up a regular Business-As-Usual (BAU) Ad campaign. This guide presumes that advertisers are familiar with creating a BAU Ad Campaign. Please refer to our Marketing API - Getting Started guide, for more information on BAU Ad Campaigns.

You can let us know that you want to create a Shops Ads campaign by specifying additional fields in your requests during the Ad campaign creation process. This guide will provide a step-by-step walkthrough to help you create a successfully running Shops Ads campaign.

When reaching out to us via Direct Support for questions or issues related to Shops Ads, please also provide us with the following:

• Ad Account IDs for which you want to enable this feature
• App ID

Additionally, we would really appreciate it if you could include [Shops Ads] in the title of the Direct Support ticket, thank you!

What are Shops Ads?

Shops Ads is an ad solution that optimizes the buyer journey across a seller’s Shop and Website to drive value for both sellers (more purchases) and buyers (better experience).

Shops Ads enables advertisers to run Ad campaigns which automatically directs users to either the sellers shop on Facebook/Instagram or their Website once they click on the ad, depending on which sales channel is most likely to drive a conversion.

Using the Marketing API, advertisers will gain the ability to publish Multi-Destination Shops Ads (MDSA), i.e. ads that can land you on a shop or a website when you click on them. Therefore, multi-destination.

Before you Begin

In order to create Shops Ads, you will need:

• Shop with onsite-checkout enabled on Facebook and Instagram.
• Shop connected to Facebook page or Instagram account.
• Shop connected to your catalog. Refer to this doc for required fields for commerce and ads.

Get Started

This is how the process of Shops Ads creation using the Marketing API will look like:

• Step 0: Check for Shops Ads Eligbility and get Commerce IDs for creating Shops Ads. This step verifies if a seller is eligible for onsite checkout and get the necessary IDs required for Shops Ads campaign creation.
• Step 1: Create an Ad Campaign
• Step 2: Create an Ad Set
• Step 3: Provide an Ad creative
• Step 4: Create an Ad

Shops Ads are also supported together with Advantage+ Shopping Campaigns (A+SC or ASC). To create an A+SC with Shops Ads, follow the steps in Advantage+ Shopping guide to create a campaign first and then see the section in this doc to create Shops Ads in ASC.

Step 1: Create an Ad Campaign

Start by creating an Ad Campaign.

Make a POST request to /act_{ad_account_id}/campaigns

Set the following params in your campaign request for Shops Ads.

Examples for non-ODAX objectives;

Example of creating a campaign with PRODUCT_CATALOG_SALES objective.

curl \
-F 'name=Product Catalog Sales Campaign' \
-F 'objective=PRODUCT_CATALOG_SALES' \
-F 'promoted_object={"product_catalog_id":"<PRODUCT_CATALOG_ID>"}' \
-F 'status=PAUSED' \
-F 'special_ad_categories=[]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/campaigns

Example of creating a campaign with the CONVERSIONS objective.

curl \
-F 'name=Conversion Campaign' \
-F 'objective=CONVERSIONS' \
-F 'status=PAUSED' \
-F 'special_ad_categories=[]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/campaigns

Examples for ODAX objective;

Example of creating a PRODUCT_CATALOG_SALES campaign with OUTCOME_SALES objective.

curl \
-F 'name=Conversion Campaign' \
-F 'objective=OUTCOME_SALES' \
-F 'promoted_object={"product_catalog_id":"<PRODUCT_CATALOG_ID>"}' \
-F 'status=PAUSED' \
-F 'special_ad_categories=[]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/campaigns

Example of creating a CONVERSIONS campaign with OUTCOME_SALES objective.

curl \
-F 'name=Conversion Campaign' \
-F 'objective=OUTCOME_SALES' \
-F 'status=PAUSED' \
-F 'special_ad_categories=[]'
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/campaigns

Step 2: Create an Ad Set

Create an Ad set.

Make a POST request to /act_{ad_account_id}/adsets

You will need to specify the following params in your adset request for Shops Ads.

Other requirements for Shops Ads:

• Shops Ads only supports a bid strategy without a cost cap.
• In order for Shops Ads to be delivered to the shop,

  • Targeting must include audiences in regions with onsite checkout support (currently, United States)
  • Placement must include at least one platform with onsite-checkout support (currently, Facebook and Instagram)

Example of creating a Shops Ads ad set with PRODUCT_CATALOG_SALES campaign objective that is billed on IMPRESSIONS.

curl \
-F 'name=Product Catalog Sales Adset' \
-F 'billing_event=IMPRESSIONS' \
-F 'daily_budget=15000' \
-F 'bid_strategy=LOWEST_COST_WITHOUT_CAP' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'targeting={"geo_locations": {"countries":["US"]}}' \
-F 'destination_type=SHOP_AUTOMATIC' \
-F 'promoted_object={"product_set_id":"<PRODUCT_SET_ID>","custom_event_type": "PURCHASE"}' \
-F 'status=PAUSED' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/adsets

Example of creating a Shops ads ad set with CONVERSIONS campaign objective that is billed on IMPRESSIONS.

curl \
-F 'name=Conversion Adset' \
-F 'billing_event=IMPRESSIONS' \
-F 'daily_budget=15000' \
-F 'bid_strategy=LOWEST_COST_WITHOUT_CAP' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'targeting={"geo_locations": {"countries":["US"]}}' \
-F 'destination_type=SHOP_AUTOMATIC' \
-F 'promoted_object= {
"omnichannel_object":{
"onsite":[
{
"commerce_merchant_settings_id":"<COMMERCE_ACCOUNT_ID>"
}
],
"pixel":[{
"pixel_id":"<PIXEL_ID>",
"custom_event_type":"PURCHASE"
}]
}
}' \
-F 'status=PAUSED' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<D_ACCOUNT_ID>/adsets

See Error Code section for more information on errors received while creating an Ad set.

Step 3: Provide an Ad creative

With Shops Ads ad sets, you can create;

• Carousel ads
• Image/video ads (only when the campaign objective is CONVERSIONS)
• Advantage+ catalog ads with Carousel ad format
• Ads with Advantage+ creative for catalog

Shops ads do not support:

• Image/video ad formats when the campaign objective is PRODUCT_CATALOG_SALES
• Collection ad formats
• Calls to action set to messaging a Page, Instagram, or WhatsApp
• Destinations set to an app, event, or Instant Experiences when the campaign objective is CONVERSIONS

Carousel Ads or Image/Video Ads

You can create a Carousel ad just like non-Shops Ads. If your campaign objective is CONVERSIONS, you can also create an Image/Video ad.

Onsite destination must be one of the following:

• storefront_shop_id - Shop storefront page

  • The shop must belong to the commerce account you promote in your ad set.
• shop_collection_product_set_id - A product set

  • The product set must belong to the catalog of the commerce account you promote in your ad set and must contain at least one visible ‘in stock’ product.
• details_page_product_id - A product

  • The product must belong to the catalog of the commerce account you promote in your ad set.

Example onsite_destinations field in asset_feed_spec set to shop storefront page.

asset_feed_spec= {
"onsite_destinations": [
{
"storefront_shop_id": "<SHOP_STOREFRONT_ID>"
}
]
}

Example onsite_destinations field in asset_feed_spec set to product set.

asset_feed_spec= {
"onsite_destinations": [
{
"shop_collection_product_set_id": "<PRODUCT_SET_ID>"
}
]
}

Example onsite_destinations field in asset_feed_spec set to a specific product.

asset_feed_spec= {
"onsite_destinations": [
{
"details_page_product_id": "<PRODUCT_ID>"
}
]
}

Example of an Ad Creative for an Image Ad

curl \
-F 'name=Sample Creative' \
-F 'asset_feed_spec= {
"onsite_destinations": [
{
"storefront_shop_id": "<SHOP_STOREFRONT_ID>"
}
]
}' \
-F 'object_story_spec={ 
"link_data": { 
"image_hash": "<IMAGE_HASH>", 
"link": "<OFFSITE_LANDING_URL>", 
"message": "try it out" 
}, 
"page_id": "<PAGE_ID>",
"instagram_actor_id" : "<INSTAGRAM_ACTOR_ID>" 
}' \
-F 'degrees_of_freedom_spec={
"creative_features_spec": {
"standard_enhancements": {
"enroll_status": "OPT_OUT"
}
}
}' \ 
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/adcreatives

See Error Code section for more information on errors received while creating Ad creatives.

Advantage+ Catalog Ads (with Carousel Ad format)

To create Advantage+ Catalog Ads in Carousel ad format promoting products from a product set, you can follow Get Started with Advantage+ Catalog Ads - Step 3: Provide an Ad Creative.

For the product set in the ad creative:

• If you are setting up a campaign with PRODUCT_CATALOG_SALES as the objective, the product set you choose must belong to the catalog you set in your campaign and must be the same as the product set you choose to promote in your ad set.
• If you are setting up a campaign with CONVERSIONS as the objective, the product set you choose must belong to the catalog of the commerce account you choose to promote in your ad set.

Additional features supported for Shops ads with Advantage+ Catalog Ads are optimizations for shops.

Current supported shop optimizations are:

• shops_bundle - Shops bundle

  • This includes both ‘automated product tags’ and ‘reasons to shop’ optimizations. With this optimization type, we will automatically add any new optimization types to your ads to improve performance.
• automated_product_tags - Automated product tags

  • We may automatically tag products in your ad. Product tags send people directly to the relevant product page in your shop.
• reasons_to_shop - Reasons to shop

  • We may automatically highlight product information from your shop, like "Free shipping", "Trending" or "Low stock". We may also add an existing offer, which lets customers save on selected items in your shop.

To opt into ‘automated product tags’, set automated_product_tags to true in the template_data of the object_story_spec.

To opt-in to ‘reasons to shop’ or ‘shops bundle’, set reasons_to_shop to true or shops_bundle to true in the asset_feed_spec of your creative.

Examples of Advantage+ Catalog ads with Carousel Ad format promoting a product set with shop optimizations.

Opting in to shops_bundle

curl \
-F 'name=Sample Creative' \
-F 'product_set_id=<PRODUCT_SET_ID>' \
-F 'asset_feed_spec= {
"shops_bundle": true
}'\
-F 'object_story_spec={ 
"template_data": { 
"call_to_action":  {
"type": "SHOP_NOW"
},
"link": "<OFFSITE_LANDING_URL>",
"multi_share_end_card": false,
"name": "{{product.name}}"
}, 
"page_id": "<PAGE_ID>",
“instagram_actor_id” : “<INSTAGRAM_ACTOR_ID>” 
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/adcreatives

Opting in to automated_product_tags

curl \
-F 'name=Sample Creative' \
-F 'product_set_id=<PRODUCT_SET_ID>' \
-F 'object_story_spec={ 
"template_data": {
"automated_product_tags": true
"call_to_action":  {
"type": "SHOP_NOW"
},
"link": "<OFFSITE_LANDING_URL>",
"multi_share_end_card": false,
"name": "{{product.name}}"
}, 
"page_id": "<PAGE_ID>",
"instagram_actor_id" : "<INSTAGRAM_ACTOR_ID>"
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/adcreatives

Opting in to reasons_to_shop

curl \
-F 'name=Sample Creative' \
-F 'product_set_id=<PRODUCT_SET_ID>' \
-F 'asset_feed_spec= {
"reasons_to_shop": true
}'\
-F 'object_story_spec={ 
"template_data": { 
"call_to_action":  {
"type": "SHOP_NOW"
},
"link": "<OFFSITE_LANDING_URL>",
"multi_share_end_card": false,
"name": "{{product.name}}"
}, 
"page_id": "<PAGE_ID>",
“instagram_actor_id” : "<INSTAGRAM_ACTOR_ID>" 
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/adcreatives

See Error Code section for more information on errors received while creating Ad creatives.

Advantage+ creative for Catalog

Shops ads also support Advantage+ creative for Catalog. This feature displays different formats and ad creatives to different Account Center accounts based on what they are most likely to respond to. You can follow the instructions in Advantage+ Creative for Catalog - Step 3: Provide Ad Creative to set up your creative.

For the product set in the ad creative:

• If you are setting up a campaign with PRODUCT_CATALOG_SALES as the objective, the product set you choose must belong to the catalog you set in your campaign and must be the same as the product set you choose to promote in your ad set.
• If you are setting up a campaign with CONVERSIONS as the objective, the product set you choose must belong to the catalog of the commerce account you choose to promote in your ad set.

Example of an Ad with Advantage+ creative for catalog.

curl \
-F 'name=Sample Creative' \
-F 'product_set_id=<PRODUCT_SET_ID>' \
-F 'asset_feed_spec= {
"optimization_type":"FORMAT_AUTOMATION",
"ad_formats": ["CAROUSEL", "COLLECTION"],
"images": [{"hash": "<CUSTOMIZED_IMAGE_HASH>"}],
"descriptions": [{"text": "{{product.description}}", "From {{product.current_price}}", ...]
} 
}'\
-F 'object_story_spec={ 
"template_data": { 
"call_to_action":  {
"type": "SHOP_NOW"
},
"link": "<OFFSITE_LANDING_URL>",
"multi_share_end_card": false,
"name": "{{product.name}}"
}, 
"page_id": "<PAGE_ID>",
“instagram_actor_id” : “<INSTAGRAM_ACTOR_ID>” 
}' \
-F 'degrees_of_freedom_spec={
"creative_features_spec": {
"standard_enhancements": {
"enroll_status": "OPT_OUT"
}
}
}' \ 
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/adcreatives

See Error Code section for more information on errors received while creating Ad creatives.

Step 4: Create an ad

Finally, you can create an ad referencing an ad creative.

curl \
-F 'status=PAUSED' \
-F 'name=Test' \
-F 'adset_id=<ADSET_ID>' \
-F 'creative= {
"creative_id”: “<CREATIVE_ID>"
},
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/ads

See Error Code section for more information on errors received while creating an Ad.

Shops ads with Advantage+ Shopping Campaigns

Shops ads are supported together with Advantage+ Shopping Campaigns, which is believed to drive an even better performance when combined together. To create an Advantage+ Shopping Campaign with Shops Ads, follow the steps in Advantage+ Shopping Campaigns - Step 2: Create Campaign to create a campaign first.

When creating an ad set for Advantage+ Shopping Campaigns with Shops Ads, set the destination_type to SHOP_AUTOMATIC and specify your commerce account (commerce_merchant_settings_id) in the omnichannel_object under promoted_object.

curl \
-F 'name=Advantage+ Shopping Adset' \
-F 'billing_event=IMPRESSIONS' \
-F 'daily_budget=15000' \
-F 'bid_strategy=LOWEST_COST_WITHOUT_CAP' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'targeting={ "geo_locations": {"countries":["US"]}}' \
-F 'destination_type=SHOP_AUTOMATIC' \
-F 'promoted_object={"omnichannel_object":{"onsite":[{"commerce_merchant_settings_id":"<COMMERCE_ACCOUNT_ID>"}],"pixel":["pixel_id": "<PIXEL_ID>","custom_event_type": "PURCHASE"}']}} \
-F 'status=PAUSED' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v17.0/act_<AD_ACCOUNT_ID>/adsets

See Cross-Channel Conversion Optimization for Advantage+ Shopping Campaigns for more information. When creating an Ad creative and an Ad for Advantage+ Shopping Campaigns with Shops Ads, follow the steps in Step 3. Provide an Ad Creative and Step 4. Create an ad.

See Error Code section for more information on errors received while creating Advantage+ Shopping Adset.

Step 0: Check for Shops Ads Eligbility and get Commerce IDs for creating Shops Ads

In order to get relevant IDs for Shops ads, you need to get catalog_management permission from your client.

1. Check for Shops Ads eligibility

To create Shops Ads for a page, the page has to have an onsite visible shop. You can get this from:

Make a GET request to /{page_id}/commerce_merchant_settings

curl -i -X GET \
"https://graph.facebook.com/v17.0/<PAGE_ID>/commerce_merchant_settings?fields=id,shops{id,fb_sales_channel{fb_page{id,name}},is_onsite_enabled,shop_status}&access_token=<PAGE_ACCESS_TOKEN>"

Sample response

{
  "id": "<Commerce Account ID>",
  "shops": {
    "data": [
      {
        "fb_sales_channel": {
          "status": "STAGING",
          "fb_page": {
            "name": "Page 1",
            "id": "page_id_1"
          }
        },
        "id": "shop_1",
        "is_onsite_enabled": true,
        "shop_status": "INACTIVE"
      },
      {
        "fb_sales_channel": {
          "status": "ENABLED",
          "fb_page": {
            "name": "Page 2",
            "id": "page_id_1"
          }
        },
        "id": "shop_2",
        "is_onsite_enabled": true,
        "shop_status": "ACTIVE"
      }
    ],    
    // …
}

For the page you wish to create Shops Ads with, check if both is_onsite_enabled is true and shop_status is ACTIVE, if so, you will be able to create Shops Ads for the page through the query in the rest of the guide.

2. Get Commerce IDs for creating Shops Ads

To create a Shops Ad for a page, you need to get Commerce Account ID (for conversion Adset) Catalog ID (for PRODUCT_CATALOG_SALES Campaign) Product set ID (for PRODUCT_CATALOG_SALES Adset or catalog Ad) Shop ID (for carousel/image/video Ads) Product ID (for carousel/image/video Ads)

In order to create Shops Ads for a page, you will need IDs of the following assets:

• product_catalog_id (for PRODUCT_CATALOG_SALES campaign)
• product_set_id (for PRODUCT_CATALOG_SALES campaign)
• commerce_merchant_settings_id(for CONVERSIONS campaign)
• shop_storefront_id associated with the onsite checkout shop (for CAROUSEL/IMAGE/VIDEO ads)
• product_id (for CAROUSEL/IMAGE/VIDEO ads)

For Commerce Account ID and Shop ID, you can get through

curl -i -X GET \
"https://graph.facebook.com/v17.0/<PAGE_ID>/commerce_merchant_settings?fields=id,shops{id,fb_sales_channel{fb_page{id,name}}}&access_token=<ACCESS_TOKEN>"

A commerce account might have multiple shops, you need to get the one with the page you want to create Shops Ads with.

For catalog ID, product set ID and product ID, you can get them through

curl -i -X GET \
"https://graph.facebook.com/v17.0/<PAGE_ID>/commerce_merchant_settings?fields=id,product_catalogs{id,product_sets}&access_token=<ACCESS_TOKEN>"

Sample Response

{
  "id": "commerce_account_id",
  "product_catalogs": {
    "data": [
      {
        "id": "product_catalog_id",
        "product_sets": {
          "data": [
            {
              "id": "product_set_1",
              "name": "Product Set 1",
              "filter": "{\"product_item_id\":{\"is_any\":[]}}"
            },
          ],
        }
      }
    ]
  }
}