server-side-conversion-tracking

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: server-side-conversion-tracking
description: Set up server-side conversion tracking so purchases are reported accurately to Facebook, TikTok, Google and Bing despite iOS restrictions, ad blockers and cookie loss. Use when conversions are under-reported, when platform-reported purchases do not match real orders, when asked about Conversions API / Events API / offline conversions / CAPI, click id passthrough (fbclid, ttclid, gclid, msclkid), or when ad optimization has degraded after tracking changes.
---

# Server-Side Conversion Tracking

Browser pixels lose a large and unpredictable share of conversions to iOS tracking prevention, ad blockers, cookie lifetime limits and cross-domain hops. Server-side reporting fixes the *reporting*, which is what the ad platform's bidding model learns from. This skill covers the model, the setup order and how to verify it.

## When to use

- Ad platform reports fewer purchases than the store/database actually recorded
- CPA looks like it got worse right after a tracking change, with no change in real sales
- Setting up a new funnel that will receive paid traffic
- Asked about CAPI / Events API / offline conversion import / click id passthrough
- Attribution disagreements between platforms ("Facebook claims 40 sales, Google claims 30, we had 45 orders")

## The model, in the order it must be built

Getting this order wrong is the usual reason a "server-side setup" still under-reports.

```
1. Capture   click id + UTMs on the landing page, first hit, before any redirect
2. Persist   attach them to the visitor's session, server-side
3. Carry     keep them across every funnel step, including cross-domain hops
4. Attach    write them onto the order record at purchase
5. Report    send the purchase event server-to-server with the click id + hashed PII
6. Dedupe    give the browser event and the server event the same event id
7. Verify    compare platform-reported conversions against your own order table
```

Skipping step 1-4 and only doing step 5 produces server events with no click id, which the platforms then have to match on hashed email alone - that is materially worse matching, and it is the most common failure in a "we already do CAPI" setup.

### Step 1-2: capture and persist

| Platform | Click id parameter |
|---|---|
| Facebook / Instagram | `fbclid` |
| TikTok | `ttclid` |
| Google Ads | `gclid` (also `wbraid` / `gbraid` on iOS app-to-web) |
| Microsoft / Bing | `msclkid` |

Also capture, on the same first hit: `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, the full landing URL, referrer, user agent, and the client IP as seen by the server. Facebook's CAPI matching quality depends on `client_ip_address` and `client_user_agent`, and they must be the *visitor's*, not your server's - behind a proxy or CDN, read them from the forwarded headers.

Store server-side, keyed to a first-party session. Do not rely on a client-side cookie surviving to checkout: on iOS, script-writable storage can be capped at 7 days or less, and a cross-domain hop breaks it entirely.

### Step 3: carry across steps

- Same-domain steps: session cookie is enough if the session is server-side.
- Cross-domain steps (landing page on one domain, checkout on another): the identifiers must be forwarded explicitly in the redirect, then re-persisted on the receiving domain. This is where most funnels silently lose attribution.
- Redirect chains: every hop must preserve the query string. A tracking redirect that drops `?fbclid=...` destroys attribution for that entire campaign.

### Step 4: attach to the order

The order record must carry the click ids, UTMs and landing URL. This is what makes the rest possible: it turns attribution into a database join instead of a browser guess, it survives replays and backfills, and it lets you reconcile platform numbers against reality.

### Step 5: report server-to-server

| Platform | Endpoint / mechanism | Credentials needed |
|---|---|---|
| Facebook