Feed Management Guide

If you are a feed partner, you need to build two core components for a complete Facebook catalog integration: Seller Onboarding and Catalog Sync Method. This guides contains the steps to implement both components and test your integration.

Integration Types

Before you start building, there are two decisions you need to make:

• How do you want to onboard the seller onto Facebook?
• How do you want to sync the catalogs to Facebook?

To help you answer those questions, we have listed 3 types of integrations you can choose from:

Lite

With a Lite integration, the entire onboarding and syncing process is done by Facebook. The only piece you build is the catalog feed file generation. Once a feed file URL is created, the user must go to the native Facebook UIs and set the feed file to be synced with their catalog.

Basic

With a Basic integration, there are two options available for handling seller onboarding:

• Ask the user to go to Facebook and create their assets. Then, have the user paste their catalog ID into your interface.
• Build a business asset creation UI within your interface using Facebook’s APIs.

As a partner, you must build the Catalog Sync Method using our APIs. The catalog syncing mechanism is handled without any seller action on Facebook’s native interfaces.

For a Basic integration, you also need to implement the Facebook Login to fetch a user’s OAuth access token, which is needed for API calls.

Premium

With a Premium experience, both the seller’s onboarding and the catalog syncing happens in your interfaces. The seller does not need to use Facebook’s interfaces. This approach can be achieved by leveraging the Meta Business Extension (MBE). The extension:

• Handles the OAuth Authentication/Authorization for you.
• Handles Business Asset selection for the seller.
• Returns an access token already assigned to all the assets the seller selected within the FBE user flow.

This is the recommended option for a long term scaled integration.

Comparison

A high level comparison of the three types of integrations for Feed Partners:

Pre-requisites

You need to perform a few steps before starting the development work. The required steps change depending on your integration choice.

Lite

There are no pre-requisites for this option. A Lite experience relies on Facebook UI tools and implies minimal development effort on your side.

Basic

You need to set up a Meta App and request the required permissions.

The first step in establishing a Basic integration is to create an application on developers.facebook.com/apps. You need the app ID for API integration points. Once you have an app, start building your integration in development mode --note the toggle at the top of the app dashboard. While in development mode, your application is able to authenticate developers and admins of the application and perform actions with assets they own.

After your integration is complete, request required production permissions via the App Review process. Acquiring such permissions allows your app to serve users other than your app’s admins and/or developers. Refer to the following documentation for the details on App Development Cycle. To manage business assets (such as catalogs), we recommend that your app requests these permissions: business_management and ads_management or catalog_management.

Premium

In terms of pre-requisites, this option is similar to the Basic integration. However, it does imply several specific steps. Refer to Meta Business Extension Guide for details on MBE integration pre-requisites.

Implementation

Step 1: Seller Onboarding

You can build two types of seller onboarding experiences:

1. Build a seller onboarding experience within your interface using Facebook’s APIs.
2. Leverage FBE to offload the onboarding to Facebook.

Onboarding Flow for Lite and Basic

For Lite and Basic options, advise your users to follow these steps to create a Catalog and related business assets. Then, provide the user with a Feed URL they can attach to their catalog via Facebook UI tools.

For a Basic integration, you also need a way for a user to authenticate themselves against your application. Authentication also allows you to acquire the access token required for Catalog API calls. We recommend that you use the Facebook Login. An alternative is to implement the OAuth flow directly.

At this point, an access token is enough for the API work. Additionally, we recommend that you consider setting up a Business Manager System User to manage assets on behalf of your sellers. A system user is a type of user designed specifically for marketing automation and it allows you to generate a system user access token. The major benefit of this is that your access to assets is no longer predicated on the initial user’s access. If you only have a user access token, your access to assets can be revoked if that specific user is no longer employed by the seller.

Optionally, your app can leverage the On Behalf Of API to programmatically enable access to users' assets for your System User. Learn more about access tokens and authentication.

Onboarding Flow for Premium (MBE)

We recommend onboarding sellers via Meta Business Extension (MBE). MBE is a pop-up based solution, that allows sellers to select or create the aforementioned assets. With MBE:

• Asset IDs and access tokens are returned to you via web hooks and/or API
• You are privy to access tokens and asset IDs, as a partner. This way, you can assist seller with pixel and catalog management, as well as commerce integration.

Please refer to the Meta Business Extension Guide for details on implementation.

Step 2: Catalog Syncing

There are two ways you can chose to sync catalogs to Meta:

• Upload a feed file so Meta can pull data from that URL.
• Push the catalogs to Meta via the APIs.

Sync Via Feed Upload (Pull)

For Lite use cases, you need to provide users with the URL where you are hosting their feed. Then, the users can attach the feed to their catalog following these steps.

For a Basic integration, you can attach the feed URL to a user’s Catalog via Feed API. You also have the option to programmatically acquire the catalog following the API calls outlined in the Sync via APIs (Push) section below.

