Commerce Platform

Plan Your Integration

Use this guide to learn about concepts and common use cases for planning your commerce integration. For platform-partner-specific integrations, see Commerce Integration for Platform Partners.

We recommend that you manage your business assets, such as your developer app, catalog, page and shop, Instagram account, under one Business Manager. For example, if you have an agency working on your catalog, you can still grant them access to work with the catalog on your behalf.

Security

We recommend to follow security best practices working with system users and access tokens. Access Token Debugger tool is helpful to see token details like expiration, type, app ID, and so on.

System users and access tokens are used for authentication of your servers or software making API calls to assets owned or managed by a Business Manager.

Manage System User Access Token Permissions

Multiple permissions are available for system users when generating an access token. Example permissions are: ads_management, business_management, manage_notifications, pages_read_engagement, and more.

Each permission allows your app to read, write information, or perform certain actions. You should restrict the access token permission scope by only assigning permissions that are required. For example, only 2 permissions are typically required for Instagram Shopping integration: manage_pages for Order Management API and ads_management for Catalog API (optional).

Once the system user has this permission, the system user access token can be used to retrieve the page access token.

Manage System User Tasks

A system user can have these task access levels for an asset like a page, ad account, or product catalog: ['MANAGE'], ['CREATE_CONTENT'], ['MODERATE'],['ADVERTISE'] and ['ANALYZE'].

The access type can be specified in the Business Manager settings.

You should restrict the page access type to ['CREATE_CONTENT'] for the Instagram Shopping integration.

Admin System Users vs System Users

System users represent servers or software making API calls to assets owned or managed by a Business Manager. The easiest, quickest way to create a System User is in the Business Manager tool.

There are 2 types of system users: admin system user and system user. An admin system user can create system users, assign permissions, and more. System user can only access the assets they have permission for.

Give system users access to assets and use system users for most API calls. You should limit using admin system user for administrative actions such as assigning permission. Since it has the most permissions, you should carefully safeguard the admin system user token.

Learn more about system users.

Safeguard Access Tokens

We recommend that you carefully safeguard the product system user and page access tokens. Store them in a secure location and do not share with anyone in plaintext.

You should not allow using a test page access token to call API for a production page. You can create two system users - one for test, and one for production.

Your app has a certain access level. This determines how many system users you can create for the Business Manager that owns your app:

Level System Users Admin System Users

Development

1

1

Basic

3

1

Standard

10

1

Rotate Access Tokens

It's a good practice to rotate system user access tokens periodically.

You may invalidate all access tokens of a system user by sending a DELETE request to the endpoint:

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

Manage Test Accounts, Access Token, and App Review

  1. Begin your integration development with a test commerce account. A test account allows you to create a Facebook shop only visible to your team, place test orders, and use API to manage those orders, without going through all the hassles of creating a real account.

  2. Once you have built out the basic functionality, submit your app for App Review. After App Review approves your app for commerce related permissions, your app can then be used to make API calls against a real commerce account.

  3. Set your Facebook or Instagram Shops in “Staging” mode in Commerce Manager where they are only visible to admins.

  4. Test your integration and buyer experience (end-to-end) before publishing those Shops.

Whether you are using a test account or real account, we recommend using a System User to generate access tokens for the API calls, as such tokens never expire. Treat these tokens as your password and store them securely.

Use Graph API Explorer to Test Requests

The Graph API Explorer is a helpful tool to perform Graph API queries and explore request fields and responses.

Use API Upgrade tool to change the version your app is using

The API Upgrade Tool shows the API calls from your app that may be affected by changes in newer versions of the API. You will be able to quickly see which changes you need to make to upgrade from your current version to a newer version.

Learn More