> ## Documentation Index
> Fetch the complete documentation index at: https://funnelfox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Pixel integration

> Add Meta (Facebook) Pixel to your FunnelFox funnels. Track conversions, optimize ad campaigns, and build retargeting audiences.

Meta Pixel integration tracks funnel events in Facebook Events Manager, enabling better ad targeting and campaign optimization across Facebook and Instagram.

The integration includes two tracking methods:

* **Meta Pixel event tracking**
* **Conversions API**

<Frame>
  <img src="https://mintcdn.com/funnelfox/AXFzHTNSdei-sPeb/assets/meta-pixel-intro.png?fit=max&auto=format&n=AXFzHTNSdei-sPeb&q=85&s=3b157431644eeaf8cb5eeb050707e0a5" width="1229" height="787" data-path="assets/meta-pixel-intro.png" />
</Frame>

## Meta Pixel vs Conversions API

Here's how these two tracking methods work:

* **Meta Pixel** creates user identity on your funnel and tracks purchase, registration, and engagement events from the browser.

* **Conversions API** receives events from FunnelFox servers and checks if these events were already sent from the browser.

<Info>
  Conversions API is an addition to Meta Pixel that we highly recommend for
  complete event coverage. Learn more in the [Facebook documentation on Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/get-started).
</Info>

## Use Conversions API

Conversions API acts as a backup when browser tracking fails or gets blocked.

Here's a common example: When someone buys your product through PayPal, they complete the purchase on PayPal's website, not on your funnel. Some browsers (especially mobile app browsers) can't track this properly, so you might miss the `Purchase` event.

Conversions API solves this problem. When FunnelFox servers get the transaction details from PayPal, they automatically send a `Purchase` event to Facebook using Conversions API. This way, you never miss important conversion data.

FunnelFox deduplicates browser (Pixel) and server (CAPI) events by sending the same `event_id` and `external_id` with both, so Facebook keeps a single conversion if duplicates arrive.

## Tracked events

| Event                  | Meta Pixel Trigger                                                                | Conversions API Trigger                                                              |
| ---------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `Purchase`             | User completed checkout (not for free trial)                                      | FunnelFox received transaction event from PSP (not for free trial)                   |
| `StartTrial`           | User completed checkout with only free trial product                              | FunnelFox received new transaction event from PSP with only free trial product       |
| `Renewal`              | -                                                                                 | FunnelFox received transaction event from PSP that is listed as subscription renewal |
| `checkout_presented`   | User has opened a screen with checkout<br />**(Can fire multiple times)**         | -                                                                                    |
| `InitiateCheckout`     | User has seen the checkout element<br />**(Triggers only once per user session)** | -                                                                                    |
| `CompleteRegistration` | User completed screen with Authorization element or email input                   | User completed screen with Authorization element or email input                      |
| `ViewContent`          | User navigated to a new screen                                                    | -                                                                                    |

## Payment flow events

When customers purchase subscriptions, the event flow varies depending on the PSP.

Select your PSP below to see how each payment type triggers Meta Pixel events for your setup.

