Onboarding Integration

Onboarding to Shops is a necessary step to enable sellers to integrate into Meta Commerce. Seamless onboarding ensures that the seller’s products are up-to-date, order information is properly synchronized, easy to reconcile on a quarterly or annual basis, and banking and payout information are set up properly for timely payouts and reporting.

Requirements

You are required to integrate with the Facebook Business Extension (FBE) to meet our Shops integration quality bar by enabling sellers to:

• Easily discover the Meta integration in the platform
• Connect their 3P account to Meta assets (Business Manager, existing catalog where applicable, existing Pixel where applicable, Pages, Instagram Handles)
• Set up and edit their onsite Shop settings (Return Settings, Legal Info, Bank Account info, Tax Info)
• Link additional assets (Pages, Instagram Handles) to the shop
• Edit their settings
• Offboard

Before You Start

1. Integrate your verified business into FBE.
2. Add FBE to your app and gain access to the FBE Developer Panel. View this diagram to understand the FBE flow for Commerce.
3. Follow the FBE setup steps and then submit your integration for FBE Integration Review. This includes enabling the FBE feature management experience within your platform so businesses can change their features or even uninstall their FBE setup.

Requirement 1: Integrate with the Facebook Business Extension

The Facebook Business Extension (FBE) is a popup-based, Meta-owned interface that lives on third-party sites as a plugin and simplifies the overall integration process with Meta. FBE allows businesses to easily set up the Meta Pixel, Catalog, and Shops. It helps businesses connect their products and services with Facebook and Instagram channels on your platform. Once connected, you can help them utilize a large suite of powerful features.

In short, the separation of responsibilities in an FBE-based integration is as outlined below:

• Owned by Meta: Interface, authentication, connection and a surface [(FBE Management view)](FBE Feature Management View) to view connected assets, manage installed features, and status of commerce integrations
• Owned by Partner: Setup of pixel, inventory upload to the Facebook catalog via API

Once set up, any of your businesses can start an FBE onboarding flow either with existing assets or by having the option to create new ones, or a combination of both.

Step 1: Add Entry Points to FBE to Your App

Create entry points to FBE where the user selects, manages, or creates their assets (e.g. business, catalog, shops, pixel, etc.). These entry points can take one of these forms:

• Business Login (aka Facebook Login) – Allows businesses to initiate their connection from your platform using a button placed on your site.
• Business Apps – Allows businesses to initiate their connection from a Meta Surface. To enable this flow and have your app listed on Meta’s Business Apps, you must provide a custom authentication UI on your site. This UI must allow the user to select their business and then redirect them back to the Meta flow with the selected information.

Example

https://facebook.com/dialog/oauth?
client_id=<FB_APP_ID>
&display=page
&redirect_uri="https://partner-site.com/redirectlanding"
&response_type=token
&scope=manage_business_extension
//   additionally use catalog_management or ads_management
//   &scope=manage_business_extension,catalog_management,ads_management
&extras={
  "setup": {
    "external_business_id": "foo-123",
    "timezone": "America/Los_Angeles",
    "currency": "USD",
    "domain": "https://example-shop.partner-site.com/",
    "channel": "ECOMMERCE",
    "business_vertical": "ECOMMERCE"
  },
  "business_config": {
    "business": {
      "name": "Foo Business"
    },
    "catalog_feed_scheduled": {
      "enabled": true,
      "feed_url": "https://partner-site.com/feed-url"
    },
    "page_cta": {
      "enabled": true,
      "cta_button_text": "Shop Now",
      "cta_button_url": "https://partner-site.com/foo-business",
      "below_button_text": "Powered by FBE Partner"
    },
    "ig_cta": {
      "enabled": true,
      "cta_button_text": "Shop Now",
      "cta_button_url": "https://partner-site.com/foo-business"
    },
    "messenger_menu": {
      "enabled": true,
      "cta_button_text": "Shop Now",
      "cta_button_url": "https://partner-site.com/foo-business"
    }
  },
  "repeat": false
}

Depending on your setup of choice, you can get business’ access token for later steps in multiple ways:

• Business Login – As with a normal Facebook Login, the end of this flow returns an access_token, which you use to get more assets (e.g. Pixel ID, page ID, and Instagram Business ID)
• Business Apps – via Webhooks.

Step 2: Set Up FBE_install Webhooks

