What Is Meta CAPI?

Meta (formerly Facebook) is a global technology company that builds products and platforms to help people connect and share across its family of apps, including Facebook and Instagram. Its advertising ecosystem supports businesses in reaching targeted audiences through data-driven marketing tools.

Meta Conversions API (CAPI) is a server-side API that enables advertisers to send web and offline events directly from their servers to Meta. It complements or replaces pixel-based tracking by reducing browser limitations and supporting user privacy protections. It helps advertisers maintain conversion tracking, audience targeting, and optimization capabilities when client-side collection is limited.

Product Type: Advertising
Integration Type: Starter Kit & ID Sync
Event Source Type: Web, Mobile Web, and Mobile App
Event Scope: Full-Funnel Events

Capabilities

Sends server-side conversion and commerce lifecycle events to Meta Conversions API.
Supports key matching and attribution identifiers via Meta Tag ID sync (_fbp, _fbc).

Considerations

The Meta Tag sync is required to populate fbc and fbp values in events.
Supports event batching (default batch size is 10; Meta accepts up to 1,000 events per batch, but rejects the entire batch if any event in the batch is invalid).
The event_id and event_name parameters are used to deduplicate events.
The starter kit automatically identifies MetaRouter as the sending partner by setting the partner_agent field to metarouter on all outgoing events.

Identity Sync

Sync Available: Yes
Required for Starter Kit: Highly recommended for user matching
Prerequisites: Pixel (Dataset) ID
Documentation: See Additional Meta Tag Sync Documentation

Sync Details

The sync fires a match pixel using the Tag ID and hashed Match ID.
Explicit cookies _fbp and _fbc are set to persist identifiers for 90 days.
A sync completion marker (*_facebookTag_sync) is stored to suppress duplicate pixel fires.
Extra tag IDs, if provided, trigger additional pixels with unique sync markers.
Identifiers are added to server-side payloads for ad targeting and campaign measurement.

Starter Kit Setup Guide

1. Deploy the Meta Tag Sync

To collect the required sync values (_fbp, _fbc), you must implement the Meta Tag sync in your web pipeline. Refer to the Meta Tag sync documentation to complete the setup. See Additional Meta Tag Sync Documentation.

2. Gather Credentials

Finding your Pixel (Dataset) ID:
1. Go to Meta Events Manager
2. Go to Data Sources
3. Click on Pixel
4. Click on Settings to find Pixel ID (it can also appear as Dataset ID)
[]
1. Generating an access token:
  1. Using Business Manager (recommended)
    1. Choose Pixel you want to implement
    2. Select the Settings Tab
    3. Find the Conversions API section and click on the Generate Access Token link under Set up direct integration and follow the instructions on the pop-up
      1. NOTE: Only visible to users with developer privileges for the business
      []
    4. Save your access token in a secure place.
2. Ensuring Conversions API is enabled in your account
  1. Click on the Manage Integrations button in the Overview tab in Events Manager.
  2. In the pop-up screen, check if you have the Conversions API set up and active. If not, click on Add New Integration > Conversions API > Set up. There is no need to go through App Review or request any permissions.

3. Add a Meta CAPI Integration

From the integration library, add a Meta CAPI integration. Then, fill out the Connection Parameters:

Connection Parameter	Description
`API_VERSION`	Meta Graph API version (default: `v24.0`).
`PIXEL_ID`	Meta Pixel ID (may appear as Dataset ID).
`ACCESS_TOKEN`	Conversions API access token from Events Manager.

4. Configure Event Mapping

MetaRouter provides all of the event mappings that Meta CAPI integrations typically require. You may add custom events, parameters, or mappings in accordance with Metas API documentation.

5. Deploy to Pipeline

In the Pipelines tab, add your Meta CAPI integration.

Event Mappings

Global

Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.

Output Key	Description	Expected Input
`action_source` Required	String: Identifies where the conversion occurred (for example, website or app).	Expression Sets `'app'` for iOS/Android, defaults to `'website'`
`event_time` Required	Timestamp: Unix timestamp (seconds) when the actual event occurred.	Expression Converts `timestamp` / `originalTimestamp` / `sentAt` to seconds since epoch
`event_source_url` Required	String: Website URL where the event occurred.	`context.page.url`
`event_id`	String: Unique ID used for deduplication when paired with `event_name`.	`messageId`
`user_data.em`	String: SHA256 hash of normalized email address.	Expression SHA256 hash of `input.traits.email`
`user_data.client_ip_address` Required	String: Client IP address (do not hash).	`context.ip`
`user_data.client_user_agent` Required	String: Client browser user agent (do not hash).	`context.userAgent`
`user_data.external_id`	String: External identifier for the user (SHA256 hashing used in this kit).	`anonymousId` (then `sha256`)
`user_data.fbc`	String: Facebook click ID (do not hash).	`context.providers.facebookTag._fbc`
`user_data.fbp`	String: Facebook browser ID (do not hash).	`context.providers.facebookTag._fbp`
`app_data.advertiser_tracking_enabled`	Boolean: Indicates whether advertiser tracking is enabled on the device.	`context.device.adTrackingEnabled`
`app_data.application_tracking_enabled`	Boolean: Indicates whether application tracking is enabled on the device.	`context.device.adTrackingEnabled`
`app_data.extinfo`	Array: Extended device and app information for app events.	Expression Derived from `context` (app/os/device/screen/network/timezone)

