Catalog

The Facebook Business Extension (FBE) 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.

Batch API

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

One-Time Feed Upload API

Available for Appointments (Services) businesses. The One-Time Feed Upload API is a standard Facebook Catalog 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.

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.

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.

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.

See Appointments (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.