API Integration Setup

Using the Graph API, you can integrate your Commerce Account with your e-commerce platform or OMS to programmatically:

API integration is optional. You can perform most catalog and orders tasks using the Catalog Manager and Commerce Manager self-serve UI.

If you're a large business, API integration is recommended.

The Order Management API is in a closed invite-only Beta program. Please work with your Facebook representative to get your app whitelisted if you have been invited to the program.

Businesses integrating with any Facebook product must have a developer app. You can create a new app or re-purpose an existing one.

You also need to create a System User that will allow your servers to make calls to the Graph API on behalf or your Facebook app. Before your app can make calls to read, update, or post to Commerce Account, you need to generate a Page Access Token used for API authentication.

Your app must be connected to your Commerce Account in Business Manager.

Follow these six steps:

  1. Create developer app
  2. Connect your app to your Business Manager
  3. Create system user
  4. Assign assets
  5. Generate page access token
  6. Connect App to Commerce Manager

1. Create Developer App

Go to the Facebook for developers page and click My Apps -> Create App.

Provide a name you want to associate with your app and a contact email used for communication about your app and click Create App ID.

After that the app will be created and you will be redirected to the App Dashboard page.

Copy the APP ID you will need it later for connecting your app to your business manager.

Once created, the app’s status will be In Development. For integration with Facebook Commerce Platform, the app does not have to be moved to the Live mode.

2. Connect your app to your Business Manager

To correctly connect the app, make sure you have an admin access to your organization’s Business Manager.

Navigate to Apps under Account in Business settings click Add and select Add an App

In a popup modal that appears insert the APP ID from the previous section and click Add App

Your app is now connected to your Business manager and you should see it in Business Settings under Accounts -> Apps

Please note that after adding a new App, you need to reload the page to see the App in your Business manager.

3. Create System User

System Users represent servers or software making API calls to assets, such as Catalog or Commerce Account owned or managed by Business Manager.

Before you can create a System User, your Business Manager must:

  • Have a real person as an admin user.
  • Own a Facebook app (see the previous step).

Facebook limits the number of system users per business manager based on your app's access level.

To create a system user, go to your Business Manager settings. Select Users → System Users and click Add. In the popup window, enter a user name and make sure to select the Regular System User role, then click Create System User.

After the system user has been created, the next step is to assign permissions to manage Page, Catalog, and App assets to the system user.

4. Assign Assets

On the system user settings page, click Assign Assets. In the popup window, select Pages under Asset Types. Search for the page connected to your Commerce Account and toggle the Manage Page permission under Admin Access.

Then switch to the Catalogs asset type, search for the catalog connected to your Commerce Account page and toggle the Manage Catalog permission under Admin Access.

Switch to the Apps asset type, search for the app you created on the previous steps and activate the App Developer permission. Click Save Changes.

You will see a confirmation that selected assets were added to the system user.

Finally, add your system user to the commerce account with the permission to manage orders. In your Business Settings go to Accounts → Commerce Accounts, select your commerce account and click Add People. In the popup window, find and select the system user and toggle the Manage Orders permission under Standard Access. Click Assign.

You will see a confirmation that selected system user was added to the Commerce Account.

5. Generate Page Access Token

Before you can generate a Page Access Token, you must first generate a System User Access Token.

Generate System User Access Token


From your Business Manager settings, Select Users → System Users. Choose a system user created on the previous steps and click on Generate New Token, then select your App. Make sure the manage_pages permission is checked. Check the ads_management permission if you plan to use Catalog API. Then click Generate Token.

The next screen will display the SYSTEM_USER_ACCESS_TOKEN. Copy and store this token in a secure location.


Generate Page Access Token


Generate a Page Access Token using SYSTEM_USER_ACCESS_TOKEN by calling:

GET https://graph.facebook.com/me/accounts?access_token=<SYSTEM_USER_ACCESS_TOKEN>

This request will list all Pages managed by the system user including the matching access_token. Example response:

{
   "data": [
      {
         "access_token": "<access token sanitized>",
         "category": "Retail Company",
         "category_list": [
            {
               "id": "2239",
               "name": "Retail Company"
            }
         ],
         "name": "Test_Shop_Page",
         "id": "<content sanitized>",
         "tasks": [
            "ANALYZE",
            "ADVERTISE",
            "MODERATE",
            "CREATE_CONTENT",
            "MANAGE"
         ]
      }
   ],
   "paging": {
      "cursors": {
         "before": "<content sanitized>",
         "after": "<content sanitized>"
      }
   }
}

Copy the access_token corresponding to the page linked with your Commerce Account, and store it in a secure location. You will use this page access token in all future Graph API requests to your Commerce Account.

Start with calling the commerce_orders API endpoint to list the details of the order that you placed in your shop on Facebook:

GET https://graph.facebook.com/<API-VERSION>/<PAGE-ID>/commerce_orders?state=IN_PROGRESS
  &access_token=<ACCESS_TOKEN>

6. Connect App to Commerce Manager

In order to manage orders via API, an App must first be associated with the Commerce Manager representing your shop. This action only needs to be performed once, and instructs the Commerce Platform to leave finalized orders in the CREATED state for you to acknowledge.

POST https://graph.facebook.com/vX.X/{cm-id}/order_management_apps?access_token=PAGE_ACCESS_TOKEN

Request

AttributeTypeDescription

cm-id

string

Commerce Manager ID for the page that you want to extract orders. You can find {cm-id} by logging into Facebook Commerce Manager and then select the page that you want to extract orders. You will be redirected to www.facebook.com/ commerce_manager/{cm-id}

Sample Response

{
    "success": true
}

The Graph API Explorer tool is helpful for making calls to the API.

Security Best Practices


Now that you have successfully generated System User tokens and Page Access tokens, check out our Security Best Practices section on how to store and manage your tokens securely.