Commerce Platform

API Integration Setup

The Commerce API is in a closed, invite-only Beta program. Please work with your Facebook representative to get access if you have been invited to the program. Commerce Test Account Access Form

Using the Commerce API, you can integrate your Commerce account with your inventory and order management system programmatically to manage products and inventory and orders.

Requirements

  • You must be an admin of your Business Manager.
  • Before you complete the App Review, your app can only access test commerce accounts.

Step 1: Create a Developer App

Go to Facebook for developers and click My Apps > Create App. You can also use an existing app.

Step 2: Create a System User

We recommend using access tokens backed by a system user to access the Commerce API. An access token obtained from a typical user can be invalidated after a period of time, or if that user changes their Facebook password.

  1. If you've not done so already, add your app to your Business Manager.

  2. Add system users to your Business Manager. You can also use an existing system user in your business.

Step 3: Assign Assets

Assign your system user admin access to the following assets in your Business Manager:

  • The app you use for the Commerce API
  • The test commerce account you created
  • The Facebook Page backing your test commerce account
  • The catalog connected to your test commerce account

You can only use the system user's access token can to access assets assigned to the system user. Once you set up your production commerce account, make sure that you also assign the system user to the relevant assets.

Step 4: Generate a System User Access Token

  1. On the Business Manager > System User page, click Add Assets and assign the system user as an admin of your app.

  2. Click Generate Token to generate an access token.

  3. Request the following permissions when you generate the access token:

    • pages_read_engagement needed for generating a Page Access Token later
    • catalog_management if you plan to use API to manage catalogs
    • business_management if you plan to use API to manage business assets

  4. Use the Access Token Debugger tool to verify that your access token has the required permissions.

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

  • commerce_manage_accounts or commerce_account_read_settings
  • commerce_account_manage_orders or commerce_account_read_orders
  • commerce_account_read_reports to access the Finance Reporting API

Before your app is approved by App Review, your app can only access a test commerce account, so make sure you generate a Page access token for the Facebook Page backing your test commerce account.

Step 5: Generate a Page Access Token

Every commerce account is backed by a Facebook Page. To access a commerce account through the API, you need a Page access token tied to that page. A Page access token is obtained from a User access token who is an admin of the Page.

Learn how to obtain a Page access token using the System User access token. This access token never expires, unless you invalidate it in Business Manager. Store this token securely and consider rotating it on a regular basis.

If you are a platform building an integration for your clients or sellers, you need to build a Facebook Login flow so that you can generate this access token on behalf of their pages. For a complete list of topics for platform integrations, see Platform Integration.

Step 6: Connect Your App to a Commerce Account

Make a one-time API call to connect your app to your test commerce account. You must first make this call to connect your app to any new Commerce account you want to manage with the app.

Step 7: Start Building

  1. Begin managing your orders placed in your test commerce account using the Order Management API.

  2. Once you demonstrate your integration on a test account, submit your app for App Review to manage a real commerce account.

  3. If you are a platform that builds integration for your sellers, you need to build an onboarding flow that automates steps 2 to 5 so that you can make API calls on the seller's behalf. Learn more about Platform Integration and Seller Onboarding.