> ## Documentation Index
> Fetch the complete documentation index at: https://f82cc46-productmetrics.manicule.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://f82cc46-productmetrics.manicule.dev/docs/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://f82cc46-productmetrics.manicule.dev/docs/api/mcp.
> Every agent surface: https://f82cc46-productmetrics.manicule.dev/docs/.well-known/llms-manifest.json

# Server-side tracking and profit bidding on a custom store (webhooks) (/docs/platforms/custom-store)

<!-- agent-signals: reading_time_min: 11 · est_tokens: 4555 · updated: 2026-11-16 -->
Related: [Connect your store: Shopify, WooCommerce, Magento, Lightspeed, Shopware or any website](/docs/platforms/overview.md), [Shopify server-side tracking and profit bidding (POAS)](/docs/platforms/shopify.md), [WooCommerce server-side tracking and profit bidding (POAS)](/docs/platforms/woocommerce.md), [Magento server-side tracking and profit bidding (POAS)](/docs/platforms/magento.md), [Lightspeed eCom server-side tracking and profit bidding (POAS)](/docs/platforms/lightspeed.md), [Shopware server-side tracking and profit bidding (POAS)](/docs/platforms/shopware.md)

> Built your own store? Your backend sends every order to Product Metrics as a signed webhook, and server-side conversions go to Google Ads, Meta and ChatGPT Ads, so you can bid on profit, new customers or lifetime value.

**Custom Store / Webhook Integration** is for a store you built yourself. Your backend sends every order to Product Metrics when it's **paid, refunded or cancelled**, with its **product costs** and the **customer's order history**. Product Metrics adds **profit**, **new or returning customer** and **lifetime value**, and sends it server-side to each ad channel you connect.

Your site also runs **Cloudflare Tracking**. Your backend knows the order, but not which ad click brought the customer or what they chose in your cookie banner: only the browser knows that. So the tracking on your pages links each visit to its order, and the order itself comes from your backend.



* **Install:** Cloudflare sign-in, plus signed webhooks from your backend: a developer connects your checkout and backend. Everything else you do yourself, in Product Metrics and Cloudflare.
* **Product cost:** the cost price on each order line your backend sends.
* **Consent banner:** a supported banner (OneTrust, Cookiebot, Usercentrics or Osano), read on your pages.

## Prerequisites

* A website whose domain uses Cloudflare DNS, with its DNS record proxied (the orange cloud).
* A Cloudflare login for that account that can approve access. Product Metrics never changes your DNS.
* A developer who can change your store's checkout and backend.
* A [workspace](/docs/using/create-a-workspace) on [Pro](/docs/using/billing): connecting a store is part of Pro. A workspace admin signs in to Cloudflare.

On Shopify, WooCommerce, [Magento](/docs/platforms/magento), [Lightspeed](/docs/platforms/lightspeed) or [Shopware 6](/docs/platforms/shopware)? Use that platform's page: no developer work needed (Magento excepted).

## In the app

### 1. Add your store

Go to **Ecommerce platforms**, select **Connect** on **Custom Store / Webhook Integration** and enter the domain your customers visit, for example `www.example.com`.

**You should see:** the website under **Cloudflare Tracking**, with **Custom Store** chosen under **Order source**.

### 2. Send its orders to a property

Under **Storefront scopes**, link the property that should receive the orders.

### 3. Sign in to Cloudflare

In **Tracking**, under **Complete your tracking setup**, open **Connect Cloudflare**. A workspace admin:

1. Selects **Connect Cloudflare**, signs in to Cloudflare and approves Product Metrics.
2. Chooses the **Cloudflare account** and the **Cloudflare zone** your domain is in.
3. Selects **Set up gateway** and keeps the page open until it finishes.

Product Metrics adds the tracking to every page of your domain.

**You should see:** **Gateway setup complete**.

### 4. Turn on order webhooks

Under **Order source**, keep **Custom Store / Webhook Integration — send live order webhooks** chosen and select **Enable Custom Store**. Copy the **webhook endpoint** and the **signing secret** and give them to your developer through your password manager.

