# Meta Ads Setup (/docs/paid-media/meta-setup)



The Meta Ads Manager layer (template ID
`9b38d03f-9f35-43bc-a823-2ffe603601dd`) drives Facebook and Instagram
campaigns.

## Agency mode [#agency-mode]

1. **Install the layer** from the catalog.
2. The setup wizard shows Layers' Business ID:
   `business_id_xxx`. Copy it.
3. In your Meta Business Manager → Settings → **Partners** → **Add
   partner** → paste Layers' Business ID.
4. Pick assets to share:
   * **Ad account** (Full access).
   * **Page** (Read).
   * **Pixel** (Manage).
   * **Instagram account** (Full access — required for Instagram ads).
5. Send the partnership request.
6. Back in Layers, click **Accept and bind**. Pick which of your shared
   ad accounts this layer manages.
7. Wallet check: top up the Org wallet before enabling agency-mode
   campaigns (see [Wallet & billing](/docs/paid-media/wallet-billing)).
8. Save.

## BYO mode [#byo-mode]

1. **Install the layer** in BYO mode.
2. Click **Connect via OAuth**. Meta dialog opens.
3. Sign in with the user that admins the ad account.
4. Grant scopes: `ads_management`, `ads_read`, `business_management`,
   `pages_show_list`, `pages_read_engagement`.
5. Pick the ad account.
6. Provide:
   * **Pixel ID** — the Meta Pixel that receives conversions.
   * **CAPI access token** — generate from Meta Events Manager → your
     Pixel → Settings → **Conversions API** → **Generate access token**.
7. Layers stores the token in the
   [Layers credential vault](/docs/trust/vault) and shows you the
   `vault_id` reference.
8. Verify by sending a test event.

## Layer config [#layer-config]

Once set up, the layer config has:

```json
{
  "mode": "agency" | "byo",
  "metaBusinessId": "...",
  "adAccountId": "act_...",
  "pageId": "...",
  "instagramAccountId": "...",
  "capi": {
    "enabled": true,
    "pixel_id": "1234567890",
    "access_token_vault_id": "vault_abc"
  },
  "objectives": ["app_installs", "purchases"],
  "geos": ["US", "CA", "UK"],
  "monthlyCostCap": 50000
}
```

## CAPI requirements summary [#capi-requirements-summary]

* `is_active = true`
* `is_deleted = false`
* `capi.enabled = true`
* `pixel_id` set
* `access_token_vault_id` resolvable

If any of these is false, CAPI relay silently no-ops. Layers surfaces this
on the layer's overview tab.

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

For brands with separate Pixels per app or geo:

* Install one Meta Ads layer per Pixel.
* Each layer has its own CAPI config and ad account.
* Dashboards roll up across all installed layers.

## Verification checklist [#verification-checklist]

* [ ] Layers can list your campaigns.
* [ ] CAPI test event appears in Events Manager → Test Events.
* [ ] Pixel ID matches the one on your website / app.
* [ ] Wallet (agency) or billing method (BYO) is funded.
* [ ] Optimizer is enabled.

## Troubleshooting [#troubleshooting]

* **"Partnership pending"** (agency) — Meta hasn't notified Layers yet;
  refresh in 5 min.
* **"Token decryption failed"** (BYO) — vault\_id rotated; regenerate
  CAPI token and re-paste.
* **Events not arriving in Test Events** — make sure the SDK is
  configured to forward to `in.layers.com`, not direct to Meta.