Server-side tracking for Facebook & Instagram ads, with consent built in.

Why server-side?

Browser pixels miss conversions: ad blockers, Safari's tracking limits and closed tabs all drop events before they reach Meta. Meta recommends sending the same events from a server through the Conversions API, with a shared event_id so each conversion is counted once. CAPI Relay is that server, ready to deploy.

Your backend can also send events directly with POST /v1/events.

Quick start

1. Get your IDs from Meta. In Events Manager, open your dataset (Pixel), then Settings. Copy the dataset ID. Under Conversions API, click Generate access token. No app review is needed.
2. Deploy the template and fill in META_PIXEL_ID, META_ACCESS_TOKEN and ALLOWED_ORIGINS (your site, for example https://www.myshop.com). The dashboard password and API key are generated for you.
3. Add a custom domain on the service, such as t.myshop.com (Railway → service → Settings → Networking). On a subdomain of your site, the browser sends the Pixel's _fbp/_fbc cookies to the relay, which improves matching.
4. Add the snippet below to your site and connect it to your cookie banner.
5. Test. Set META_TEST_EVENT_CODE to the code shown in Events Manager → Test events, open https://t.myshop.com/admin (any username, password = ADMIN_PASSWORD) and press Send a test event. Remove the variable when you go live.

Website snippet

Load it after your Meta Pixel (which should itself only load after consent):

<script>
  window.capi = window.capi || function () { (capi.q = capi.q || []).push(arguments) };
</script>
<script async src="https://t.myshop.com/capi.js"></script>

From your cookie banner's callback, when the visitor accepts marketing cookies:

capi('consent', true);   // and capi('consent', false) if they withdraw it

Then send events with capi('track', …) instead of fbq('track', …). It fires the Pixel and the relay with the same event ID:

capi('track', 'ViewContent', { content_ids: ['sku-42'], content_type: 'product' });

capi('track', 'Purchase',
  { value: 49.90, currency: 'EUR', order_id: '1042' },
  { userData: { em: 'jane@example.com', ph: '06 12 34 56 78' }, eventId: 'order-1042' });

The helper never sets cookies. It reads the _fbp and _fbc cookies created by the Pixel, and builds fbc from an fbclid URL parameter when needed.

Server API

Send events from your backend: order confirmations, CRM updates, offline sales. Up to 500 events per request.

curl -X POST https://t.myshop.com/v1/events \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "event_name": "Purchase",
      "event_id": "order-1042",
      "consent": true,
      "event_source_url": "https://www.myshop.com/checkout",
      "user_data": {
        "em": "jane@example.com",
        "client_ip_address": "203.0.113.7",
        "client_user_agent": "Mozilla/5.0 …"
      },
      "custom_data": { "value": 49.90, "currency": "EUR" }
    }]
  }'

Response: {"accepted": 1, "duplicates": 0, "skipped_no_consent": 0, "errors": []}

• consent must be true for each event: you confirm the person consented.
• action_source defaults to website; other Meta values (system_generated, physical_store, email…) are accepted. Website events need event_source_url.
• event_time (Unix seconds) is optional and must be within the last 7 days.
• Values already hashed with SHA-256 are passed through unchanged.

Endpoints

Configuration

Privacy and your responsibilities

CAPI Relay runs on your own infrastructure; you are the controller of the data it processes. Under the GDPR and ePrivacy rules, server-side tracking does not remove the need for consent. Before going live:

• make sure your cookie banner calls capi('consent', …) and that your Meta Pixel only loads after consent;
• mention Meta's Conversions API in your privacy policy;
• respect Meta's Business Tools Terms (for example, do not send sensitive data such as health information).

Stored: the Meta-formatted event (hashed contact data, IP address, user agent, fbp/fbc, your custom_data), delivery status and Meta's error messages, for RETENTION_DAYS only. Never stored: events without consent, raw emails or phone numbers.

FAQ