Event Specific

Page

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment Static value `'PageView'`
`custom_data.content_category`	String: The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	String: The name of the page associated with the event.	`properties.name`

Products Searched

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment Static value `'Search'`
`custom_data.search_string`	String: Search query made by the user.	`properties.query`

Product Viewed

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment Static value `'ViewContent'`
`custom_data.content_type`	String: Type of content.	Enrichment Static value `'product'`
`custom_data.content_category`	String: The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	String: The name of the page or product associated with the event.	`properties.name`
`custom_data.content_ids`	Array: Content IDs associated with the event.	Expression Returns an array containing `properties.product_id`
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression `price * (quantity or 1)`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression Derived from `properties.product_id`, `properties.quantity`, `properties.price`

Product List Viewed

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment Static value `'ViewContent'`
`custom_data.content_type`	String: Type of content.	Enrichment Static value `'product'`
`custom_data.content_category`	String: The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	String: The name of the list associated with the event.	`properties.list_id`
`custom_data.content_ids`	Array: Content IDs associated with the event.	`properties.products` (pluck `product_id`)
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression Sum of `price * (quantity or 1)` across `properties.products[]`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression Derived from `properties.products[]`

Product Added

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment Static value `'AddToCart'`
`custom_data.content_type`	String: Type of content.	Enrichment Static value `'product'`
`custom_data.content_category`	String: The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	String: The name of the page or product associated with the event.	`properties.name`
`custom_data.content_ids`	Array: Content IDs associated with the event.	Expression Returns an array containing `properties.product_id`
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression `price * (quantity or 1)`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression Derived from `properties.product_id`, `properties.quantity`, `properties.price`

Cart Viewed

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment Static value `'ViewContent'`
`custom_data.content_type`	String: Type of content.	Enrichment Static value `'product'`
`custom_data.content_ids`	Array: Content IDs associated with the event.	`properties.products` (pluck `product_id`)
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression Sum of `price * (quantity or 1)` across `properties.products[]`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression Derived from `properties.products[]`

Checkout Started

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment Static value `'InitiateCheckout'`
`custom_data.content_ids`	Array: Content IDs associated with the event.	`properties.products` (pluck `product_id`)
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression Sum of `price * (quantity or 1)` across `properties.products[]`
`custom_data.num_items`	Integer: Total number of items in the checkout.	Expression Sum of `(quantity or 1)` across `properties.products[]`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression Derived from `properties.products[]`
`custom_data.order_id`	String: Unique order ID.	`properties.order_id`

Payment Info Entered

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment Static value `'AddPaymentInfo'`
`custom_data.order_id`	String: Unique ID associated with the order.	`properties.order_id`
`custom_data.content_ids`	Object: Contains `checkout_id` and `order_id`.	Expression Returns `{ checkout_id=properties.checkout_id, order_id=properties.order_id }`

Product Added To Wishlist

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment Static value `'AddToWishlist'`
`custom_data.content_category`	String: The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	String: The name of the page or product associated with the event.	`properties.name`
`custom_data.content_ids`	String: Content ID associated with the event.	`properties.product_id`
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression `price * (quantity or 1)`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression Derived from `properties.product_id`, `properties.quantity`, `properties.price`

Order Completed

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment Static value `'Purchase'`
`custom_data.content_type`	String: Type of content.	Enrichment Static value `'product'`
`custom_data.content_ids`	Array: Content IDs associated with the event.	`properties.products` (pluck `product_id`)
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression Sum of `price * (quantity or 1)` across `properties.products[]`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression Derived from `properties.products[]`
`custom_data.order_id`	String: The order ID for this transaction as a string.	`properties.order_id`

Required & Recommended Identifiers

These identifiers must be mapped to Meta CAPI in order for successful user matching to occur. Without these IDs, any events sent to Meta CAPI may not be accurately reflected in reporting.

Attribute	Example	Sync Injector Required?
`client_user_agent` Required	`Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0`	No
`client_ip_address` Required	IPV4: `168.212.226.204` IPV6: `2001:0db8:85a3:0000:0000:8a2e:0370:7334`	No
`external_id` Recommended	`402DA762-201E-42C1-961B-C1fA6CBCF566`	No
`fbc` Highly Recommended	`fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890`	Yes
`fbp` Highly Recommended	`fb.1.1596403881668.1116446470`	Yes
`em` Recommended	`542d240129883c019e106e3b1b2d3f3cb3537c43c425364de8e951d5a3083345`	No

Integration Validation

Validate your Meta CAPI implementation by following Metas official verification steps in Events Manager:

Meta CAPI - Verifying Setup

Additional Meta CAPI Documentation

Getting Started

Data Collection

Metarouter platform

Integrations

Meta CAPI