Meta Ads CAPI Setup

[Didoo AI] Step-by-step guide for setting up Meta Conversions API (CAPI) — server-side event tracking that improves conversion measurement accuracy and reduces CPA discrepancy vs pixel-only tracking. Use when setting up tracking for a new account or when CPA shown in Meta Ads Manager is significantly higher than actual leads/sales.

Elias@Didoo@elias-didoo

Install

openclaw skills install @elias-didoo/meta-ads-capi-setup

Meta Ads CAPI Setup Guide

Required Credentials

Credential	Where to Get	Used For
META_ACCESS_TOKEN	Meta Developer Console → Graph API Explorer → Generate Token	All Meta Marketing API calls
META_PIXEL_ID	Meta Events Manager → select your Pixel → copy Pixel ID	Identifying which pixel to configure

Token note: The System User access token (generated in Business Settings) is the primary credential for CAPI API calls. You still need a registered Meta App (App ID) to set up the CAPI integration in Events Manager — the App ID is required when creating the System User and configuring token permissions. Make sure the token includes these scopes: ads_management, business_management, pages_read_engagement.

When to Use

When setting up tracking for a new account, or when CPA shown in Meta Ads Manager is significantly higher than actual leads/sales (indicating a tracking gap). CAPI is especially critical for lead generation campaigns where offline conversions are the true business outcome.

What CAPI Does (vs Pixel Only)

Pixel only: Browser-based. Tracks users who click your ad and then take action on your website. Misses users who convert on different devices, after clearing cookies, or without clicking.
CAPI: Server-to-server. Sends conversion events directly from your server to Meta. More accurate, more reliable, harder to block.

Together: Pixel + CAPI gives Meta the most complete picture → better optimization → lower CPA over time.

If you're not using CAPI, you're likely overpaying for every lead. The gap can be 20–50% depending on industry and browser mix.

Prerequisites

Before setting up CAPI, you need:

Meta Pixel installed on your website
A Meta App registered at developers.facebook.com (App ID required to configure CAPI in Events Manager)
A server environment that can send HTTP requests (or a partner integration like Shopify, WooCommerce, Zapier, or Google Tag Manager Server-side)
Access to your Meta Business Manager with pixel-level permissions

Step 1: Choose Your Integration Method

Recommended for Most SMBs — Native Platform Integration

Use your e-commerce platform's built-in Meta integration. This is the easiest path:

Platform	How to Connect
Shopify	Shopify Admin → Sales Channels → Meta
WooCommerce	Plugins → Meta for WooCommerce
Other platforms	Check Meta's partner directory at meta.com/partners

Steps (native integration):

Go to Meta Events Manager → select your Pixel
Click "About CAPI" → "Get Started"
Select your platform from the partner list
Follow the on-screen prompts to authorize the connection
Select which events to send (see Step 3 below)

Advanced — Manual Integration Options

Only use these if you are a developer or using a platform without native Meta integration.

Method	Best For	Complexity
Google Tag Manager Server-Side	Teams already using GTM	Medium
Zapier / Make.com	No-code teams, non-standard tech stacks	Medium
Meta Conversions API via Meta Business Manager	Simple server events without developer resources	Low
Direct API Integration	Developers building custom infrastructure	High

For Direct API: use your META_ACCESS_TOKEN to send events to https://graph.facebook.com/v21.0/{pixel_id}/events.

Step 2: Generate a System User Access Token

Go to Meta Business Manager → Business Settings → System Users
Create a new system user with "Analytics" or "Ads" permissions
Generate an access token with: ads_management, business_management, pages_read_engagement
Save this token securely — you'll need it for all API calls

Step 3: Configure Which Events to Send

Go to Meta Events Manager → select your Pixel
Click "About CAPI" → "Get Started"
Select your integration method
Configure which events to send:

Event	Recommended For
PageView	All campaigns — helps Meta build audience
ViewContent	E-commerce product pages
AddToCart	E-commerce
Purchase	E-commerce (critical — this is your conversion event)
Lead	Lead generation (critical — matches your optimization goal)
CompleteRegistration	Webinar, courses, freemium signups
Contact	Local service businesses

Step 4: Test Your CAPI Connection

In Meta Events Manager:

Select your pixel → "Test Events" tab
Trigger the events on your website (submit a form, complete a purchase, etc.)
Check that events appear in the test panel within seconds

What to verify:

Events are arriving with Deduping source confirmed (CAPI and Pixel aren't double-counted)
Event IDs are being passed (for deduplication)
Parameter completeness — more parameters = better optimization

Event parameters that improve CAPI quality:

event_id — unique ID per event, enables deduplication
user_data — email, phone, country (hashed with SHA-256)
custom_data — value, currency, content_name, content_category

Step 5: Verify CAPI Is Working Correctly

In Meta Events Manager, check:

Event Quality Score — should be "Active" with green status
Matching Quality — how many user parameters Meta can match to real users
No significant gap between pixel events and CAPI events

Matching Quality benchmarks:

7+ parameters with good hash quality → Excellent
5–6 parameters → Good
< 5 parameters → Poor — optimize your event setup

Step 6: Standard Events vs. Custom Events

Standard Events (Preferred)

Meta's predefined event names: Lead, Purchase, PageView, ViewContent, AddToCart, InitiateCheckout, CompleteRegistration. Better optimization because Meta knows exactly what the event means.

Custom Events

Use only when no standard event fits. Define custom name and parameters yourself. Required for: offline sales, phone calls, specific business workflows.

CAPI Common Issues and Fixes

Issue	Likely Cause	Fix
CAPI events not appearing in Meta	Token expired or permissions wrong	Regenerate access token with correct permissions
Huge gap between pixel and CAPI volumes	CAPI not connected properly	Check Events Manager → CAPI status
CPA artificially high in Meta	CAPI not sending offline conversions (lead gen)	Verify Lead event is firing server-side
Events marked as "Unmatched"	User data not being passed correctly	Ensure email/phone is hashed before sending
Duplicate events (double counting)	Both pixel and CAPI firing without deduplication	Pass event_id in both pixel and CAPI calls

Lead Generation — CAPI Is Especially Critical

For lead gen campaigns, the conversion happens offline — someone fills out a form, you call them, they sign up. Meta pixel can't see this.

What CAPI must send for lead gen:

Lead event when form is submitted (server-side, not just pixel)
Lead event when you mark a lead as qualified in your CRM (offline → Meta)
Revenue data if possible (even approximate) — helps Meta optimize for quality

CRM Integrations that support CAPI for leads: HubSpot, Salesforce, Zapier, Make.com.

If you're not sending offline lead data back to Meta: Meta is optimizing for form submissions only. You're paying for leads that never convert.

Event Deduplication — Preventing Double Counting

When both Pixel and CAPI send the same event (same event_id), Meta deduplicates automatically. Requirements:

Same event_id in both pixel and CAPI call
Same event_name
Events fired within the same 48-hour window
Same user data (at least one: email, phone, client_ip, client_user_agent)

Security Notes

Access tokens for CAPI should be treated like passwords — store in environment variables, never in code repositories
Use HTTPS for all CAPI calls
Hash PII (email, phone) using SHA-256 before sending to Meta