Meta Conversions API · Setup, Integration & Event Match Quality

The browser-based Meta Pixel relies on JavaScript executing in the user's browser and cookies being set and read. Three factors have progressively eroded pixel reliability:

• iOS 14.5 ATT (2021). The majority of iOS users opted out of cross-app tracking, blocking Meta from reading the IDFA. Pixel-based conversion attribution for opted-out iOS users is significantly impaired.
• Ad blockers. An estimated 25–40% of desktop users in Western markets use ad blockers that block the Meta Pixel script from loading, causing those conversions to be entirely invisible to Meta.
• Browser privacy features. Safari's Intelligent Tracking Prevention (ITP) limits third-party cookies to 7 days (and sometimes 24 hours), shortening effective attribution windows.

CAPI bypasses all three: it fires from your server regardless of what the user's device or browser is doing. A purchase that completes on an opted-out iOS Safari session with an ad blocker — completely invisible to the pixel — is fully captured by server-side CAPI.

When a user completes an action on your website (purchase, lead submission, etc.), your server sends an HTTP POST request to Meta's Conversions API endpoint with the event data — including hashed customer identifiers that Meta uses to match the event to a Meta user account and attribute it to the ad interaction that drove it.

POST https://graph.facebook.com/v18.0/{pixel_id}/events
{
  "data": [{
    "event_name": "Purchase",
    "event_time": 1712345678,
    "event_id": "order_12345",          // for deduplication
    "action_source": "website",
    "user_data": {
      "em": ["[hashed_email]"],          // SHA-256 hashed email
      "ph": ["[hashed_phone]"],          // SHA-256 hashed phone
      "fn": "[hashed_first_name]",
      "ln": "[hashed_last_name]",
      "ct": "[hashed_city]",
      "client_ip_address": "192.168.1.1",
      "client_user_agent": "Mozilla/5.0...",
      "fbc": "fb.1.1234567890.AbCdEfGhIj",  // click ID from URL
      "fbp": "fb.1.1234567890.1234567890"   // browser pixel cookie
    },
    "custom_data": {
      "value": 99.00,
      "currency": "GBP",
      "contents": [{"id": "SKU123", "quantity": 1}],
      "order_id": "order_12345"
    }
  }],
  "access_token": "YOUR_ACCESS_TOKEN"
}

All customer data must be hashed with SHA-256 before sending — Meta performs the matching on its side using the same hashing. Never send unhashed PII (email, phone, name) to the API.

Direct integration fires CAPI events from your backend code — the most flexible and highest-control implementation method. Requires developer involvement.

Setup steps

1. Generate a System User Access Token. In Business Manager: System Users → Add System User → assign your pixel as an asset with Advertise permission → Generate Token. This token is used to authenticate CAPI requests.
2. Implement server-side event sending. On every conversion event (order confirmed, lead submitted), your server code sends the CAPI POST request with the event data and hashed user identifiers.
3. Pass event_id for deduplication. Generate a unique event_id for each event occurrence and send it in both the browser pixel and the CAPI request — Meta uses this to deduplicate (see deduplication section).
4. Verify in Events Manager. Test Events tool shows CAPI events arriving in real time — verify event_name, parameters, and user_data fields are present.

Meta provides official SDKs for Python, Node.js, PHP, Ruby, and Java to simplify the API calls — available at developers.facebook.com/docs/marketing-api/conversions-api.

For common e-commerce and CMS platforms, Meta has pre-built partner integrations that implement CAPI without custom development:

Partner integrations typically handle base pixel installation, standard e-commerce events (ViewContent, AddToCart, Purchase with value), and CAPI simultaneously. Check the specific integration documentation to confirm which events it sends server-side vs browser-only.

Meta's Conversions API Gateway is a cloud-hosted solution that Meta operates — providing CAPI functionality without requiring you to build and maintain your own server-side integration. It acts as a proxy: your browser pixel sends events to the Gateway server, which then forwards them to Meta's CAPI with additional server-side signals.

Gateway CAPI is suitable for businesses that want CAPI's signal quality improvement without direct API development. It is less technically demanding than direct integration but provides less flexibility — you cannot add custom business logic or additional data enrichment the way a direct integration can.

Setup: in Events Manager → your pixel → Settings → Conversions API → Set Up Gateway. Meta provides a CloudFormation template (AWS) or Docker container for self-hosted deployment.

Running pixel and CAPI simultaneously means Meta may receive the same event twice — once from the browser and once from the server. Without deduplication, every conversion would be counted twice, corrupting conversion data and Smart Bidding signals.

Meta deduplicates using the event_id parameter: when the same event_id arrives via both pixel and CAPI within the deduplication window, Meta counts it as one event. Implementation requirements:

• Pixel side: Pass eventID parameter in the pixel event call: fbq('track', 'Purchase', {value: 99, currency: 'GBP'}, {eventID: 'order_12345'})
• CAPI side: Pass the same value as the event_id field in the API request
• Uniqueness: The event_id must be unique per event occurrence — use the order ID for Purchase, a UUID for Lead events, etc.

Verify deduplication is working in Events Manager → your pixel → Events tab — events processed via deduplication show a "Deduplicated" label. If you see double the expected conversion count, deduplication is not working and event_id matching needs to be verified.

Event Match Quality (EMQ) is a 0–10 score in Events Manager that measures how well Meta can match your conversion events to actual Meta user accounts. Higher EMQ means better attribution, better optimisation, and more complete Custom Audiences. Low EMQ means conversions are going unattributed — they happened but Meta cannot tell which user's ad interaction caused them.

Customer data fields ranked by EMQ contribution

Target EMQ score of 7.0+. Scores below 6 indicate significant matching gaps — typically caused by missing email or phone data. The most impactful improvement: ensure email address is collected at checkout and passed to CAPI for every Purchase event.

Authentic Sources