The signing secret is shown **once**. From now on your backend's orders count; purchases on your pages only link visits to orders.

**You should see:** **Current order source: Custom Store / Webhook Integration — live order webhooks** and **Webhook setup: Ready**.

### 5. Your developer connects checkout and backend

Your developer follows [For developers](#for-developers) below, or the **Developer quickstart: live orders** under **Order source**. They:

1. Save a tracking reference with each order at checkout, and report the same reference on the order confirmation page.
2. Send each order from your backend when it's paid, refunded or cancelled.
3. Send a first order to the **test webhook endpoint** and select **Check test delivery**.

**You should see:** **Test webhook verified**, with the event ID your developer sent.

### 6. Finish tracking setup

* **Consent**: choose your banner (OneTrust, Cookiebot, Usercentrics or Osano). See [Consent](/docs/using/consent).
* **Channels**: connect [Google Ads](/docs/channels/google-ads), [Meta](/docs/channels/meta) and [ChatGPT Ads (OpenAI)](/docs/channels/openai).
* **Google Ads conversion actions**: [create them](/docs/using/conversion-actions).
* **Additional costs**: product costs come with each order; [add the rest](/docs/using/costs): shipping, handling, returns and payment fees.

**You should see:** the badge next to **Tracking** read **Tracking active**.

### 7. Check it works

Place a real order and pay for it. Under **Order source**, select **Refresh order status**.

**You should see:** **Webhook delivery: Order received** with the time. More in [Check tracking](/docs/using/check-tracking).

## Set it up with AI



Paste the prompt into your assistant.



First connect the Product Metrics MCP server ([https://www.productmetrics.io/mcp](https://www.productmetrics.io/mcp); see [Connect your assistant](/docs/mcp/connect)).

**Claude or ChatGPT:** "Connect my custom store to Product Metrics with Custom Store / Webhook Integration. Check my setup status first, walk me through each open step, and give me the link when I need to sign in to Cloudflare."

**Claude Code or Codex:** "Connect my custom store to Product Metrics with Custom Store / Webhook Integration, then help me send signed order webhooks from our backend and pass the order proof at checkout, following [https://www.productmetrics.io/docs/platforms/custom-store](https://www.productmetrics.io/docs/platforms/custom-store). Use the Product Metrics MCP server, or the productmetrics CLI with --json and the Product Metrics skills if they are installed (run `productmetrics help agents` first)."

## How it works on a custom store

|                               | On a custom store                                                                  |
| ----------------------------- | ---------------------------------------------------------------------------------- |
| **Install**                   | Cloudflare sign-in for the tracking on your pages, plus webhooks from your backend |
| **Order source**              | Your backend's webhooks. Purchases on your pages only link each visit to its order |
| **Order sent**                | Every change: placed, paid, refunded or cancelled. Conversions count from payment  |
| **Product cost**              | The cost price your backend records on each order line when the order is placed    |
| **New or returning**          | From the order history your backend sends with each order                          |
| **Consent**                   | OneTrust, Cookiebot, Usercentrics or Osano, read on your pages                     |
| **Refunds and cancellations** | Your backend sends them; Product Metrics adjusts the conversion it sent            |
| **Earlier orders**            | Not imported: only orders paid after you turn on webhooks count                    |
| **Billing**                   | Part of [Pro](/docs/using/billing)                                                      |

If the visit never arrives, Product Metrics waits up to an hour after payment, then keeps the order without it. Without the ad click and the visitor's consent, that order may not reach your ad channels.

## What you get on a custom store

Each feature and its channels:



| Feature                                                                | Channels                                                                                      | On this platform                                                                                     |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [Server-side conversion tracking](/docs/features/ad-blocker-proof-tracking) | [Google Ads](/docs/channels/google-ads) · [Meta](/docs/channels/meta) · [ChatGPT Ads](/docs/channels/openai) | Sent once your backend reports the order paid, linked to the visit on your pages.                    |
| [Enhanced Conversions](/docs/features/enhanced-conversions)                 | [Google Ads](/docs/channels/google-ads) · [Meta](/docs/channels/meta) · [ChatGPT Ads](/docs/channels/openai) | From the hashed email, phone and billing address your backend sends, only with ad user data consent. |
| [Customer lists](/docs/features/customer-list)                              | [Google Ads](/docs/channels/google-ads)                                                            | Customer Match lists from the orders your backend sends.                                             |
| [POAS and ROAS bidding](/docs/features/poas-bidding)                        | [Google Ads](/docs/channels/google-ads) · [Meta](/docs/channels/meta) · [ChatGPT Ads](/docs/channels/openai) | Product costs from each order line, plus your [additional costs](/docs/using/costs).                      |
| [New customer bidding](/docs/features/new-customer-bidding)                 | [Google Ads](/docs/channels/google-ads) · [Meta](/docs/channels/meta)                                   | New or returning from the order history your backend sends.                                          |
| [Returning customer bidding](/docs/features/returning-customer-bidding)     | [Google Ads](/docs/channels/google-ads) · [Meta](/docs/channels/meta)                                   | Orders from customers who bought before, as their own conversion.                                    |
| [LTV bidding](/docs/features/ltv-bidding)                                   | [Google Ads](/docs/channels/google-ads) · [Meta](/docs/channels/meta) · [ChatGPT Ads](/docs/channels/openai) | Observed value from the paid orders your backend sends, not a prediction.                            |

## For developers

Send one **complete order snapshot** per change, as a `POST` to the webhook endpoint from step 4:

* **When**: each time an order is placed, paid, refunded or cancelled. A new `eventId` (UUID) per change and a higher `orderRevision` per order; a retry sends the same saved body again.
* **Whole order, every time**: all lines, totals and refunds so far, plus `customerHistory`: how many paid orders the customer had before this order's payment. Work it out once, at payment, and send the same values on every later snapshot.
* **Cost on every line**: `unitCost`, the cost price excluding tax when the order was placed. A missing cost is rejected; send `0` only for a known free item.
* **Money** is a JSON integer in micros (`12.34` is `12340000`), excluding tax, in the order's currency. Totals must add up exactly.
* **Customer** (optional): SHA-256 hashes of the email, phone and billing name, plus plain country and postcode. Never send raw personal data.
* **Visit link**: at checkout, create a random `orderProof` (32–128 letters, digits, `_` or `-`), save it with the order, send it in `tracking.orderProof`, and pass the same string to `sdk.purchase` on the confirmation page.



**Example order snapshot:**

```json
{
  "schemaVersion": 1,
  "eventId": "019c0000-0000-7000-8000-000000000101",
  "orderRevision": 1,
  "occurredAt": "2026-10-21T10:01:00Z",
  "order": {
    "id": "order-1001",
    "transactionId": "ORDER-1001",
    "status": "paid",
    "createdAt": "2026-10-21T10:00:00Z",
    "paidAt": "2026-10-21T10:01:00Z",
    "currency": "EUR",
    "taxBasis": "exclusive",
    "customerId": "customer-42",
    "lines": [
      {
        "lineId": "line-1",
        "productId": "product-10",
        "variantId": "variant-10-blue",
        "quantity": 2,
        "currentQuantity": 2,
        "subtotalExTaxMicros": 100000000,
        "discountExTaxMicros": 10000000,
        "taxMicros": 18000000,
        "refunds": [],
        "unitCost": {
          "amountMicros": 20000000,
          "sourceReference": "order-1001:line-1:cost-at-sale",
          "observedAt": "2026-10-21T10:00:00Z"
        }
      }
    ],
    "totals": {
      "subtotalExTaxMicros": 100000000,
      "discountExTaxMicros": 10000000,
      "shippingExTaxMicros": 10000000,
      "shippingTaxMicros": 2000000,
      "taxMicros": 20000000,
      "totalMicros": 120000000,
      "refundedShippingExTaxMicros": 0,
      "refundedShippingTaxMicros": 0,
      "refundedTotalMicros": 0
    }
  },
  "customerHistory": {
    "priorQualifyingOrderCount": 0,
    "historyComplete": true,
    "evaluatedBefore": "2026-10-21T10:01:00Z"
  },
  "tracking": { "orderProof": "checkout_RandomOpaqueTokenWith32CharsMinimum" }
}
```

### Sign each request

Sign the exact bytes you send: `X-PM-Signature` is the lowercase hex HMAC-SHA256 of `timestamp + "." + body`, keyed with the signing secret. The timestamp is Unix seconds and must be within five minutes; re-sign each retry.

```js
import { createHmac } from "node:crypto";

const body = JSON.stringify(snapshot);
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", process.env.PM_SIGNING_SECRET)
  .update(`${timestamp}.${body}`)
  .digest("hex");

const response = await fetch(process.env.PM_WEBHOOK_URL, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-PM-Timestamp": timestamp,
    "X-PM-Signature": signature,
  },
  body,
});
```

### Responses

| Response                    | What to do                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| `202`                       | Accepted. Mark the event sent                                                              |
| `200`                       | Already received, or older than a revision already received. Mark it sent                  |
| `400`                       | Fix the field the response names; don't resend unchanged                                   |
| `401`                       | Check the secret, the exact body and your clock                                            |
| `409`                       | An ID, revision or customer history changed, or the order was paid before webhooks were on |
| `429`, `5xx` or no response | Resend the same body later, with a fresh timestamp and signature                           |

Keep the signing secret on your server. **Rotate signing secret** stops the old one at once.

## Troubleshooting

| Problem                                                        | Fix                                                                                                                                                            |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **"Webhook setup isn't finished"**                             | Select **Rotate signing secret** to finish it, and give your developer the new secret.                                                                         |
| **"Couldn't enable Custom Store"**                             | If it says **Connecting a store is part of Pro**, start [Pro](/docs/using/billing), then select **Enable Custom Store** again.                                      |
| **"Awaiting first live order"**                                | Your backend hasn't sent a paid order yet, or Product Metrics rejected it. A rejected order returns its error to your backend: ask your developer to check it. |
| **"No test webhook verified with the current signing secret"** | After **Rotate signing secret**, earlier tests no longer count. Your developer sends a new test signed with the new secret.                                    |
| **Orders from before you turned on webhooks don't appear**     | That's expected: only orders paid after you selected **Enable Custom Store** count. There's no import of earlier orders.                                       |
| **Fewer conversions than paid orders**                         | Check that the confirmation page reports the same tracking reference your backend sends, and that [consent](/docs/using/consent) names the banner your store shows. |
| **"Proxy the storefront DNS record first"**                    | Turn on the orange cloud for your domain's DNS record in Cloudflare, then choose the zone again.                                                               |

## FAQ

### Do I need a developer for a custom store?

Yes. A developer connects your checkout and sends orders from your backend as signed webhooks. Everything else, including the Cloudflare sign-in, you do yourself.

### Why does a custom store also need Cloudflare Tracking?

Your backend knows the order, but not which ad click brought the customer or what they chose in your cookie banner. The tracking on your pages links each visit to its order.

### What happens when an order is refunded or cancelled?

Your backend sends the updated order, and Product Metrics adjusts the conversion it sent.

### Where do product costs come from on a custom store?

From the cost price your backend sends on each order line, recorded when the order is placed. You add shipping, handling, returns and payment fees as [additional costs](/docs/using/costs).

## Where next



* [Google Ads](/docs/channels/google-ads): connect Google Ads and Merchant Center
* [Meta](/docs/channels/meta): send purchases through the Meta Conversions API
* [ChatGPT Ads (OpenAI)](/docs/channels/openai): send purchases through the OpenAI Conversions API
* [Costs](/docs/using/costs): add shipping, handling, returns and payment fees
* [Any website (Cloudflare)](/docs/platforms/cloudflare): without a backend, from the confirmation page alone
* [Other platforms](/docs/platforms/overview): compare every store platform

On the website: [Full Signal Tracking](https://www.productmetrics.io/server-side-tracking), [pricing](https://www.productmetrics.io/pricing), [supported platforms](https://www.productmetrics.io/platforms)

Developers: add the website with the [CLI](/docs/cli/commands#stores-and-tracking) or the [API](/docs/api/stores-and-tracking/tracking-create-website-installation); turning on webhooks is done in the app.
