Seller Onboarding for Platforms

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

Seller Setup

1. Set Up a Facebook Login Flow

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

business_management
pages_read_engagement
catalog_management

If you were granted access to the Commerce API after Oct 20, 2020, you need to also request these permissions:

commerce_manage_accounts
commerce_account_manage_orders or commerce_account_read_orders
commerce_account_read_reports if you want to access the Finance Reporting API

2. Find Authorized Pages and Commerce Accounts

With the access token returned from Facebook Login, make the following call to get a list of Pages that the seller has authorized your app to access

Graph API Explorer

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/me/accounts?fields=access_token,name,id,tasks

GET /me/accounts?fields=access_token,name,id,tasks 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(
    '/me/accounts?fields=access_token,name,id,tasks',
    '{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(
    "/me/accounts?fields=access_token,name,id,tasks",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Using the id of the page, find the associated Business ID, Commerce Merchant Setting ID, and Catalog IDs by making the following call

Graph API Explorer

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{page-id}/?fields=business,commerce_merchant_settings{id,display_name,product_catalogs}

GET /{page-id}/?fields=business,commerce_merchant_settings{id,display_name,product_catalogs} 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(
    '/{page-id}/?fields=business,commerce_merchant_settings{id,display_name,product_catalogs}',
    '{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(
    "/{page-id}/?fields=business,commerce_merchant_settings{id,display_name,product_catalogs}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

If the seller wants to set up using one of the existing Pages and Commerce Accounts, skip the next step and go to Step 3.

2. Redirect to Commerce Manager

If the seller wishes to set up using a new Commerce Account, you need to direct them to Commerce Manager to create one.

Redirect seller to the URL as shown in the example below. Provide a redirect_url parameter as well as your app_id so Commerce Manager can send the seller back after setup is complete.
Commerce Manager will attach the ID of the newly created CommerceMerchantSettings object in the cms_id parameter when redirecting back to your platform.

If you get permission errors, it is likely because the seller did not grant you access to the right Page or the new Commerce Account. You can explain it and re-ask for permission.

Attribute Type Description

Attribute	Type	Description
`app_id` Required	`string`	Platform Partner App ID
`redirect_url` Required	`string`	The URL Facebook will redirect the seller 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)

app_id

Required

string

Platform Partner App ID

redirect_url

Required

string

The URL Facebook will redirect the seller 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)

Example Redirect URL to Commerce Manager

https://www.facebook.com/commerce_manager/onboarding?app_id=12345&redirect_url=https://www.example.com/

Redirect URL for Seller

https://www.example.com/?cms_id=112358

Example experience

3. Authenticate Commerce Merchant Settings

Platform partners must establish ownership with seller 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 seller's catalog ID and Facebook Page ID from the CMS object and save it for using with catalog API. Learn more about retrieving additional metadata from a Commerce Merchant Settings.

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 seller's Business Manager and allows access to your sellers' Business assets such as Catalogs and Pages.

Learn more about the OBO API here.

Order Management

After a seller 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.