Conversions API End-to-End Implementation

The Conversions API supports advertisers’ efforts to provide consumers with appropriate data transparency and control while also helping them to continue providing personal experiences. With the API, you can share data directly from your server, rather than through a browser.

Benefits of Integration

  • Deeper-Funnel Visibility: The Conversions API allows you to share a wider array of data when compared to the Facebook pixel. With the API, you can make decisions taking into account more information, such as CRM data, lower funnel events (including qualified leads), and multi-site conversion paths across a website and a physical location.

  • Data Control: When used via a Server-Only implementation (for example, without the Facebook Pixel), the Conversions API gives you added control over what data you share. You can choose to append insights to your events, providing data such as product margins or historical information, like customer value scores.

  • Signal Reliability and Resiliency: Data sharing through the Conversions API may be more reliable than browser-based methods alone, like the Facebook pixel. The API is designed to be less susceptible to issues like a browser crash or connectivity problems. New industry data transmission restrictions may limit the efficacy of cookies and pixel tracking, so the Conversions API helps you have control on sharing signals that may no longer be captured by the pixel.

Overview

You can think about your Conversions API integration in two main stages:

The following is a snapshot of the complete integration process:

RequirementsFull IntegrationOptimization

Select events to share with Facebook with user consent (if any).


Set up your business’ assets: Facebook Pixel, Facebook Application, Business Manager, Server Connection, System User.

Step 1: One event - Sending any event, manually or automated using the system user's token. Completing this step means you have correctly set up authentication.


Step 2: Fully Integrated - You need to be sending some automated events to be considered integrated. Completing this milestone means you are able to optimize for Conversions API even in the event that you stop using the pixel or the pixel is blocked.

Once you are fully integrated, send enough automated funnel events to be considered fully onboarded. Then, optimize your match rate based on guidance from Event Match Quality.


Make sure:

  • The events can be sent via either channel (browser or server) and it is not being double-counted.
  • The events are being sent as close to real-time as possible.
  • Provide customer information parameters to be used for identity matching.

Existing Pixel Users

If you have an existing Facebook pixel integration, the Conversion API integration should be built as an extension of the pixel integration, instead of as an entirely different connection.

General Consent

If you have logic for controlling consent with respect to sharing pixel data, use the same logic with respect to sharing data via Conversions API.

Alternatives

  • If you want to optimize your ads for app events, please use the App Events API.
  • If your events are store sales, please use the Offline Conversions API. Offline events that are not store sales are eligible for conversions API.

Preparation

Pick Your Integration Type

To start, select the integration option you would like to implement:

SetupApproach Description

Redundant Setup (Recommended)

Send all events via both pixel and Conversions API. This is the recommended setup for those who would like to keep the pixel on their website, and are able to fully adopt the Conversions API.


To succeed, you must be able to generate a persistent event_id for both pixel and Conversions API events. This means sending the same event_name and event_id on both the pixel and the Conversions API event, in order to deduplicate identical events.


This setup provides performance on par or better than using only the browser pixel. The server can capture events that may not be tracked by the browser, such as purchases that occur on a separate website, lead conversions, or phone calls.

Split Setup

Send different types of events via pixel and Conversions API. For example, you could send PageView and ViewContent via pixel, and Lead or Purchase via Conversions API.


While this option is not as optimal as a redundant setup, you may consider it if you do not want to use a fully redundant setup. Take into consideration that you may need to complete additional work as browser changes are implemented.

Server-Only Implementation

Only send events through the Conversions API, instead of through the browser. We recommend implementing either a redundant setup or a split setup before switching to this approach.

Define Events to Send

Once you have chosen your integration approach, you can define which events you want to send. Signals are most useful if they are matched to Facebook user IDs, so it is important to think through what parameters you are sending us with an event and how often you would like to send them.

Event Options

Send events that are most relevant to your business. See a full list of supported standard and custom Facebook events.

Event Parameters

You can send multiple parameters inside each event. See parameters used by Conversions API to learn more about those fields.

You can add multiple types of IDs to your events, including event_id, external_id and order_id. It’s important to know the difference between these parameters:

IDDescriptionHow It Is Used

External ID

Your unique ID for a specific customer.

Learn more about External ID.

Event ID

A unique ID for a given event.

Used on event deduplication. This field is very important if you are sending events via both browser pixel and conversions API.

