Implementing Margin-Value CAPI On Shopify Via The Order Paid Webhook
A working recipe for sending margin (not revenue) as the Purchase value to Meta's Conversions API, triggered by Shopify's orders/paid webhook with per-line COGS lookup.
Quick answer
Subscribe a serverless endpoint to Shopify's `orders/paid` webhook, look up COGS per line item (product cost field or a `cogs` metafield), subtract COGS + shipping refunds from net revenue to get margin, and POST a `Purchase` event to Meta's Conversions API with `value = margin` and `currency = order.currency`. Use the order ID as `event_id` to deduplicate against the browser pixel.
Margin-value CAPI on Shopify via the orders/paid webhook
A server-side pattern that sends true gross margin — not revenue — as the Purchase event value to Meta's Conversions API, triggered by Shopify's orders/paid webhook.
Meta's auction optimises toward whatever number you put in `value`. If that number is revenue, the algorithm chases high-AOV orders regardless of whether they make money. The fix is to send margin instead. On Shopify, the cleanest trigger is the `orders/paid` webhook: it fires once payment is captured, carries every line item with quantity and price, and gives your endpoint enough context to subtract COGS, discounts, and shipping costs before forwarding a Purchase event to CAPI. The native Shopify–Meta channel doesn't expose this hook, so the implementation lives in your own webhook handler.
This page assumes you already decided that sending margin to Meta is the right move — the parent topic, bidding to POAS on Meta when the platform only sees revenue, covers that strategic case. Here we focus on the Shopify-specific mechanics.
The reader we're writing for: a performance marketer or e-commerce engineer on a €2M–€10M Shopify store who has tried the native Meta sales channel, hit its ceiling, and now wants a server-side pipeline they control.
Why the native Shopify–Meta channel won't do this
Shopify's first-party Meta integration sends Purchase events with `value = total_price`. There's no setting, metafield, or app config that swaps revenue for margin. Meta receives the gross order value and bids accordingly.
If you want margin in `value`, you need a second pipeline that you own end-to-end: a webhook subscription, a handler with COGS access, and a CAPI POST. You then either deduplicate against the native channel using `event_id`, or disable the native Purchase event entirely and rely on yours.
Pick one source of truth for Purchase
Running the native Shopify channel AND your custom margin pipeline without coordinating `event_id` will double-count purchases in Meta. Either turn off Purchase in the native channel and own it fully, or send matching `event_id` values from both so Meta's deduplication merges them — and accept that Meta keeps the higher of the two values.
The pipeline, end to end
Step 1 — Register the webhook. In your Shopify custom app, subscribe to topic `orders/paid` pointing at a public HTTPS endpoint (Cloudflare Worker, Vercel function, AWS Lambda behind API Gateway). Shopify signs every request with `X-Shopify-Hmac-Sha256`; verify it before doing anything else or you've shipped an open relay.
Step 2 — Resolve COGS per line. For each `line_item`, look up cost. The order payload doesn't include it, so you call the Admin GraphQL API: `productVariant(id: ...) { inventoryItem { unitCost { amount } } }`. Cache variant→cost in KV or Redis; an apparel store with 2,000 SKUs will hit the same variants over and over.
Step 3 — Compute margin. Sum `(line.price − line.discount − unit_cost) × quantity` across line items, subtract shipping cost if you track it, then subtract payment-processor fees if you want true contribution margin. Floor the result at zero — never send negative `value` to Meta, it gets rejected.
Where to get COGS — ranked by reliability
COGS sources on Shopify, ranked by accuracy and operational cost
| Source | Accuracy | Setup effort | Best for |
|---|---|---|---|
| InventoryItem.unitCost (Admin API) | High — merchant-maintained | Low — already in Shopify | Stores already tracking cost per item |
| Custom product metafield `cogs.amount` | High — you control it | Medium — bulk-edit needed | Stores wanting a margin field separate from inventory cost |
| Category-level flat % (margin table) | Medium — 5-15% drift | Very low | Stores without per-SKU cost data yet |
| ERP / 3PL sync (Linnworks, Cin7) | Highest — landed cost | High — middleware required | €5M+ stores with real cost accounting |
| Hardcoded blended margin % | Low — masks SKU mix | Trivial | Day-one pilots only; replace within 30 days |
A practical pattern: start with `InventoryItem.unitCost` for SKUs that have it, fall back to a category-level percentage for the rest, and log which path each order took. Within a month you'll see which products need a real cost backfilled.
Building the CAPI Purchase payload
POST to `https://graph.facebook.com/v18.0/{pixel_id}/events`. Set `event_name = "Purchase"`, `event_time` from `order.processed_at`, `action_source = "website"`, `event_source_url` from the order's landing site URL, and crucially `event_id = order.id`. That `event_id` is what lets Meta deduplicate this server event against the browser pixel that fired at checkout.
In `custom_data`, set `value = margin` and `currency = order.currency`. Hash and pass `user_data`: `em` (email SHA-256), `ph` (phone), `fn`/`ln`, plus `fbp` and `fbc` if you captured them at checkout via a Shopify Web Pixel extension. Match quality drops fast without `fbp`/`fbc`, so capture them — don't skip this step.
Idempotency, retries, and the test-event tool
Shopify retries failing webhooks for 48 hours with exponential backoff. Your handler must be idempotent: log every processed `order.id` in a KV store with a 7-day TTL and short-circuit duplicates with a 200 OK. Without this, a transient CAPI error becomes 8 duplicate Purchase events over two days.
Before going live, set `test_event_code` on the CAPI payload and watch events land in Meta Events Manager → Test Events. Verify the `value` matches the margin you expect for a known order, that deduplication merges your server event with the pixel event, and that match quality is above 7.0. Then remove `test_event_code` and ship.
Implementation FAQ
Partially. Tools like Stape's GTM Server-Side or Elevar can receive the Shopify webhook and forward to CAPI, but rewriting `value` to margin requires a custom variable or transformation step that pulls COGS — which itself needs a data source. You end up writing logic somewhere; the question is whether it lives in Lambda or in a GTM custom JavaScript variable.
`orders/create` fires the moment a draft order or checkout completes, before payment capture. Cash-on-delivery, manual payment, and fraud-review orders that never actually pay would still send a Purchase to Meta. `orders/paid` fires only on successful payment capture, matching what Meta should optimise toward.
Subscribe to `refunds/create` and send a second CAPI event with a negative-equivalent action. Meta doesn't formally support negative Purchase values, so the common pattern is to fire a custom event `PurchaseRefunded` with the refund amount, and exclude refund-heavy customers from your retargeting audiences. Heavy returners distort margin bidding otherwise.
Yes. Subscription renewals via Shopify's native subscription API or apps like Recharge fire `orders/paid` on each successful charge. Your handler treats them like any other order. You may want to send a different `content_category` so Meta can distinguish first-purchase vs renewal in reporting.
`orders/paid` fires for all payment methods including Shop Pay, Apple Pay, and Google Pay. The complication is that accelerated checkouts often skip the order-confirmation page, meaning the browser pixel may not fire — making your server event the only signal Meta receives. That's an argument for getting the CAPI pipeline live before relying on pixel data.
Use a Shopify Web Pixel extension (the newer sandboxed approach) or a Customer Event listener to read the `_fbp` cookie and the `fbclid` URL parameter at checkout, then attach them to an order note attribute. They appear in the webhook payload under `note_attributes` and you read them in your handler.
Fall back through a hierarchy: product metafield `custom.cogs` → product type's category margin table → store-wide blended margin. Log which fallback fired per order; if more than 10% of orders use the blended fallback, your margin signal to Meta is noisy and you should backfill costs before trusting POAS bidding.
If your custom pipeline covers Purchase reliably, yes — at minimum disable the Purchase event there to avoid double-counting. Keep the native channel for catalog sync (DPA, Advantage+ Shopping) since that's a separate concern from event tracking. Catalog and events are independently configurable.
Expect a 7–14 day learning reset on existing campaigns. CPMs typically stay flat, CPA-on-revenue rises (because Meta is no longer chasing high-AOV low-margin orders), and POAS improves once the algorithm has ~50 margin-flagged conversions per ad set. Don't judge the switch in the first week.
Hashing email and phone is pseudonymisation, not anonymisation, so it's still personal data under GDPR. You need a lawful basis — consent from the cookie banner is the cleanest. Honour the consent flag: if a customer rejected marketing cookies, your webhook handler should either skip the CAPI POST for that order or send it without `user_data` identifiers.
Track CAC, channels, and funnel conversion in one place
Metricuno connects ad spend, funnel events, and revenue so you can see CAC by channel, cohort, and campaign — without stitching together five tools.