# Pixel & CAPI (/docs/paid-media/pixel-capi)



For Meta and TikTok, conversion attribution requires:

* A **Pixel** (Meta) / **Pixel** (TikTok) on your site or app.
* A **CAPI** (Conversions API) / **Events API** access token to send
  events server-side.

Layers handles both server-side via the
[Layers SDK + ingest pipeline](/docs/sdk/architecture). You don't ship
the Meta SDK or TikTok SDK in your app.

## How it works [#how-it-works]

1. The Layers SDK in your app sends events to `in.layers.com/l/events`.
2. The ingest pipeline stores the event in the SDK event store.
3. The CAPI relay looks up the project layer's CAPI config. If the
   layer is active and its CAPI block has `enabled = true`, a `pixel_id`
   set, and a resolvable `access_token_vault_id`, the relay continues.
4. If all conditions are met, the relay POSTs the event to:
   * Meta Graph API's Conversions endpoint (keyed to the Pixel / dataset
     ID from `capi.pixel_id`). Events are mapped from the SDK name to a
     standard Meta event name (e.g. `purchase_success → Purchase`).
     Unmapped events are dropped.
   * TikTok Events API. Events are mapped to standard TikTok events;
     unmapped events dropped.

## Where to configure [#where-to-configure]

In each ad layer's settings:

```json
{
  "capi": {
    "enabled": true,
    "pixel_id": "1234567890",
    "access_token_vault_id": "vault_xyz"
  }
}
```

The `vault_id` references an entry in the
[Layers credential vault](/docs/trust/vault) — the actual token never
appears in config.

## Generating tokens [#generating-tokens]

### Meta [#meta]

1. Meta Events Manager → your Pixel → **Settings** → **Conversions API**.
2. Click **Generate access token**.
3. Copy.
4. In Layers, paste into the layer setup wizard. Layers stores in vault
   and shows you the `vault_id`.

### TikTok [#tiktok]

1. TikTok Business Center → Events Manager → your Pixel → **Settings**.
2. Click **Generate access token**.
3. Copy and paste into Layers.

## Test events [#test-events]

After configuration, run a test event:

1. In Layers, the layer's overview tab → **Send test event**.
2. Open Meta Events Manager → **Test Events**, or TikTok Events Debugger.
3. Confirm the event arrived.

## Event name mapping [#event-name-mapping]

Both Meta and TikTok relays map SDK event names to the platform's
standard events. Events that don't map are dropped (logged but not
forwarded). Dedup across a client-side Pixel and CAPI is handled via
`event_id`, not naming — see below.

Defaults — see [standard events](/docs/sdk/standard-events) for the full
mapping table:

* `purchase_success`, `paywall_purchased` → Meta `Purchase`, TikTok `Purchase`
* `subscription_start`, `trial_start` → Meta `Subscribe`/`StartTrial`, TikTok `Purchase`
* `add_to_cart` → `AddToCart`
* `content_open` → `ViewContent`
* `sign_up` → `CompleteRegistration`

Per-layer overrides can be set via `capi.event_map` on the layer
config.

## Event ID for dedup [#event-id-for-dedup]

Each Layers SDK event has a UUID `event_id`. CAPI requests include this
ID. If you also have a client-side Pixel firing the same event, ensure
both share the `event_id` so Meta dedupes.

## Vault binding [#vault-binding]

The token is decrypted only inside the CAPI relay path at send time —
it never appears in logs or in API responses. See
[Vault & credential handling](/docs/trust/vault).

## Multi-pixel setups [#multi-pixel-setups]

For brands with separate Pixels per app or geo:

* Install one Meta Ads layer (or TikTok Ads layer) per Pixel.
* Each layer has its own `capi` config.
* The CAPI relay routes events to the right Pixel based on the
  app → project-layer lookup.

## Troubleshooting [#troubleshooting]

* **Events not arriving** — check the layer's overview tab for "CAPI
  silent failure" warnings. Common cause: vault\_id rotated; regenerate.
* **Duplicate conversions** — the client Pixel and CAPI both reported
  without sharing `event_id`. Synchronize event\_ids in your client code.
* **TikTok event dropped** — your custom event name isn't in the
  standard map. Either rename in your SDK or accept the drop.