Webhooks are required for all partners which want to be listed in the App Store. If you don’t plan to have your app in the app store, then you can choose to ignore this section or revisit it later. Meta fires webhook events each time one of your businesses installs, modifies, or uninstalls FBE. Each time a webhook event is received, it’s expected that your app will consume this event and understand what assets the business has modified, added, or removed from their connection with your app. Your app’s behavior should update based on the most current connected assets. We highly recommend that you implement and test your subscription to our webhook.

To set up a webhook:

1. Create an endpoint on a secure server that can properly process requests from Meta.
2. In the App Dashboard, configure your FBE webhooks description:
1. In the FBE section > Webhooks tab, type your app’s callback URL.
2. Enter a verification token and then validate your endpoint.

After setup, the fbe_install webhook is automatically subscribed.

For more detailed steps, see Webhook.

Notifications

Upon receiving a webhook notification of an install, you need to:

1. Store the access token (and its type) and record the assets that your app has been granted access to.
2. Enable a set of features based on what assets have been granted.
3. If a required asset for a specific feature is missing, disable that feature only. For example, if your app has been granted access to a catalog, but not a pixel, only implement the catalog-powered feature, not the pixel-powered feature.
4. Inform the user with an update how your app is behaving based on what assets they have access to.

Upon receiving an update on an existing installation, you need to:

1. Update the access token and record of assets that have been granted to you.
2. Update the set of features your app will be enabled for the seller based on the assets that have been granted to the platform.
3. Inform the user with an update how your app is behaving based on what assets they have access to.

Upon receiving an uninstall notification, you need to:

1. Disable features that your app implements for the seller.
2. Inform the seller about the change to their configuration.

Step 3: Fetch Asset Details with the Returned Token

You can get information about businesses connected to your platform through FBE via one (or both) of the two following methods:

• Webhook—Required for all partners that want to be listed in the App Store. With a webhook setup, the details of businesses onboarding or editing via FBE will be received via the webhook payload from the webhook setup in Step 2.
• FBE Installs API endpoint—Recommended for self-hosted businesses. For any business that has installed FBE, you can query their basic installation information using the fbe_installs endpoint. Using a business’ access token and external business ID, you can call the FBE Installs API endpoint for detailed information about their setup.

Example: FBE Installs API Call

curl -i -X GET \   "https://graph.facebook.com/<version>/fbe_business/fbe_installs?fbe_external_business_id=<external business id>&access_token=<access token sanitized>"

Step 4: Fetch the System User Token

After a user installs FBE, the extension generates an employee system user on the client's Business Manager. Note that this system user is no longer visible in Business Manager, but exists on the backend. Naming for this new system user follows the schema {App Name} System User (FBE).

To do that, make the following API call:

curl -X POST \
  -F 'app_id={app_id}' \
  -F 'scope=ads_management,catalog_management,manage_business_extension' \ 
  -F 'access_token={user_access_token}' \
  -F 'fbe_external_business_id={fbe_external_business_id}' \ 
https://graph.facebook.com/<API_VERSION>/<client_business_manager_id>/access_token

For the scope field, use the manage_business_extension permission. Depending on your use case (see Step 5), the ads_management, catalog_management, pages_read_engagement, business_management, instagram_basic, and manage_business_extension permissions will likely also be needed.

• If your app needs to read and manage the Ads account of a business, request the ads_management permission. With this permission, you have the ability to create ads campaigns, fetch ad metrics, build ad management tools, and more.
• If your app needs to create, read, update, or delete business-owned product catalogs that a business is an admin of, you should request the catalog_management permission. We recommend this permission for all apps. This enables your app to build commerce-related, dynamic ads, and inventory management solutions.

Step 5: Set Up Management View

To allow businesses to further configure features (beyond what was specified in installation), you can direct businesses to our FBE Feature Management View from your platform. You can use the JavaScript SDK or URL to add an entry point to launch the FBE Management View. Both methods need to display a button to click, which launches the FBE Management View window.

Step 6: Add an Entry Point to Uninstall FBE

Your platform should add an entrypoint (e.g. button) for businesses to uninstall FBE. We recommend doing this by making a DELETE request to the proper endpoint.

Example: Call to our Deletion Endpoint

curl -X DELETE \
"https://graph.facebook.com/v<API_VERSION>/fbe_business/fbe_installs?fbe_external_business_id=<FBE_EXTERNAL_BUSINESS_ID>&access_token=<ACCESS_TOKEN>"

If you have implemented an fbe_install webhook, you will receive events when the user uninstalls FBE.

Learn More

• Facebook Business Extension (FBE)
• FBE setup steps
• FBE Developer Panel
• Uninstall FBE
• Webhooks