Order ID

A unique ID for a given order. This parameter only works for purchase events and expects an order_id field in custom_data.

This implementation is limited to select Facebook partners. Contact your Facebook representative for access.


Used on purchase event deduplication, if you send events via both browser pixel and conversions API.


  • Once you sent us your first order, we discard the second one if:
  • You send a second event with the same order_id within a specific time window, and We resolve that the same user completed both orders.

You can deduplicate purchase events within two windows: 48 hours (recommended) or 28 days. This is the window between the first and second instances of the same event.

Data Freshness

We recommend that you send events in real time or in batches based on a specific timeline via the Conversions API. Sending your events in real time or within 1 hour helps ensure that they can be used for attribution and optimized for ad delivery.

Sending your events more than 2 hours after they occurred can cause a significant decrease in performance for ads optimized for those events. Events sent with a delay of 24 hours or more may experience significant issues with attribution and optimized ad delivery.

If you’re sending events with long conversion windows, send the event as close to real time as possible from the point at which the full conversion is completed.

Move on to the next step once you have:

  • A list of events to send.
  • The specific fields you want to send with each event.
  • Defined how frequently you will send events.

Available Optimization Types

The Conversions API offers the following optimization types:

Optimization OptionDescription

Conversions Optimization

Optimize ad delivery to show ads to people most likely to make a conversion.

Value Optimization (also known as Return on Ads Spend Optimization)

Optimize ad delivery to show ads to people most likely to make a conversion of a specified value, such as purchases over $50.

Dynamic Product Ads

Optimize ad delivery to show ads for specific products to people most likely to purchase those specific products.

Execution

There are two ways to implement your integration:

Advertisers using conversions API through one of our marketing partners should follow our partner’s implementation guidelines.

Direct Integration

Step 1: Set Up Requirements

Prior to using the Conversions API, set up the following assets:

AssetDescription

Facebook Pixel

When you send events through the Conversions API, they’re processed and stored in the same way as the events you send through your pixel. When you implement the Conversions API, you select which pixel you want to send your events to.


Sending your Conversions API events to a pixel lets you use your Conversions API events in the same way you use your browser-based pixel events for measurement, attribution, and ad delivery optimization. We recommend sending events from the browser and your server to the same Facebook pixel ID.

Business Manager

You need a Business Manager to use the API. Business Manager helps advertisers integrate Facebook marketing efforts across their business and with external partners. If you don't have a Business Manager, see the Help Center article on how to Create a Business Manager.

Access Token

To use the Conversions API, you need an access token. There are two ways of getting your access token:

Move on to Implement the API once you have the assets ready. Remember to save IDs for your assets, since you use those on your API calls.

Step 2: Implement the API

Once you are done with the requirements, start the implementation process. While building on the Conversions API, always check the developer documentation.

Test Calls (Optional)

If this is your first time using the API, start with a test call. To do that, you need a payload and a method for making API calls. After the call is completed, check Events Manager to verify the call worked as expected.

PayloadAPI Call Method

Use the Payload Helper to generate a sample payload to be sent with your call. Follow the instructions listed on the tool. Your payload should look something like this:

{
  "data": [
   {
    "event_name": "Purchase",
    "event_time": 1601673450,
    "user_data": {
      "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068",
      "ph": null
     },
    "custom_data": {
      "currency": "USD",
      "value": "142.52"
    }
   }
  ]
}

If you want to test your payload from the Payload Helper, add your pixel ID under Test this Payload and click on Send to Test Events. You should be able to see the event on Events Manager > Your Pixel > Test Events. Learn more about the Test Events Tool.

Once you are satisfied with your payload, decide how you want to make your call. You can use our Graph API Explorer (see Guide) or your own servers. If you are using your servers, you can use CURL or the Facebook SDK—We highly recommend using the SDK.


Independently on your call method, you should call the /{pixel_id}events endpoint and attach the JSON data generated by the Payload Helper. Once you make the call, you should get a response like this:

{
  "events_received": 1,
  "messages": [],
  "fbtrace_id": <FB-TRACE-ID>
}

After you complete your first call, verify your events on Events Manager > Your Pixel > Overview.

Move on to Send and Verify Events once you have checked your test events in Events Manager.

Send and Verify Events