<AccordionGroup>
  <Accordion title="Stripe">
    | Purchase type                     |  Trial start | Conversion / Sub start |   Renewal  |
    | --------------------------------- | :----------: | :--------------------: | :--------: |
    | **Subscription only**             |       —      |       `Purchase`       |  `Renewal` |
    | **Free trial**                    | `StartTrial` |       `Purchase`       |  `Renewal` |
    | **Paid trial**                    |  `Purchase`  |        `Renewal`       |  `Renewal` |
    | **Subscription + intro discount** |       —      |       `Purchase`       |  `Renewal` |
    | **Lifetime (one-off)**            |       —      |       `Purchase`       |      —     |
    | **Subscription upsell**\*         |       —      |       `Purchase`       | `Purchase` |

    \* Additional subscription upsell (not upgrade instead of initial one).
  </Accordion>

  <Accordion title="Paddle">
    | Purchase type                     |  Trial start | Conversion / Sub start |  Renewal  |
    | --------------------------------- | :----------: | :--------------------: | :-------: |
    | **Subscription only**             |       —      |       `Purchase`       | `Renewal` |
    | **Free trial**                    | `StartTrial` |        `Renewal`       | `Renewal` |
    | **Paid trial**                    |  `Purchase`  |        `Renewal`       | `Renewal` |
    | **Subscription + intro discount** |       —      |       `Purchase`       | `Renewal` |
    | **Lifetime (one-off)**            |       —      |       `Purchase`       |     —     |
  </Accordion>

  <Accordion title="Solidgate">
    | Purchase type                       |  Trial start | Conversion / Sub start |  Renewal  |
    | ----------------------------------- | :----------: | :--------------------: | :-------: |
    | **Subscription only**               |       —      |       `Purchase`       | `Renewal` |
    | **Free trial**                      | `StartTrial` |        `Renewal`       | `Renewal` |
    | **Paid trial**                      |  `Purchase`  |        `Renewal`       | `Renewal` |
    | **Subscription + intro discount**\* |  `Purchase`  |        `Renewal`       | `Renewal` |
    | **Lifetime (one-off)**              |       —      |       `Purchase`       |     —     |

    \* Intro discounts cannot be configured directly in Solidgate. They are applied via a paid trial and use the same transactions.
  </Accordion>

  <Accordion title="FunnelFox Billing">
    | Purchase type          | Trial start | Conversion / Sub start |  Renewal  |
    | ---------------------- | :---------: | :--------------------: | :-------: |
    | **Subscription only**  |      —      |       `Purchase`       | `Renewal` |
    | **Free trial**         |  `Purchase` |       `Purchase`       | `Renewal` |
    | **Paid trial**         |  `Purchase` |        `Renewal`       | `Renewal` |
    | **Lifetime (one-off)** |      —      |       `Purchase`       |     —     |
  </Accordion>
</AccordionGroup>

## Configure events

