> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt).

# Meta Web CAPI (New)

> Forward web conversion events to Meta's Conversions API server-side through Branch for Meta ad campaigns.

## Overview

Meta Web Conversions API (Web CAPI) enables Branch to forward web conversion events to Meta's [Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api) server-side. When users select your Meta ads that link to a Branch Ad Link, Branch captures click metadata, attributes the resulting web conversions, and forwards those events to Meta. This connects ad clicks, attribution, and campaign optimization.

Branch has always attributed web conversions. With Meta Web CAPI enabled, Branch also shares that web conversion signal with Meta. This gives Meta's algorithm the data it needs to improve Event Match Quality (EMQ) and optimize ad delivery. Meta Events Manager then shows more complete conversion reporting without relying solely on browser-based pixel tracking.

For more information about integrating ad partners in general, visit our [Ad Partner Integration Guide](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md).

> **Note: Meta Web CAPI vs. Meta SAN attribution**
>
> Meta Web CAPI sends web conversion signal *from* Branch *to* Meta to support optimization and reporting. It's separate from the Meta self-attributing network (SAN) integration, which returns app attribution claim data *to* Branch. Enabling Meta Web CAPI doesn't change how Branch attributes conversions or how Branch assigns Meta SAN credit.

### Partner capabilities

| Capability | Details |
| --- | --- |
| Supported event sources | Branch Web SDK, Server-to-server (S2S) |
| Platforms | Web |
| [Event Match Quality (EMQ)](https://www.facebook.com/business/help/765081237991954) | Supported, and enhanced when `fbc` is present |
| Event deduplication | Supported via `event_id` (mapped from `event_data.transaction_id`) |

## Before you begin

To set up Meta Web CAPI, you first need to:

- Enable Branch's Performance Product for your Branch account. Contact your Branch account manager or speak with our [Sales team](https://www.branch.io/contact-sales/).
- Enable the Meta (Facebook) integration in Branch under **Configuration > Integrations > Ad partners**.
- Implement the [Branch Web SDK](https://help.branch.io/developer-hub/web-sdk-overview.md) on your website with [event tracking](https://help.branch.io/developer-hub/track-branch-events.md) configured, or send web conversion events through [server-to-server (S2S)](https://help.branch.io/apidocs/events/overview.md) ingestion.
- Place Branch Ad Links in your Meta web campaigns. This is a primary matching signal Branch uses when forwarding events to Meta CAPI, and it improves EMQ. For more information, see [Event Match Quality (EMQ)](https://www.facebook.com/business/help/765081237991954).

## Enable Meta Web CAPI

To begin, navigate to **Configuration > Integrations** in Branch, select the **Ad partners** tab, and use the **Search partners** bar to find **Facebook**.

Meta CAPI requires a **Dataset ID** and **CAPI Access Token** from your Meta Events Manager account. Follow the steps below to retrieve these credentials and enable CAPI forwarding in Branch.

### Step 1: Retrieve your Dataset ID

1. Log in to [Meta Events Manager](https://business.facebook.com/events_manager).
2. Navigate to **Datasets**.
3. Select your dataset (pixel) from the left panel.
4. Copy your **Dataset ID** from the Events Activities window.

### Step 2: Generate a CAPI access token

1. In Meta Events Manager, select the dataset from Step 1.
2. Select the **Settings** tab.
3. Under **Conversions API**, locate the **Access Token** section.
4. Select **Generate access token**.
5. Copy the token.

### Step 3: Enter credentials in Branch

1. On the **Facebook** page in Branch, select **Partner settings**.
2. Under **Postback Credentials**, enter the Dataset ID from Step 1 in the **Dataset ID** field.
3. Enter the token from Step 2 in the **CAPI Access Token** field.
4. Select **Save**.

Once saved, Branch begins forwarding eligible web conversion events to Meta CAPI based on your configuration.

## Configure postbacks

Branch forwards web conversion events to Meta CAPI based on your postback configuration. Branch maps these to Meta's standard Conversions API event names as follows:

| Meta event | Branch event |
| --- | --- |
| `Purchase` | `PURCHASE` |
| `AddToCart` | `ADD_TO_CART` |
| `ViewContent` | `VIEW_ITEM` |
| `InitiateCheckout` | `INITIATE_PURCHASE` |
| `CompleteRegistration` | `COMPLETE_REGISTRATION` |
| `Search` | `SEARCH` |
| `AddToWishlist` | `ADD_TO_WISHLIST` |
| `Subscribe` | `SUBSCRIBE` |
| `StartTrial` | `START_TRIAL` |
| `{custom_event_name}` | `{custom_event_name}` |

To forward all web conversion events Branch receives, not just events attributed to Meta campaigns, turn on **Send all events** on the **Postback config** tab, and then select **Save Changes**. This gives Meta the broadest possible signal for optimization and reporting.

To add postbacks for additional events or to customize behavior, follow the steps in the ["Configure postbacks" section](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md#configure-postbacks) in the general [Ad Partner Integration Guide](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md).

## Deduplicate events with Meta Pixel

If you also use the Meta Pixel or send events through CAPI from other sources, the same conversion event may reach Meta more than once. Meta deduplicates these events using a shared `event_id`. If both events carry the same `event_name` and `event_id`, Meta counts them as a single conversion.

Branch uses `transaction_id` as the `event_id` it sends to Meta CAPI. To enable deduplication, pass the same `transaction_id` in your Branch Web SDK event as you do for the `eventID` in your Meta Pixel event for the same conversion.

> **Caution: transaction_id required for deduplication**
>
> If you don't provide a `transaction_id` on the event, Branch omits `event_id` from the CAPI payload. Meta can't deduplicate those events with Pixel, which may result in duplicate conversions in Meta reporting.

## Verify your data

After you save your credentials and configure postbacks, verify that events flow correctly:

- **In [Liveview](https://help.branch.io/account-hub/liveview-new.md)**: Confirm that web conversion events from your site appear in real time. Filter for `Platform = Web` to isolate web events.
- **In Meta Events Manager**: Navigate to your dataset and confirm that events forwarded by Branch appear under the **Overview** tab.
- **In Meta Events Manager > Test Events**: Use the Test Events tool to send a test conversion and verify that Meta receives and matches it correctly.

## CAPI data mappings

Branch maps the following fields from web conversion events to the Meta Conversions API payload:

| Meta CAPI field | Branch source field | Notes |
| --- | --- | --- |
| `event_name` | `name` | Mapped to Meta standard event names. See [Configure postbacks](#configure-postbacks). |
| `event_time` | `event_timestamp` | Unix timestamp in seconds. |
| `event_id` | `event_data.transaction_id` | Used for event deduplication. Omitted if `transaction_id` isn't present on the event. |
| `action_source` | Hardcoded: `"website"` | Required by Meta for all web CAPI events. |
| `event_source_url` | `user_data_http_origin` | The URL of the page where the conversion occurred. |
| `user_data.client_ip_address` | `user_data_ip` | Captured from the originating web request. |
| `user_data.client_user_agent` | `user_data_user_agent` | Captured from the originating web request. |
| `user_data.fbc` | `&fbclid` (via Branch Ad Link) | Formatted as `fb.1.{create_timestamp}.{fbclid}`. Omitted if `fbclid` isn't present. |
| `custom_data.value` | `revenue` | Included when present on the event. |
| `custom_data.currency` | `currency` | Included when present on the event. |
| `custom_data.contents` | `content_items[]` | Maps `$sku`, `$quantity`, and `$price` from each content item. |
| `custom_data.content_ids` | `content_items[].$sku` | Array of `$sku` extracted from content items. |

### Map content type to product

Branch automatically sets `content_type` to `product` when the event carries `content_items[]`. Otherwise, Branch doesn't add the `content_type` parameter.

## Troubleshoot

Use the checks below to troubleshoot common issues with Meta Web CAPI.

### Events not appearing in Meta Events Manager

If forwarded events don't appear in Meta Events Manager, check the following:

- You entered your **Dataset ID** and **CAPI Access Token** correctly in Branch. An invalid token causes Meta to reject all events.
- Branch Liveview shows your web events, which means the Branch Web SDK or S2S is tracking them. Branch can only forward events it receives.
- **Send all events** is on in the **Postback config** tab, or your active postbacks include the specific events you expect.

### Low EMQ score

If Meta reports a low EMQ score for forwarded events, check the following:

- Your Meta campaigns use Branch Ad Links. Without Branch Ad Links, Branch can't capture the `fbc` parameter, so CAPI events don't include it. The `fbc` parameter is the primary click-level matching signal and improves EMQ.
- Your Branch Web SDK implementation captures the page URL where conversions occur (`event_source_url`). Along with IP address and user agent, this field contributes to match quality when `fbc` is absent.

### Duplicate conversions in Meta reporting

If you use both Meta Pixel and Branch CAPI and see higher-than-expected conversion counts in Meta reporting, deduplication may not be working. Check the following:

- The `transaction_id` in your Branch Web SDK event matches the `eventID` in your Meta Pixel event for the same conversion.
- Both the Pixel event and the CAPI event use the same `event_name`. Meta requires both the event name and the event ID to match for deduplication.