To start sending events, make a POST request to the API’s /events edge. Attach a payload to your call —if you need help generating your payload, visit the Payload Helper. See the following resources for more information and code samples:

After you start sending events, go to Events Manager and confirm that we have received the events you sent. Learn how to Verify Your Events.

If your implementation is complementary to a browser Pixel, move on to deduplication settings. Otherwise, you are all set! Check Support if you still have questions.

Step 3: Add Parameters for Deduplication

If you’re sending identical events from your pixel and through the Conversions API, you need to set up deduplication for your events sent via both channels. First, read developer documentation to understand the deduplication logic.

Event-based deduplication

If we find the same server key combination (event_id, event_name) and browser key combination (eventID, event) sent to the same pixel ID within 48 hours, we discard the later sent duplicate events.

To help ensure your events are deduplicated:

  • For the corresponding events, make sure the following parameters are set to the same value:
    • event_id from your server event and eventID from your browser event
    • event_name from your server and browser events
  • After you send duplicate events, check Events Manager to see if the correct events are being dropped.
  • Ensure that each unique event sent via both pixel and Conversions API has its own event_id. This ID should not be shared with other events.

Alternative to event-based deduplication

While Event ID will always be the best way to deduplicate events, it's a fairly complex implementation. You can leverage alternative solutions by using external_id or fbp parameters. If you have configured the external_id or fbp parameters to be passed via both browser and server, we will deduplicate events automatically if we see the same event with same external_id or fbp parameters within 48 hours.

Optional Step 4: Explore Business SDK Features

The Facebook Business SDK has advanced features designed especially for Conversions API users:

  • Asynchronous Requests — Use this feature if you do not want to block your program’s execution to wait for a request to be completed. With this approach, you make your request and get a signal back from the server once it has been completed. While you wait for the response, the program can keep executing.
  • Concurrent Batching — Leverage asynchronous requests to increase throughput by utilizing resources more efficiently. Create batched requests to support use cases like event request workers, cron jobs, and more.
  • HTTP Service Interface — Override the Business SDK’s default HTTP service and implement your own custom service with your preferred method or library.

Integration as a Platform

The following instructions are for partners offering conversions API as a service to advertisers.

Step 1: Set Up Requirements

Your app should get the following features and permissions:

Step 2: Send Events on Behalf of Clients

First, follow the direct integration steps and test your integration. Then, you can request authorization to send events on behalf of your clients. You have the following authentication options:

Facebook Business Extension (FBE) Approach (Recommended)

FBE returns all the necessary information needed to send events on behalf of the client via the following process. FBE provides an endpoint to retrieve system user access tokens created in the client’s Business Manager. This process includes permissions to send server events and is done automatically and in a secured way.

The endpoint requires an user access token as input parameter. For new FBE users, call this endpoint the endpoint to fetch the system user access token after you finish setting up FBE. Existing users need to ask for re-authentication before calling the new API endpoint.

Facebook Business Extension (v2) is currently only available to approved partners. If you are interested in becoming a partner, please contact your Facebook representative for access. FBE requires the manage_business_extension capability.

If you do not have a representative, please fill out this form if you are an eCommerce partner or this form (available on desktop only) if you are in the Services vertical.

Client system user access token

Have your client manually create a System User Access Token via Conversions API inside the Pixel Settings. Then, send events to the advertiser’s Pixel with that token.

A system user or an admin system user must install the app that will be used to generate the access token. With this setup, your app is allowed to call APIs on behalf of this system user or admin system user.

Client shares Pixel to partner’s Business Manager

With this option, the client shares their Pixel to partner via Business Manager settings or via API, then you can assign the partner system user to the client pixel and you can generate an access token to send server events.

Step 3: Attribute Events to Your Platform

To attribute conversions API events to your platform, use the partner_agent field. This allows you to set your own platform identifier when sending events on behalf of a client. If you are a managed partner, work with your Facebook Representative to agree on an identifier for your platform. This value should be in a format that is less than 23 characters and includes at least two alphabetical characters. Then, send it with each server event.

Always provide an up-to-date setup guide for advertisers looking to activate the integration on your platform.

Support

For All Partners

See information about debugging and Business Help Center articles.

For Managed Partners

Provide the following information to your Facebook Representative, so they can help with testing integrations and troubleshooting: Business Manager ID, App ID, Pixel IDs.