Catalog

Facebook Business Extension (v2) is currently only available to approved partners. If you are interested in becoming a partner, please contact your Facebook representative for access. FBE requires the manage_business_extension capability.

If you do not have a representative, please fill out this form if you are an eCommerce partner or this form (available on desktop only) if you are in the Services vertical.

The Facebook Business Extension (FBE), v2 uses Catalog to intake a business's inventory. It is used to power various features, such as dynamic ads, Page Shops, and Featured Services Card. It is an optional part of the integration, but is required for certain features.

The Facebook Catalog has its own suite of APIs, but FBE integrates with a few of them directly so you can easily update a business's inventory on our platform (without you needing to keep track of Facebook Catalog IDs on your end).

To ensure that all required fields are correctly populated in your catalog for dynamic ads and commerce use cases (Page Shop, Instagram Shopping, Marketplace), see Support Fields.

Update Inventory

To update inventory, there are 2 methods:

  • Push: Push catalog to Facebook via the API (recommended)
  • Pull: Have Facebook periodically Pull the catalog from your platform (discouraged as it leads to stale inventories and unnecessary server load)

Push Methods

We strongly recommend using one of the Push methods (Batch API or One-Time Feed Upload API) as it enables instant inventory updates and reduces server load on both ends. The access_token used here is the same one returned from Business Login and the Webhook.

You must send us a business's full inventory as soon as you receive a new installation Webhook. You need to send an update any time a business makes a change to their inventory on your website.

Batch API

Recommended for most ecommerce businesses. The Batch API is useful for businesses with large inventories (100+ items) and/or frequently updating items.

The Batch API is a standard Facebook Catalog API; however, when using it to update inventories for FBE, you can make POST requests to the following proxy endpoint (no Catalog ID needed):

https://graph.facebook.com/<API_VERSION>/fbe_catalog/batch?fbe_external_business_id=<YOUR_ID_FOR_THE_BUSINESS>&requests=<REQUESTS>

One-Time Feed Upload API

Recommended for most Services businesses. The One-Time Feed Upload API is useful for businesses with smaller inventories (~100 items or fewer).

With this method, you send a full inventory any time an update is made, which performs a full replace of the inventory in Facebook Catalog.

Using FBE Proxy (discouraged)

The One-Time Feed Upload API is a standard Facebook Catalog API; however, when using it to update inventories for FBE, you can make requests to the following proxy endpoint (no Feed ID needed):

https://graph.facebook.com/<API_VERSION>/fbe_catalog_feed/uploads

This FBE proxy endpoint fbe_catalog_feed/uploads will be deprecated, we recomend you to use One-Time Feed Upload API directly instead.

Example - Feed files hosted on a public location

curl \
  -F "fbe_external_business_id=<YOUR_ID_FOR_THE_BUSINESS>" \
  -F "url=http://www.example.com/sample_feed.xml" \
  -F "access_token=<ACCESS_TOKEN>" \
  https://graph.facebook.com/<API_VERSION>/fbe_catalog_feed/uploads

Example - Uploading feed files directly from the local machine. The path to the file needs to be changed according to your use case:

curl \
  -F "fbe_external_business_id=<YOUR_ID_FOR_THE_BUSINESS>" \
  -F "file=@catalog.csv;type=text/csv" \
  -F "access_token=<ACCESS_TOKEN>" \
  https://graph.facebook.com/<API_VERSION>/fbe_catalog_feed/uploads

Using One-Time Feed Upload API directly (recommended)


Step 1: Get Feed ID created during FBE installation by sending connected Catalog ID (from Webhook notifications or from our FBE installation API endpoint):

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

Learn more about Product Feed API.

Step 2: Perform one-time uploads to the feed

Example — Feed files hosted on a public location

Graph API Explorer
curl -X POST \
  -F 'url="http://www.example.com/sample_feed.xml"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{FEED_ID}/uploads
POST /{FEED_ID}/uploads HTTP/1.1
Host: graph.facebook.com

url=http%3A%2F%2Fwww.example.com%2Fsample_feed.xml
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{FEED_ID}/uploads',
    array (
      'url' => 'http://www.example.com/sample_feed.xml',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{FEED_ID}/uploads",
    "POST",
    {
        "url": "http:\/\/www.example.com\/sample_feed.xml"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Example — Uploading feed files directly from the local machine. The path to the file needs to be changed according to your use case.

Graph API Explorer
curl -X POST \
  -F 'file=@catalog.csv;type=text/csv' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{FEED_ID}/uploads
POST /{FEED_ID}/uploads HTTP/1.1
Host: graph.facebook.com

file=%40catalog.csv%3Btype%3Dtext%2Fcsv
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{FEED_ID}/uploads',
    array (
      'file' => '@catalog.csv;type=text/csv',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{FEED_ID}/uploads",
    "POST",
    {
        "file": "@catalog.csv;type=text\/csv"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Supported Formats

All request and response formats are otherwise the same as documented for the original endpoint.

Vertical Example CSV Feed Example TSV Feed Example XML Feed

ECOMMERCE

ECOMMERCE Sample CSV

ECOMMERCE Sample TSV

ECOMMERCE Sample XML

SERVICES

SERVICES Sample CSV

SERVICES Sample TSV

SERVICES Sample XML

See Services Catalog supported fields.

Pull Method

We discourage this method as it leads to stale inventories until subsequent pulls, but is useful for smaller, self-hosted businesses with a publicly accessible inventory file. If you choose to use this method for a business, you need to specify the catalog_feed_scheduled feature in Business Configuration, passed in via Business Login. When this is defined, we fetch the business's inventory from the specified public URL on a regular basis, irrespective of any updates.

Learn more about the Scheduled Feed Pull.