Merchant Onboarding for Platforms

Platform partners can use the Facebook Commerce Manager to onboard merchants by utilizing a redirect URI to send merchants back to the platform after onboarding, along with a Commerce Merchant Settings (CMS) ID for the merchant.

Merchant Setup

1. Set Up a Facebook Login Flow

When implementing Facebook Login, be sure to request the following App Permissions:

2. Redirect to Commerce Manager

After a merchant logs in with Facebook they will be redirected to Commerce Manager to finish the onboarding process. Once the onboarding process is complete the merchant is redirected back to your platform. Provide a redirect_url parameter as well as your app_id to redirect the merchant. Use the provided cms_id Commerce Merchant Settings object along with our Commerce APIs to retrieve additional metadata about the merchant.

Attribute TypeDescription

app_id

Required

string

Platform Partner App ID

redirect_url

Required

string

The URL Facebook will redirect the merchant to after onboarding is complete. Note: The redirect_url must match the base domain in your app. The base domain for your app can be managed via the Facebook app dashboard under Settings > Basic.

A Base domain should include the core domain as well as your top-level domain (for example, facebook.com, myshops.com, etc)

Facebook Redirect URL Example

https://www.facebook.com/commerce_manager/onboarding?app_id={app-id}&redirect_url={redirect-url}

Redirect URL for Merchant

{redirect-url}?cms_id={commerce-merchant-settings-id}

Example experience

3. Authenticate Commerce Merchant Settings

Platform partners must establish ownership with merchant shops to perform Order Management operations. After completing this step, your app will have permissions to retrieve and modify orders.

1. Register your app ID for a Commerce Merchant Settings (CMS) object

POST Request

Graph API Explorer
curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{commerce_merchant_settings_id}/order_management_apps
POST /{commerce_merchant_settings_id}/order_management_apps HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{commerce_merchant_settings_id}/order_management_apps',
    array (),
    '{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(
    "/{commerce_merchant_settings_id}/order_management_apps",
    "POST",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Response

On success, your app receives the following:

{
    "success": true
}

If a CMS has already been registered by another app, it cannot be registered again. To de-register, please contact your partnership liason at Facebook. When an app is already registered:

{
  "error":
    {
        "message": "Fatal",
       "type": "OAuthException",
       "code": -1,
       "error_subcode": 2361126,
       "is_transient": false,
       "error_user_title": "Shop Already Has Authorized Order Management App",
       "error_user_msg": "Shop has already authorized an Application to manage its orders. Contact Facebook if you need to de-authorize the existing Application.",
       "fbtrace_id": "BzNm1CrkMKz"
    }
}

2. GET Catalog and Page ID from Commerce Merchant Settings (CMS)

Retrieve the merchant's catalog ID and Facebook Page ID from the CMS object and save it for later catalog API usage.

Request

Graph API Explorer
curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{commerce_merchant_settings_id}?fields=product_catalogs,merchant_page
GET /{commerce_merchant_settings_id}?fields=product_catalogs,merchant_page HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{commerce_merchant_settings_id}?fields=product_catalogs,merchant_page',
    '{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(
    "/{commerce_merchant_settings_id}?fields=product_catalogs,merchant_page",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Response

{
  "product_catalogs": {
    "data": [
      {
        "id": "10455456806199",
        "name": "Some ECommerce Platform Catalog"
      }
    ]
  },
  "merchant_page": {
    "id": "455786458954555",
    "name": "Merchant Shop"
  },
  "id": "38545478524704"
}

For more information about Product Catalogs and inventory syncing, please review our Product Catalog Documentation.

3. Establish an "On-behalf-of" (OBO) System User relationship.

The Business On-Behalf-Of API allows platforms to create a System User, and use the System User's access token, that exists inside the merchant's Business Manager and allows access to your merchants' Business assets such as Catalogs and Pages.

Learn more about the OBO API here.

Order Management

After a merchant has been successfully onboarded and their inventory has been uploaded to a Catalog on Facebook, their products are ready to be purchased by consumers. The Order Management API can be used to move orders from the Facebook Commerce Platform into your service and manage their lifecycle. See our Order Management documentation for more detail.