Overview

We encourage you to read this guide thoroughly and to integrate with as many elements of our Commerce APIs as possible; ideally with all of the ones relevant to your use case.

Developer Role Scope

As a developer, you most likely fit into one of these categories:

• Seller: You’re part of an ecommerce company that has its own custom technical stack, and want to integrate with Meta’s Commerce APIs to enable a single (or a handful of) Shops to operate on Meta’s technologies.

• Tech Provider/Partner: You’re part of an ecommerce platform company, or a company providing software services to existing ecommerce businesses, but doesn’t have a Shop by itself (collectively referred to as a commerce tech provider or partner), and you want to integrate with Meta’s Commerce APIs on behalf of the multiple shops supported by your platform.

In both categories, the quality of your integration will have a meaningful impact when your customers interact with products and Shops managed with our Commerce APIs. This guide is specifically focused on helping partner developers who want to:

• Integrate with our Commerce APIs.

• Get an overview and the “big picture” of all the elements that go into building a high-quality integration with Meta’s Commerce APIs.

• Learn how the integration can lead to positive business outcomes: find new customers, close more sales, and successfully leverage Meta’s ads to drive the same outcomes.

Buyer Role Considerations

Buyers have a very high bar when it comes to making purchase decisions. They seek rich information about the products they’re considering buying. They want a good deal, and expect to find the same discounts and promotions on a Shop as they find on the seller’s own website. They need timely updates about an order they’ve placed with accurate shipping, tracking, and returns information.

Providing all of these elements to Meta is key to improving buyer conversion rates with Shops.

High-Level Developer Flow

At Meta, we allow third party developers to build systems that integrate with our Instagram and Facebook platforms through a collection of Commerce API endpoints, collectively part of the Graph API. Here we describe the high-level developer flow and the components involved in building a high-quality Commerce API integration.

Prerequisites

• You must have a business setup and verified on Meta

• Required commerce contracts must be signed, including the Tech Provider Amendment and Supplemental Terms

• You must be familiar with the concepts of Graph API, which is the primary way for reading from and writing data to the Meta commerce platform

Step 1: Create a Developer App

To make requests to these Graph API endpoints, you first need to create an app in the Meta for Developers portal. In this context, an app represents a collection of capabilities that your third-party software is granted access to on Meta’s systems. Every API call you make to Meta’s systems is associated with this app and your capabilities determine which API calls your software has access to. This app is associated with your business entity on Meta. Meta’s data model is designed such that all of the assets you create to run your business on Meta are owned by this business entity object. This same business entity object that owns your app can also own your Facebook Page, Instagram account, ad account, and product catalog.

Step 2: Create Access Token (Using Test Account)

As part of the app approval process, you need to provide an access token with each call when making API calls. This access token allows your app to access Meta’s platforms on behalf of a user. Access tokens are the equivalent of digital keys that keep a user logged in to Facebook so they don’t need to re-enter their password every time your third-party software needs to access Meta’s platforms on behalf of that user.

As a partner developer who wants to build a commerce integration where you’ll manage multiple shops, you’ll be required to store multiple access tokens—one for each shop you support that’s selling on Facebook and Instagram channels.

To begin, create a test commerce account, associating the assets and generating a corresponding access token to be used for developing the commerce API integration.

Step 3: Build Commerce API Integrations (Using Test Account)

Begin integrating with the catalog, order management, and promotions (offers) APIs in parallel using the test commerce account created in step 2: Integrate with the catalog APIs to set up and operate a high-quality, up-to-date catalog that powers the purchase experience and influences the buying decisions. Integrate with the order management APIs to manage the life cycle of the orders placed by buyers on Facebook and Instagram channels. Integrate with the promotion APIs to synchronize different types of promotions and handle purchases and refunds in the presence of promotions.

Learn how to integrate with these APIs to meet our Shops quality bar.

Step 4: Submit App for Review

App Review is an integral part of the App Development process. You initiate an app review by requesting individual permissions and describing how the requested permissions will be used by your app to power the businesses you support. This process enables us to verify that your app uses our products and APIs in an approved manner. Learn more about the App Review process.

Step 5: Implement Flow for Onboarding Sellers onto Meta Commerce

Implement the best path for onboarding your sellers onto Meta Commerce. At the end of this flow, an access token is generated for each seller you support, which you need to store and use when making API calls on behalf of that seller.

Learn detailed instructions on how to create an ideal onboarding integration that meets our Shops quality bar.

Step 6: Refine Commerce API Integration (Using Production Account)

Refine your integration to handle the different edge case scenarios and to gracefully handle failures. Understand and adopt the recommended integration best practices outlined in the best practices guide. Finally, test your integration with real orders.

Integration Quality Bar

The table below lists the seller Jobs To be Done (JTBDs) grouped by different categories, their priority (0 being the highest), whether they are Meta-specific or applicable to other channels, the associated Meta Commerce integration quality bar requirements and potential enhancements.