Sync via APIs (Push)

Create Or Get Catalog

FBE simplifies the integration by providing you with Catalog ID and the access token via Webhooks and API.

If you are not using MBE, you need to get the catalog ID directly from the user. Your app can verify if the user has an existing catalog with the following API calls.

First, check the Business Manager ID the user has ADMIN access to. This is also the business hosting the catalog.

curl -G \
  -d 'fields="permitted_roles"' \
  -d 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/<API_VERSION>/<USER_ID>/businesses'

The response should look like this:

{
    "data": [
        {
            "id": "<BUSINESS_ID>",
            "permitted_roles": ["ADMIN"]
        },
        {
            "id": "<BUSINESS_ID>",
            "permitted_roles": ["ADMIN"]
         }
     ]
}

Once you have the Business Manager ID, you can get their catalog ID:

curl -G \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/owned_product_catalogs"

Product Import

As a best practice, we recommend that your application enables sellers to export products from your platform to Facebook via:

• Bulk updates: Catalog Items Batch API for updating multiple products in bulk.
• Updating individual products: For updates to individual products your app can send POST requests to the Product Item node. This approach is not suitable for updating the information on large number of products.

We recommend setting up the Catalog Items Batch API. This way, you can use the “push” method to proactively send real time (or close to real time) updates to catalog content via the API. This approach ensures that the inventory is synchronized between the platforms.

In case you are unable to invest in implementing the Catalog Items Batch API, we recommend Feed API as an interim integration option.

It is imperative that content served through Facebook Marketing Partners applications adhere to our Commerce and Advertising policies. We take policy violations very seriously and act quickly to ensure that partners continue to represent our program’s standards. To improve the rejection rate for catalogs managed via your application, we recommend communicating the aforementioned Facebook policies to users along with the following Facebook Blueprint Course.

You can verify the current state of product catalogs served by your app by comparing the number of rejected products against the total number of products in the catalog. To do that, use the following API call:

curl -G \
  -d 'fields="review_status"' \
  -d 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/<VERSION>/<PRODUCT_CATALOG>/products'

Your response should look like this:

"data": [
    {
        "review_status": "approved",
        "id": "<product_item_id>"
    },
    {
        "review_status": "rejected",
        "id": "<product_item_id>"
    }
]

The review status gets updated once products become eligible for delivery on the Facebook platform. Thus, the status may remain without changes upon product creation or update.

Learn how to Set Up Country and Language Feeds via the API and Set up a catalog for multiple languages and countries, Ads Help Center. Find more details on Catalog Management Best Practices in this section of the documentation.

New Vs Existing Catalogs

For catalogs that already have product data, you should first check the content of the catalog by sending the following API calls:

curl -G 
\-d 'fields=["category","name","retailer_id"]' 
\-d 'filter={"name":{"i_contains":"shoe"}}' 
\-d 'summary=true' 
\-d 'access_token=<ACCESS_TOKEN>'
https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/products

Once you have the product data from the catalog, you can update product info with additional fields and send them back to catalog. It is important that when doing so you do not overwrite essential product identifiers such as retailer_id.

Set Up Attribution

As a requirement to partnering with Meta, we must be able to internally attribute the product catalogs that inventory feeds partners are providing on behalf of their advertisers. All feed partners must use the Marketing API or implement the meta tag below for all XML, CSV, and TSV inventory files uploaded to Facebook.

API Instructions

Attribution happens automatically based on your app ID when you update products in catalogs with the Marketing API.

Meta Tag

If you manage your users’ catalogs via file uploads, include the following two elements as space delimited comments at the top of TSV/CSV feeds or inside a metadata tag in your XML feeds:

• ref_application_id: Your Facebook app ID
• ref_asset_id: ID that uniquely identifies this catalog in your system.

The tag allows Meta to associate catalogs using the uploaded feed to you, the partner. Without it, we are unable to accurately attribute feeds that you provide Meta to revenue generated by inventory-based use cases, like Advantage+ catalog ads.

As we build out a badging program for feed partners, it is crucial that the revenue you are enable is fully recognized. This method ensures recognition for feeds uploaded both via Ads Manager and the API, and enables our team to best support inventory management partners like you.

For full details, including sample feed files containing meta tags, see the Set Meta Tag in Product Feed File section of the Metadata Tag Setup API Documentation.

Step 3: Testing

Once you have started sending us catalog data, you can check if there are any problems in the Commerce Manager. To do that, visit Commerce Manager’s Issues page to see which items are missing categories or required fields. This allows you to identify which items are, and which are not, ready to be used in shops.

If you’re using the push APIs, the response from the API provides warnings as to which fields, if any, are missing or invalid.

You also want to know that your metadata tags are valid and that catalogs you make available via feeds are being correctly attributed to you. For the moment, the best way to do this is to email your Partner Manager to ask them to check after you have added the tags.