By default, FunnelFox sends events to Meta based on the mappings described in the [Tracked events](/integrations/tracking/meta-pixel#tracked-events) and [Payment flow events](/integrations/tracking/meta-pixel#payment-flow-events) sections. You can customize this behavior to match your setup.

1. Go to **Purchase Event Mapping** on the [Integrations > Meta](https://app.funnelfox.com/integrations/meta) page.
2. Configure the following, then republish your funnel:

* **Toggle on / off**: Whether FunnelFox sends the event at all.
* **Channel**: How the event reaches Meta: **Browser + CAPI**,
  **Browser only**, or **CAPI only**.
* **Meta event**: The Meta event name the purchase maps to. Choose from
  `Purchase`, `Subscribe`, `StartTrial`, `AddToCart`,
  `InitiateCheckout`, and `Renewal`.
* **Include purchase value**: Attaches the purchase value and currency to
  the event so Meta can calculate return on ad spend.
* **First purchase only**: Sends only the first purchase per session and
  ignores upsells. Learn more in the
  [Limit purchase events](#limit-purchase-events) section below.

<Frame>
  <img src="https://mintcdn.com/funnelfox/TUDSXtzW3pBNKrn-/assets/meta-event-configuration.png?fit=max&auto=format&n=TUDSXtzW3pBNKrn-&q=85&s=8ff04d898f028637d1c6733f8ee96d34" width="1920" height="989" data-path="assets/meta-event-configuration.png" />
</Frame>

You can map these five events:

| Purchase event           | When it happens                                 | Available channels                      |
| ------------------------ | ----------------------------------------------- | --------------------------------------- |
| **One-off purchase**     | Single non-recurring payment.                   | Browser + CAPI, Browser only, CAPI only |
| **Trial start**          | User starts a free or paid trial.               | Browser + CAPI, Browser only, CAPI only |
| **Trial converted**      | Trial ends and the first payment is charged.    | CAPI only                               |
| **Subscription start**   | First subscription purchase without a trial.    | Browser + CAPI, Browser only, CAPI only |
| **Subscription renewal** | Recurring payment for an existing subscription. | CAPI only                               |

<Info>
  **Trial converted** and **Subscription renewal** happen after the user
  leaves the funnel, so the browser pixel cannot fire them. These events
  always send through Conversions API only.
</Info>

## Limit purchase events

You can stop sending purchase events for additional subscription upsells.
When this is on, FunnelFox suppresses the `Purchase` events for Stripe that a
subscription upsell would trigger (both its conversion and its renewals).

To do so, go to **Integrations > Meta** and toggle on
**First purchase only**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/TUDSXtzW3pBNKrn-/assets/meta-limit-events.png?fit=max&auto=format&n=TUDSXtzW3pBNKrn-&q=85&s=beb7c0e3bd7d0e19163858eae537ef09" width="1920" height="989" data-path="assets/meta-limit-events.png" />
</Frame>

Select your PSP below to see how each purchase type triggers Meta Pixel
events when the toggle is enabled.

<AccordionGroup>
  <Accordion title="Stripe">
    | Purchase type                     |  Trial start | Conversion / Sub start |  Renewal  |
    | --------------------------------- | :----------: | :--------------------: | :-------: |
    | **Subscription only**             |       —      |       `Purchase`       | `Renewal` |
    | **Free trial**                    | `StartTrial` |       `Purchase`       | `Renewal` |
    | **Paid trial**                    |  `Purchase`  |        `Renewal`       | `Renewal` |
    | **Subscription + intro discount** |       —      |       `Purchase`       | `Renewal` |
    | **Lifetime (one-off)**            |       —      |       `Purchase`       |     —     |
    | **Subscription upsell**\*         |       —      |            —           |     —     |

    \* Additional subscription upsell (not upgrade instead of initial one).
  </Accordion>

  <Accordion title="Paddle">
    | Purchase type                     |  Trial start | Conversion / Sub start |  Renewal  |
    | --------------------------------- | :----------: | :--------------------: | :-------: |
    | **Subscription only**             |       —      |       `Purchase`       | `Renewal` |
    | **Free trial**                    | `StartTrial` |        `Renewal`       | `Renewal` |
    | **Paid trial**                    |  `Purchase`  |        `Renewal`       | `Renewal` |
    | **Subscription + intro discount** |       —      |       `Purchase`       | `Renewal` |
    | **Lifetime (one-off)**            |       —      |       `Purchase`       |     —     |
  </Accordion>

  <Accordion title="Solidgate">
    | Purchase type                       |  Trial start | Conversion / Sub start |  Renewal  |
    | ----------------------------------- | :----------: | :--------------------: | :-------: |
    | **Subscription only**               |       —      |       `Purchase`       | `Renewal` |
    | **Free trial**                      | `StartTrial` |        `Renewal`       | `Renewal` |
    | **Paid trial**                      |  `Purchase`  |        `Renewal`       | `Renewal` |
    | **Subscription + intro discount**\* |  `Purchase`  |        `Renewal`       | `Renewal` |
    | **Lifetime (one-off)**              |       —      |       `Purchase`       |     —     |

    \* Intro discounts cannot be configured directly in Solidgate. They are applied via a paid trial and use the same transactions.
  </Accordion>

  <Accordion title="FunnelFox Billing">
    | Purchase type          | Trial start | Conversion / Sub start |  Renewal  |
    | ---------------------- | :---------: | :--------------------: | :-------: |
    | **Subscription only**  |      —      |       `Purchase`       | `Renewal` |
    | **Free trial**         |  `Purchase` |       `Purchase`       | `Renewal` |
    | **Paid trial**         |  `Purchase` |        `Renewal`       | `Renewal` |
    | **Lifetime (one-off)** |      —      |       `Purchase`       |     —     |
  </Accordion>
</AccordionGroup>

## Next steps

* [Set up Meta Pixel integration](/integrations/tracking/set-up-meta-pixel-integration)