Meta CAPI Setup Guide: Conversions API Explained
Step-by-step guide to setting up Meta Conversions API (CAPI). Why pixel alone fails, setup options, deduplication, Event Match Quality optimization, and testing.
Meta Conversions API Setup Guide: Complete CAPI Implementation for 2026
The Meta Pixel alone is no longer sufficient for accurate conversion tracking. iOS privacy changes, ad blockers, and browser cookie restrictions have degraded pixel accuracy to 40–70% of actual events for most advertisers.
Meta Conversions API (CAPI) solves this by moving conversion data from the browser to your server, bypassing the privacy restrictions that break pixel tracking. This guide walks you through the complete CAPI setup — from Events Manager configuration through testing and validation.
---
What You'll Need Before Starting
Before configuring CAPI, confirm you have:
• Meta Business Manager access — Admin or developer role
• Ad account — Active account linked to your Business Manager
• Facebook Page — Associated with your business
• Server access — Ability to add code to your web server or ecommerce platform
• Pixel installed — Existing browser pixel recommended (for dual-tracking with deduplication)
• Access token — System user token or page token (covered in setup steps below)
---
Step 1: Create or Locate Your Dataset in Events Manager
Meta's Conversions API sends events to a dataset (previously called a pixel). If you have an existing pixel, your CAPI events should use the same dataset ID to enable deduplication between browser and server events.
1. Go to Events Manager at business.facebook.com/events_manager
2. Select your ad account from the top-left dropdown
3. Click + Connect Data Sources if creating new, or select your existing pixel/dataset
4. If creating new: choose Web → Conversions API → name your dataset
5. Note the Dataset ID (also called Pixel ID) — you'll need it for all API calls
---
Step 2: Generate a System User Access Token
CAPI requires a long-lived access token. System user tokens are the recommended approach — they don't expire when users change passwords or revoke app permissions.
Create a System User
1. In Business Manager, go to Business Settings → Users → System Users
2. Click Add → name the system user (e.g., "CAPI Integration") → set role to Employee
3. Click Add Assets → select your ad account → grant Advertiser access
4. Click Add Assets → select your pixel/dataset → grant Analyze and Upload access
Generate the Token
1. On the System User page, click Generate New Token
2. Select your app (or create one at developers.facebook.com)
3. Required permissions: ads_management, ads_read, business_management
4. Set expiration: Never (for server-side automation)
5. Copy and securely store the token — you won't be able to see it again
---
Step 3: Understand the CAPI Event Structure
Before implementing, understand what you're sending. Each CAPI event is a JSON payload sent to:
Minimum required fields:
Key fields explained:
| Field | Required | Description |
|-------|----------|-------------|
| event_name | Yes | Standard event name (Purchase, Lead, etc.) |
| event_time | Yes | Unix timestamp when event occurred |
| action_source | Yes | website, app, phone_call, email, other |
| event_id | Dedup | Unique ID — must match pixel eventID for deduplication |
| user_data.em | Recommended | SHA-256 hashed email |
| user_data.ph | Recommended | SHA-256 hashed phone |
| client_ip_address | Recommended | User's IP address (from request headers) |
| client_user_agent | Recommended | User's browser agent string |
---
Step 4: Hash User Data Correctly
Meta requires PII to be SHA-256 hashed. Incorrect hashing is the most common setup error.
Hashing rules:
• Lowercase before hashing
• Remove whitespace before hashing
• Phone numbers: E.164 format without + (e.g., 14155551234)
• Email: user@example.com → lowercase → hash
• Names: lowercase, no leading/trailing spaces
Python example:
Node.js example:
Never send unhashed PII. Meta will reject events that appear to contain plain-text email addresses or phone numbers.
---
Step 5: Generate Event IDs for Deduplication
If you're running both pixel and CAPI (recommended), deduplication prevents Meta from counting the same conversion twice.
How deduplication works:
1. Your browser pixel fires with eventID: "order_12345_ts_1678901234"
2. Your server sends the same event with event_id: "order_12345_ts_1678901234"
3. Meta sees matching IDs → counts as one event
Event ID generation strategy:
Important: Generate the event ID server-side and pass it to the browser for pixel use, not the other way around. This ensures consistency even if the browser is slow or blocks the pixel.
---
Step 6: Implement CAPI Events
Option A: Direct API Integration (Any Platform)
Send events directly from your server using HTTP:
Option B: Shopify (Native Integration)
1. In Shopify Admin → Apps → Facebook & Instagram
2. Under Data Sharing, enable Maximum level
3. This activates Shopify's native analytics integration for purchase and checkout events
Note: Shopify's native integration sends purchase events but may miss other conversion events (add-to-cart, view content). F