---
id: "integrations/attribution/reference/meta-ads"
title: "Meta Ads Event Delivery Reference"
description: "Use this page as a reference for the event delivery request RevenueCat sends to Meta Ads. It maps RevenueCat sources to Meta request elements. For setup steps, see Meta Ads."
permalink: "/docs/integrations/attribution/reference/meta-ads"
slug: "docs/integrations/attribution/reference/meta-ads"
version: "current"
original_source: "docs/integrations/attribution/reference/meta-ads.mdx"
---

> **AI agents:** This is the Markdown version of a RevenueCat documentation page. For the complete documentation index, see [llms.txt](https://www.revenuecat.com/docs/llms.txt).

Use this page as a reference for the event delivery request RevenueCat sends to Meta Ads. It maps RevenueCat sources to Meta request elements. For setup steps, see [Meta Ads](https://www.revenuecat.com/docs/integrations/attribution/meta-ads).

Meta's event APIs support many matching and event fields, but Meta's API docs don't describe which values RevenueCat can populate. Use this reference when you need to understand which RevenueCat event fields, customer attributes, and dashboard settings RevenueCat includes in Meta requests. Successful delivery means Meta accepted the request; Meta still decides whether the event can be matched, attributed, made eligible for App Promotion, or used for optimization.

| Meta API path | Delivery behavior | Required identifiers |
| :------------ | :----------------- | :------------------- |
| **Conversions API** | Sends server-side events to a Meta dataset for app, web, or workflow events. | Native app events require `$fbAnonId` or a platform advertising ID. iOS events also require ATT authorization or the dashboard setting that allows delivery without it. Web events use web matching attributes when available. |
| **App Events API** | Sends app events through Meta's older app activities endpoint. | App events require `$fbAnonId` or a platform advertising ID. iOS events also require ATT authorization. |

## Example event delivery requests

### Conversions API example

RevenueCat sends Conversions API (CAPI) events to the configured production or sandbox Meta dataset using the configured access token.

```json
{
  "headers": {
    "X-Forwarded-For": "<ip_address>"
  },
  "body": {
    "partner_agent": "revenuecat",
    "access_token": "<conversions_api_token>",
    "data": [
      {
        "event_name": "<meta_event_name>",
        "event_time": <event_timestamp_seconds>,
        "action_source": "<action_source>",
        "event_id": "<revenuecat_generated_order_id>",
        "user_data": {
          "madid": "<idfa_or_google_advertising_id>",
          "anon_id": "<facebook_anonymous_id>",
          "external_id": "<hashed_app_user_id>",
          "em": "<hashed_email>",
          "ph": "<hashed_phone>",
          "client_ip_address": "<ip_address>",
          "client_user_agent": "<user_agent>",
          "fbp": "<browser_id>",
          "fbc": "<click_id>"
        },
        "custom_data": {
          "currency": "USD",
          "value": <usd_revenue>,
          "order_id": "<revenuecat_generated_order_id>",
          "content_type": "product",
          "content_ids": ["<product_id>"],
          "contents": [
            {
              "id": "<product_id>",
              "quantity": 1
            }
          ]
        },
        "app_data": {
          "advertiser_tracking_enabled": <advertiser_tracking_enabled>,
          "application_tracking_enabled": <application_tracking_enabled>,
          "vendor_id": "<idfv>",
          "extinfo": [
            "i2",
            "<bundle_id>",
            "",
            "<app_version>",
            "<os_version>",
            "",
            "<locale>",
            "",
            "",
            0,
            0,
            "",
            0,
            0,
            0,
            ""
          ]
        }
      }
    ]
  }
}
```

### App Events API example

The App Events API is Meta's older app-event delivery path. It uses the configured Meta App ID and Client Token, and sends a `CUSTOM_APP_EVENTS` payload to the app activities endpoint.

```json
{
  "headers": {
    "X-Forwarded-For": "<ip_address>"
  },
  "body": {
    "event": "CUSTOM_APP_EVENTS",
    "advertiser_tracking_enabled": "1",
    "application_tracking_enabled": "1",
    "app_user_id": "<app_user_id>",
    "client_token": "<client_token>",
    "advertiser_id": "<idfa_or_google_advertising_id>",
    "custom_events": [
      {
        "_eventName": "<meta_event_name>",
        "fb_content": [
          {
            "id": "<product_id>",
            "quantity": 1
          }
        ],
        "_valueToSum": <usd_revenue>,
        "fb_content_type": "product",
        "fb_currency": "USD",
        "fb_order_id": "<revenuecat_generated_order_id>",
        "_logTime": <event_timestamp_seconds>
      }
    ],
    "ud": {
      "em": "<hashed_email>",
      "ph": "<hashed_phone>"
    },
    "extinfo": [
      "i2",
      "<bundle_id>",
      "",
      "<app_version>",
      "<os_version>",
      "",
      "<locale>",
      "",
      "",
      0,
      0,
      "",
      0,
      0,
      0,
      ""
    ]
  }
}
```

## RevenueCat source to Meta request mapping

### Conversions API mapping

| Meta CAPI request element | RevenueCat source and behavior |
| :--- | :--- |
| Endpoint and credentials | Sends `POST` requests using the configured production or sandbox Dataset ID in the endpoint, and sends the matching Conversions API token as `access_token` in the JSON body. |
| `action_source` | Sends `app` for native app purchase and install events, and `website` for web purchase or Funnels events. |
| `event_source_url` | Sent when RevenueCat has a page URL from web purchase or workflow context, or the `$pageUrl` customer attribute. |
| `event_id` | Uses a RevenueCat-generated order ID for purchase events and an install event ID for install-style events. For purchase events, the same generated order ID is also sent as `custom_data.order_id`. |
| `custom_data` | Sends USD revenue as `value`, `USD` as `currency`, `order_id`, product content fields, and workflow fields for Funnels events where applicable. |
| `user_data.madid` | Sends the valid IDFA, Google Advertising ID, or Amazon Advertising ID when available for the event platform. |
| `user_data.anon_id` | Sends `$fbAnonId` for native app events. RevenueCat doesn't send `anon_id` for web-originated purchases. |
| `user_data.external_id` | Sends a hashed RevenueCat app user ID. |
| `user_data.em` and `user_data.ph` | Sends hashed email and phone values when those customer attributes are set. |
| `user_data.client_ip_address` | Sends the `$ip` customer attribute when available. |
| `user_data.client_user_agent` | Sends web or workflow user agent data, or the `$userAgent` customer attribute when available. |
| `user_data.fbp` and `user_data.fbc` | Sends web click/browser identifiers from event data, or the `$fbp` and `$fbc` customer attributes when available. |
| `app_data` | Sends tracking flags, IDFV as `vendor_id` when available, and Meta `extinfo` app/device context from RevenueCat's last-seen app data where available. Unavailable `extinfo` values are left blank or zeroed. |
| Request headers | Sends `X-Forwarded-For` when RevenueCat has an IP address. |

### App Events API mapping

| Meta App Events API request element | RevenueCat source and behavior |
| :--- | :--- |
| Endpoint and credentials | Sends `POST` requests using the configured production or sandbox Meta App ID in the endpoint, and sends the matching Client Token as `client_token` in the JSON body. |
| `event` | Sends `CUSTOM_APP_EVENTS`. |
| `advertiser_tracking_enabled`, `application_tracking_enabled` | Sends static `"1"` values for App Events API events. |
| `app_user_id` | Sends the RevenueCat app user ID. |
| `advertiser_id` or `anon_id` | Sends a valid IDFA, Google Advertising ID, or Amazon Advertising ID when available. If RevenueCat doesn't have a mobile advertising ID, it sends `$fbAnonId` as `anon_id`. |
| `custom_events` | Sends the configured Meta event name, product content fields, USD revenue, `USD` currency, generated order ID, and log time. |
| `ud.em` and `ud.ph` | Sends hashed email and phone values when those customer attributes are set. |
| `extinfo` | Sends Meta app/device context from RevenueCat's last-seen app data where available; unavailable values are left blank or zeroed. |
| Request headers | Sends `X-Forwarded-For` when RevenueCat has an IP address. |

## Web-originated purchases

For Web Billing or other web-originated purchases, mobile advertising identifiers are not expected. Add web matching attributes such as `$email`, `$phoneNumber`, `$ip`, `$fbp`, `$fbc`, `$userAgent`, and `$pageUrl` when available and privacy-compliant to improve matching quality.