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 Meta 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 Meta 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 Meta 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:

• Preparation — Select which type of integration makes sense for you, define which events to send, and review available optimization options.

• Execution — Learn how to implement the API. For this stage, you can also use a partner integration.

The following is a snapshot of the complete integration process:

Existing Pixel Users

If you have an existing Meta 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.

Preparation

Pick Your Integration Type

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

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 Meta 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 Meta 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:

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:

Execution

There are two ways to implement your integration:

• Direct Integration — You, as an advertiser, directly implement conversions API.
• Integration as a Platform — You, as a marketing partner, offer conversions API as a service to your clients.

Direct Integration

Step 1: Set Up Requirements

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

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.

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

{
  "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:

• Using the API > Send requests
• Dropped Events
• Upload Time versus Event Transaction Time
• Batch Requests
• Hashing

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 Meta 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:

• Access Level: Advanced Access
• Feature: Ads Management Standard Access
• Permissions: ads_management and pages_read_engagement and ads_read.

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:

Meta Business Extension Approach (Recommended)

Meta Business Extension returns all the necessary information needed to send events on behalf of the client via the following process. Meta Business Extension 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 Meta Business Extension users, call this endpoint the endpoint to fetch the system user access token after you finish setting up Meta Business Extension. Existing users need to ask for re-authentication before calling the new API endpoint.

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 Meta 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.

Support

For All Partners

See information about debugging and Business Help Center articles.

For Managed Partners

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

API Documentation

• Get started - Test the API from your own Business Manager
• Using the API
• Best Practices - Conversions API
• Set Up Conversions API as a Platform
• Standard Meta Events
• Custom Meta Events
• Parameters
• Payload Helper
• Data Processing Options for Conversions API and Offline Conversions API
• If you want to optimize for app events, use App Event API