Collaborative Ads

Collaborative Ads is a solution built on top of Dynamic Ads. It enables brand advertisers to safely collaborate with a retailer or a marketing partner and achieve advertising goals such as target product for sales using retailer-provided content.

The retailer or marketing partner should share a catalog segment with the brand advertiser with all their products. This segment is a portion of their catalog or a superset of product sets. The brand advertiser can then accept this catalog segment and start running Dynamic Ads using this catalog segment. Brand advertisers cannot edit the catalog segment but they can create their own product sets from it.

An advertiser essentially runs a Dynamic Ads campaign for catalog sales with a product catalog. Therefore they can use standard Facebook ads reports which now include metrics related to the catalog segment.

In addition, you can use product-level reporting and retailer-level reporting to show only the brand’s purchases to the brand advertiser.

High-Level Steps

For retailers and marketing partners:

  • Step 1: Onboard into Collaborative Ads
  • Step 2: Create Catalog Segment - The segment must contain products belonging to one of its prospective brand partners.
  • Step 3: Share Catalog Segment with Brand Partner
  • (For Marketing Partners Only) Step 4: Provide Discovery Tools for Brands

For brands:

  • Step 1: Accept Catalog Segment
  • Step 2: Create Ad Campaign with Catalog Segment
  • Step 3: View Reporting - View reporting related to the products in the catalog segment.
  • Optional Step 4: Debugging - Use tools to diagnose and resolve problems, see Dynamic Ads, Debugging Tools.

Steps For Retailers and Marketing Partners

Step 1: Onboard into Collaborative Ads

To complete this step, your app needs business_management and catalog_management permissions.

Currently, this is not supported via API, and must be completed via UI. To start this process, click ‘Become a Retail Partner’ in the Collaborative Ads Retailer Directory.

Step 2: Create Catalog Segment

To complete this step, your app needs business_management and catalog_management permissions.

Create a catalog segment from one of your existing catalogs. The segment must contain all the products you would like to share with your brand partner.

To create a catalog segment via API, make a POST request to the owned_product_catalogs edge. The following fields are required for catalog segment creation:

  • parent_catalog_id: The parent catalog from which your segment was created. This catalog needs to be Collaborative Ads compliant. You can find your catalog’s status in Catalog Manager.
  • catalog_segment_filter: A JSON-encoded rule used to create the catalog segment.

Step 3: Share Catalog Segment

To complete this step, your app needs business_management and catalog_management permissions.

Share your catalog segment with your brand partner. To do this via API, make a POST request to /{catalog_segment_id}/agencies. In your call, you can add the following fields:

FieldDescription

business

type: numeric string or integer

Required.

ID for the business the catalog will be shared with.

permitted_tasks

type: array < enum {MANAGE, ADVERTISE} >

Required.

Tasks the business will be allowed to execute. Available options are: ['ADVERTISE', 'MANAGE'].

utm_settings

type: JSON object {enum{campaign_source,campaign_medium,campaign_name}: string}

Optional.

You can specify campaign_source, campaign_medium, and campaign_name.


For example: {campaign_source: “fb_campaign_source”}.

(For Marketing Partners Only) Step 4: Provide Discovery Tools for Brands

To complete this step, your app needs the business_management permission. The API call must include a user access token and that user needs to have permission on the suggested partner, business, or collaboration request.

As a marketing partner, you should provide a way for brands to discover possible Collaborative Ads partners. You can use the following endpoints to find retailers to work with:

If a brand finds a partner, you can reach out to the retailer with a collaboration request. Do that by making the following POST request to /{cpas-collaboration-request-id}:

{business-id}/collaborative_ads_collaboration_requests?
brands=”[“[BRAND NAME]”, “[BRAND NAME 2]”]”&
contact_email=[CONTACT_EMAIL]&
contact_first_name=[CONTACT_FIRST_NAME]&
contact_last_name=[CONTACT_LAST_NAME]&
phone_number=[PHONE NUMBER]&
receiver_business=[RECEIVING BUSINESS ID]

Keep track of your reach outs with the following endpoints:

Steps For Brands

Step 1: Accept Catalog Segment

To complete this step, your app needs the business_management permission.

