Catalog Management Guide

It is essential that you provide sellers with a streamlined tool to sync their inventory between your platform and Facebook. This guide provides best practices on exporting products to sellers’ catalogs on Facebook and making sure these catalogs get attributed to your partner profile.

Overview

Before you start, we recommend that you learn about the following concepts:

Product catalogs: objects where sellers can store product information. Later, this information can be used in Advantage+ catalog ads and conversions tracking.
Feed: a set of items you upload from a seller so that a product catalog accurately reflects items available in inventory.
Product item: a single item in an online store, such as a SKU. You can have a single product feed represent all products in a catalog; or multiple product feeds where each feed represents a single country or division's products.

Get Started

New Feed Management partners focused exclusively on catalog management need to create an application on developers.facebook.com/apps before starting implementation.

Using the access token and catalog ID from your FBE or API integration, your app can export products from your platform to the seller’s product catalog on Facebook.

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

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

Regardless of your upload method, we require that your application set up an Enhanced Catalog. You can do that by providing a Product Category and at least one product field specific to the category.

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 FBE, 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.

Comparison	Batch Item API	Feed API	Notes
	Push updates in accordance with our specs when the underlying data changes.	Periodically generate a feed file with your products. Your plugin should create this file according to our developer specs.
Requires Use of Facebook APIs	Y	N (Optional)	While there are APIs for both Feed and Batch, it is possible to set up a scheduled feed pull using Facebook's Commerce Manager and not have to use our APIs.
Multi-platform Feed File	N	Y	Feed files can be generated in a standard format used by multiple platforms.
Near-real Time Synchronization	Y	N	The Feeds rely on Facebook pulling at scheduled times whereas the Batch APIs allow you to update your catalogs as soon as something changes.
Immediate Feedback for Errors	Y	N	If something goes wrong with your feed generation, the asynchronous nature of the pull method means you do not know there is a problem until some time later.
Requires Generation of Large Feed File	N	Y	The feed approach inherently requires the re-generation of the file when changes occur. Depending on the number of products managed, this may require a significant length of time and computation resources.

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 Facebook, 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 Facebook to associate catalogs using the uploaded feed to you, the partner. Without it, we are unable to accurately attribute feeds that you provide Facebook 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.

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.