Onboarding

Onboarding via Redirect

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.

Use the setup steps outlined in this guide to onboard sellers.

Step 1. Set Up a Facebook Login Flow

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

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

See Permissions, Reference for more information.

Step 2. Find Authorized Pages and Commerce Accounts

  1. 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:
    2. 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 */
      }
    }
);
  2. Using the id of the page, find the associated business ID, Commerce Merchant Setting ID, and catalog IDs by making the following call:
    3. 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 4.

Step 3. Redirect to Commerce Manager

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

  1. Redirect seller to the URL as shown in the example below.

  2. Provide a redirect_url parameter and your app_id so Commerce Manager can send the seller back after setup is complete.

  3. Commerce Manager attaches 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's likely that the seller did not grant you access to the correct page or the new Commerce account. You can explain it and re-request permission.

Attribute Description

app_id

Type: string

Required

Platform Partner App ID

redirect_url

Type: string

Required

URL that Facebook redirects the seller to after onboarding is complete.

The redirect_url must match the base domain in your app. You can manage the base domain for your app via the Facebook App Dashboard under Settings > Basic.

A base domain should include the core domain and your top-level domain (for example, facebook.com, myshops.com, and so on).

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



Step 4. Authenticate Commerce Merchant Settings

Platform partners must establish ownership with seller shops to perform order management operations. After authenticating Commerce Merchant Settings (CMS), your app will have permissions to retrieve and modify orders.

Register Your App ID for a 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 unregister, contact your Facebook partnership liason. 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"
    }
}

Get Catalog and Page ID from 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 CMS.

GET 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"
}

Learn more about product catalogs and inventory syncing.

Establish an 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. It also allows access to your sellers' business assets, such as catalogs and pages.

Learn more about the Business On Behalf Of API.

Step 5. Manage Orders

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. You can use the Order Management API to move orders from the Facebook Commerce Platform into your service and manage their lifecycle.

Learn More