If your brand has not used Collaborative Ads before, you need to accept the Terms of Service:

  • Call /received_sharing_agreements and get the BusinessAgreement ID.
  • Use agreement-request-id?request_status=APPROVE to accept the Terms of Service. Inside this page, search for agreement-request-id POST request for more information.

After accepting the terms, your brand can add people to the catalog segment using the /{product-catalog-id}/assigned_users endpoint.

Step 2: Create Ad Campaign

To complete this step, your app needs business_management and ads_management permissions.

Your brand can use the accepted catalog segment to create ad campaigns. You should use a separate ad account for each retailer you want to run Collaborative Ads for. Once the dedicated ad account is linked to a retailer, it can only select catalog segments belonging to that specific retailer.

To create and run ads you do as you normally do for your own product catalog, however you should provide catalog_segment_ID instead of a catalog ID:

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

On success, you get a new ad campaign ID:

{
"id": "<CAMPAIGN_ID>"
}

There are four fields which you can normally set with Dynamic Ads which you cannot with a catalog segment:

  • multi_share_end_card is set to false by default and you cannot change
  • You cannot change description in template_data
  • template_url_spec which you can use for deeplink URLs must point to merchant's website
  • Custom tracking specs are disabled

Step 3: View Reports

Once the ads are running, Brand Advertisers can get metrics on how ads are performing. We have several new insights metrics at different ad object levels. See catalog_segment_value and related metrics for:

catalog_segment_value aggregates the conversion events, including purchases, add-to-carts and view products for the catalog segment at each ad object level. It aggregates events across website, mobile and omni-channel sources. Learn more about Estimated and In-Development Insights Metrics.

Step 4: Debug and Diagnose Issues

Brands should now troubleshoot and debug any issues running their Dynamic Ads for the catalog segment.

See Dynamic Ads Debugging Tools.

Insights

The following estimated metrics are related to Collaborative Ads —see About Estimated, In development, and Third-party metrics.

To query any of our reporting metrics:

  • Your app needs to have ads_management and business_management permissions. See App Review.
  • You need to have a user access token and this user must be allowed to view reporting for the ad account in question.

Queries can be made on the following objects: ad account, ad campaign, ad set, and ad.

MetricDescription

catalog_segment_value

Value from aggregated conversion events, including purchases, add-to-carts and view products for the catalog segment at each ad object level.

catalog_segment_value_omni_purchase_roas

Total return on ad spend (ROAS) from purchases of items shared between Brand and Retailer. This number is based on information received from one or more Retailer' connected Facebook Business Tools. The amount is attributed to your ads.

catalog_segment_value_website_purchase_roas

Total return on ad spend (ROAS) from website purchases of items shared between Brand and Retailer. This number is based on information received from one or more Retailers' connected Facebook Business Tools. The amount is attributed to your ads.

catalog_segment_value_mobile_purchase_roas

The total return on ad spend (ROAS) from mobile app purchases of items shared between Brand and Retailer. This number is based on information received from one or more Retailers' connected Facebook Business Tools. The amount is attributed to your ads.

catalog_segment_actions

Similar to catalog_segment_value, but this metric aggregates actions for the catalog segment at each ad object level.

converted_product_value

Value of conversions driven by your ads for a given product ID. This number is recorded by your Retailer partner's Pixel or App SDK.


The API only returns Product IDs —see /{product-item-id} for information. If you want to get brand names as well, please use Ads Manager.

converted_product_quantity

Quantity of conversions driven by your ads for a given product ID. This number is recorded by your Retailer partner's Pixel or App SDK.


The API only returns Product IDs —see /{product-item-id} for information. If you want to get brand names as well, please use Ads Manager.

Breakdowns

Breakdowns are used to group your insights results into different sets —see Breakdowns. You can use following breakdowns with Collaborative Ads metrics:

  • Date: Get insights for a specific date range. To use this breakdown, add time_range to your query. For example: &time_range[since]=2020-03-01&time_range[until]=2020-04-01.

  • Product Level: Get insights for a specific product. Use this breakdown for converted_product_value and converted_product_quantity metrics by adding &action_breakdowns=action_converted_product_id to your query.

Combining Breakdowns

Use the following combining breakdowns for Collaborative Ads:

  • action_converted_product_id
  • action_type, action_converted_product_id