Commerce Platform

Migrate to Simplified Version of Shops Ads API

We are making changes to Shops to make it easier for businesses to maintain their shop while maximizing ROI from Shops ads. Buyers will still discover new products and build their carts on Facebook and Instagram, but now the final checkout will always happen on the advertiser’s optimized website checkout flow – which includes any additional payment method integrations, cross-sell/up-sell methods (like bundles and average order value (AOV) plugins), and rich brand storytelling elements.

Please ensure you have migrated to the new version of the Shops ads API by August 11, 2025 to prevent any disruption to your business.

Before You Begin

To create a product catalog sale or conversion ad using the website and shop destination, you will need:

  • A shop using offsite checkout with in-app browser (IAB).
  • A Facebook Page or Instagram account connected to your shop.
  • A catalog connected to your shop. See the Catalog Fields documentation for the required fields for commerce and ads.
  • Commerce eligibility for Shops ads.

Step 1: Commerce Eligibility for Shops Ads

To know if a shop can be used as a destination in your creative, it has to have the following properties:

  1. CTA: offsite_iab_checkout
  2. Campaign contains at least one of the offsite_iab_checkout_enabled_countries

Request

curl -i -X GET \ "https://graph.facebook.com/v23.0/411624925357565/commerce_merchant_settings?fields=id%2Cshops%7Bid%2Cfb_sales_channel%7D%2Ccta%2Coffsite_iab_checkout_enabled_countries&access_token={access_token}"


-----
{
  "access_token": "{access_token}",
  "fields": "id,shops{id,fb_sales_channel},cta,offsite_iab_checkout_enabled_countries"
}

Example Response

