Commerce Integration for Platform Partners

Use this guide to learn about the comprehensive Facebook Commerce Integration process for platform partners who support sellers through onboarding and placing their first order.

FBE Common Use Cases

Missing Instagram Account

If you don’t have an Instagram account, but want to sell on Instagram, your account must satisfy our requirements. Unless sellers have an eligible account before starting FBE, they cannot onboard into Instagram Shopping. You can, however, add an Instagram channel later via the FBE management view, after the Instagram account is fully compliant with our Seller Access policies. Learn more about Instagram Shopping prerequisites.

Check Seller Status for Onsite or Offsite Commerce

  1. Pull the commerce account ID (merchant_settings_id) from the FBE installation details.
  2. Use the Commerce API status information cta field.

Check Seller’s Setup

To check if a seller set up a Facebook Shop or Instagram account:

  1. Pull the commerce account ID (merchant_settings_id) from the FBE installation details.
  2. Use the commerce merchant settings API facebook_channel field to see if sellers enabled Facebook channel. If the request does not return a channel ID, this means that the channel is not enabled.
  3. Use commerce merchant settings API instagram_channel field to see if sellers enabled the Instagram channel. If the request does not return a channel ID, this means that the channel is not enabled.

Verify Seller Setup

  1. Validate that the setup status is enabled: Check that shop_setup is SETUP in the commerce merchant settings API.

  2. Validate that integrity status is enabled. Use our commerce webhook to monitor commerce account status changes. For example, to see if sellers enable new channels, make changes Checkout on Facebook/Instagram to Checkout on another website or vice versa, complete the setup, pass our integrity review, and so on.

  3. Validate that Instagram Shopping is approved if a seller selected Instagram Shopping channel: Check that the status is APPROVED in the FBE installation details API.

Change an Integration

To change an integration if a seller’s setup changes, we recommend these actions:

FBE Management ActionsPlatform Actions

Add or remove distribution channel

Shop changes in UI

Offsite upgraded to onsite

Shop changes in UI. When Shop is fully set up, start listening for orders.

Onsite downgrade to offsite

Shop changes in UI. Pull orders for another hour. Fulfill/cancel/refund orders for another 30 days.

Delete Shop

Shop changes in UI. Stop listening for orders 60 minutes after the event.

Get Help with FBE Setup

Both FBE click-through and FBE management view have visible Help Center links and “Get help” forms that are directed to Facebook support teams. For any issues with setup, ask sellers to use these links to get help with installation.

Re-onboard Sellers

To re-onboard sellers from another platform or from self-serve:

  1. The seller must request to disconnect from another platform support to avoid conflicts when updating product, orders, or settings.

  2. After the seller has disconnected from another third-party platform, they can go through the same FBE click-through flow to configure the setup and grant you permissions to manage the commerce account.

Disconnect or Delete an Integration

To disconnect your integration from the seller setup, it is enough to uninstall FBE. That would not change the commerce account details, except removing permission for your platform to manage the seller commerce account.

To delete the integration, the seller can use FBE management view Delete functionality.

Commerce Merchant Settings

During the onboarding process via FBE, sellers follow a series of steps to select and create assets (such as Page, catalog, business, and so on), input payment details for payouts, set shipping preferences, and so on.

Once onboarding steps are complete, a Commerce Merchant Settings (CMS) account is created. This CMS is used to fetch all the details required, such as page ID, catalog ID, and so on.

Catalog Integration

As a platform partner, you must upload all the products of a seller to Facebook to help build Shops. Use these guidelines to integrate your catalog successfully. Learn more about our best practices for a commerce catalog and best practices for managing your inventory.

Create a Seller’s Catalog for a Seller by Platform

During the onboarding process, the seller selects or creates a catalog. You can fetch the catalog ID from the page ID or CMS ID:

From the page ID:

curl -i -X GET \


From the CMS ID:

curl -i -X GET \
"{CMS_ID}/product_catalogs?access_token={USER _ACCESS_TOKEN}"


Upload Products to Facebook

There are multiple ways to populate your catalog. The most common approach is to list all your products and attributes into a flat file using one of the supported formats (CSV, TSV, RSS XML, ATOM XML), and upload it as a catalog feed. Learn more about how to upload your inventory.

Display the Status of Product Uploads to Sellers

Learn how to handle product feed upload errors.

Update Products to Facebook

There are two modes of updates depending on use case:

  • Scheduled Feed Update: We recommend that you sync products every 15 minutes with all updates. This recommendation helps sync any new products added, updates made to a product by adding images, descriptions, and so on. Learn how to perform a one-time direct upload.

  • Real-Time Update: For frequent updates, such as inventory or price, we recommend to use the batch API to prevent overselling.

Adopt an Inventory Allocation Strategy for High Heat Products, Product Launches (Drops)

To support your sellers from overselling, we strongly recommend to provide inventory specific to Facebook/Instagram, and not combining with other channels, such as websites, and so on. Sellers should have an option to allocate inventory per channel if they choose to. Learn more about best practices.

Integrate Fields in the Seller's Catalog

Catalog fields are instrumental to the quality of the experience for customers buying products on your Facebook Shop or Instagram Shopping channels. Learn more about how to use catalog fields, the universal basic attributes, and the supported feed formats. See also category-specific fields and supported catalog fields.

Order Management Integration

After a seller has been successfully onboarded and their inventory has been uploaded to Facebook, their products are ready to be purchased by consumers. Learn more about order management.

Frequency to Sync Orders

We recommend that you read orders every 5 minutes and acknowledge them. Once you acknowledge and create an order in your platform, immediately update us with the merchant_order_reference via the Acknowledgement API.

Inventory Recommendation

If your inventory is zero (0) when you sync an order, we recommend: Acknowledge the order and have negative inventory for seller to take action on your platform. If you don't support negative inventory, issue a cancel request for these orders.

Sync Canceled Orders from Facebook

If a seller doesn't ship the product within a specified service-level agreement (SLA), Facebook cancels the orders automatically. We recommend that you sync these orders immediately to prevent sellers from accidentally shipping these orders. Once an order is canceled by Facebook, no further action can be taken on orders, such as shipping.

Learn more about best practices for orders, shipping and fulfillment, and post-purchase customer experience.