{
  "data": [
    {
      "id": CMS_ID,
      "shops": {
        "data": [
          {
            "id": SHOP_ID,
            "fb_sales_channel": {
              "status": "ENABLED",
              "fb_page": {
                "name": PAGE_NAME,
                "id": PAGE_ID
              }
            }
          }
        ],
        "paging": {
          "cursors": {
            "before": TOKEN,
            "after": TOKEN
          }
        }
      },
      "cta": "OFFSITE_IAB_CHECKOUT",
      "offsite_iab_checkout_enabled_countries": [
        "US"
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": TOKEN,
      "after": TOKEN
    }
  }
}

Shops call to action (CTA) can change from onsite_checkout to offsite_iab_checkout but not the other way around. A shop can become ineligible and move from offsite_iab_checkout to other CTAs such as offsite_link.

Step 2: Creating a campaign

Start by creating your ad campaign with a POST request to /act_{ad_account_id}/campaigns.

At this level, you must set your advertising goal through the objective field. For Shops ads, the supported objectives are PRODUCT_CATALOG_SALES and CONVERSIONS for non-Outcome-Driven Ad Experience (ODAX), and OUTCOME_SALES objective for ODAX.

For the PRODUCT_CATALOG_SALES objective, the promoted_object is product catalog ID. Note the product catalog has to be connected to an offsite_iab_checkout shop to be eligible for Shops ads.

For the CONVERSIONS objective, the promoted_object field is not required.

Examples for Non-ODAX Objectives

Example of creating a campaign with the 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 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v22.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 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v22.0/act_<AD_ACCOUNT_ID>/campaigns

Examples for ODAX Objectives

Example of creating a PRODUCT_CATALOG_SALES campaign with the 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/v22.0/act_<AD_ACCOUNT_ID>/campaigns

Example of creating a CONVERSIONS campaign with the 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/v22.0/act_<AD_ACCOUNT_ID>/campaigns

Step 3: Create an Ad Set

For Shops ads, you must specify the destination type as WEBSITE for your ad set.

  • If the objective of the campaign is set to PRODUCT_CATALOG_SALES, you must provide a product set ID in promoted_object to promote products from that product set.
  • If the object of the campaign is set to CONVERSIONS, define your promoted_object to be a commerce account with offsite_iab_checkout enabled.

Other requirements for Shops ads.

  • Shops ads only supports PURCHASE as a conversion event (CUSTOM_EVENT_TYPE) in the product set (if the objective is PRODUCT_CATALOG_SALES) or in the Meta Pixel (if the objective is CONVERSIONS).
  • Shops ads only support optimizing for offsite conversions (OFFSITE_CONVERSIONS as optimization_goal).
  • Shops ads only support a bid strategy without a cost cap.
  • In order for Shops ads to be delivered to the shop, targeting must include audiences in countries included in offsite_iab_checkout_enabled_countries.
  • In order for Shops ads to be delivered to the shop, the placement must include at least one platform with offsite_iab_checkout checkout support (currently, Facebook and Instagram).

Example of creating a Shops ads ad set with a campaign with the PRODUCT_CATALOG_SALES objective that is billed on IMPRESSIONS:

curl \
  -F 'name=Product Catalog Sales Adset' \
  -F 'bid_amount=3000' \
  -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=WEBSITE \
  -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/v22.0/act_<AD_ACCOUNT_ID>/adsets

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

curl \
  -F 'name=Conversion Adset' \
  -F 'bid_amount=3000' \
  -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=WEBSITE' \
  -F 'promoted_object={"pixel_id": <PIXEL_ID>, "custom_event_type": "PURCHASE"}
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v22.0/act_<D_ACCOUNT_ID>/adsets

Step 4: Provide a Creative

You first need to set the destination_spec > destination_type field to WEBSITE_AND_SHOP.

Request

curl -i -X POST \
"https://graph.56617.od.facebook.com/v23.0/act_id/adcreatives?access_token=%7Baccess_token%7D&destination_spec=%7B%22destination_type%22%3A%22WEBSITE_AND_SHOP%22%7D&name=My%20creative%20title&object_story_spec=%7B%22link_data%22%3A%7B%22call_to_action%22%3A%7B%22type%22%3A%22SHOP_NOW%22%7D%2C%22link%22%3A%22example.org%22%7D%2C%22page_id%22%3A%22PAGE_ID%22%7D"

Carousel Ads or Image/Video Ads

You can create a carousel ad just like non-Shops ads. If the objective of your campaign is CONVERSIONS, you can also create an image/video ad.

The page_id and/or instagram_user_id specified in object_story_spec must have at least one shop belonging to the commerce account you chose to promote in your ad set or the catalog you chose to promote in your campaign. They must also be connected to the same commerce account.

Additionally for Shops ads, you need to specify an onsite destination as an alternative destination for your offsite landing page. To do this, set the onsite_destination field in the asset_feed_spec of your creative.

Onsite destination must be one of:

  • Shop storefront page: The shop must belong to the commerce account you promote in your ad set.
  • 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.
  • 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 a creative for an image ad:

curl \
  -F 'name=Sample Creative' \
  -F 'asset_feed_spec= {
        "onsite_destinations": [
          {
            "storefront_shop_id": "<SHOP_STOREFRONT_ID>"
          }
        ]
      }' \
  -F 'destination_spec= {
   "desination_type": "WESBITE_AND_SHOP"
     }' \
  -F 'object_story_spec={ 
    "link_data": { 
      "image_hash": "<IMAGE_HASH>", 
      "link": "<OFFSITE_LANDING_URL>", 
      "call_to_action": {
        "type": "SHOP_NOW"
      },
      "message": "try it out" 
    }, 
    "page_id": "<PAGE_ID>",
    "instagram_user_id" : "<IG_USER_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v22.0/act_<AD_ACCOUNT_ID>/adcreatives

Advantage+ Creative for Catalog

Shops ads also support Advantage+ creative for catalog. This feature displays different formats and ad creatives to different aAccount cCenter 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.

The page_id and/or instagram_user_id specified in object_story_spec must have at least one shop belonging to the commerce account you chose to promote in your ad set or the catalog you chose to promote in your campaign. They must also be connected to the same commerce account.

For the product set in the 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 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 Advantage+ creative for catalog:

curl  -i -X POST \
  -F 'name=Sample Creative' \
  -F 'product_set_id="<PRODUCT_SET_ID>"' \
  -F 'destination_spec= {
   "desination_type": "WEBSITE_AND_SHOP"
     }' 
  -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_user_id” : “<IG_USER_ID>” 
  }' \
  -F 'degrees_of_freedom_spec={
      "creative_features_spec": {
        "standard_enhancements": {
          "enroll_status": "OPT_OUT"
        }
      }
    }' \ 
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v22.0/act_<AD_ACCOUNT_ID>/adcreatives

Step 5: 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/v22.0/act_<AD_ACCOUNT_ID>/ads

Shops Ads with Advantage+ Shopping Campaigns

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.

Get Commerce IDs for Creating Shops Ads

To create a Shops ad for a Page, you need:

You can get the Commerce Account ID and Shop ID by running the previous query:

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

A commerce account might have multiple shops., Yyou need to get the one with the Page you want to create Shops ads with.

For catalog ID, product set ID and product ID:

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

Sample Response

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