Connect Polar

Polar sends paid and refunded orders to a webhook signed with the endpoint's secret. Checkout metadata links each order to the visit that started it.

Set up the webhook

1. Copy the webhook URL

   In MetricRaven, open Settings → Integrations → Polar and copy the webhook URL.

2. Add an endpoint in Polar

   In your Polar organization, open Settings → Webhooks → Add Endpoint. Paste the URL, choose the Raw format, and select order.paid and order.refunded. For subscription goals, also select subscription.created, subscription.active, subscription.updated, subscription.canceled, subscription.uncanceled and subscription.revoked.

3. Paste the secret in MetricRaven

   Copy the endpoint's secret from Polar, paste it into the Polar card and choose Connect Polar.

Pass the visitor ID at checkout

Polar copies checkout metadata to the order. Use these keys, and set externalCustomerId to your user ID so it matches the Identify API:

1. Read the visitor ID in the browser

   The MetricRaven script exposes window.analytics.getVisitorId(). Read it when checkout starts and send it to your checkout code:

   script.js

   Copy

   1

   2

   3

   4

   // Read this in the visitor's browser when they start checkout.
   const visitorId = window.analytics?.getVisitorId() ?? null;
   // Send visitorId to your own checkout endpoint alongside its usual request data.
   // Use the authenticated user ID from your backend; do not trust a browser-supplied user ID.

2. Add it to the checkout

   Checkout API

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   // Server: create a checkout with the Polar SDK (@polar-sh/sdk).
   const checkout = await polar.checkouts.create({
     products: ["YOUR_PRODUCT_ID"],
     successUrl: "https://example.com/success",
     // Your authenticated user's ID; Polar returns it as customer.external_id.
     externalCustomerId: user?.id,
     metadata: visitorId ? { metricraven_visitor_id: visitorId } : {},
   });
   // Redirect the visitor to checkout.url

   For a checkout link, pass the visitor ID as reference_id; Polar adds it to the order metadata:

   Checkout link

   Copy

   1

   2

   3

   4

   5

   // Browser: Polar copies ?reference_id= from a checkout link into the order metadata.
   const url = new URL("https://buy.polar.sh/YOUR_CHECKOUT_LINK_ID");
   const visitorId = window.analytics?.getVisitorId();
   if (visitorId) url.searchParams.set("reference_id", visitorId);
   window.location.href = url.toString();

MetricRaven links each payment to a visit using the first of these that is available:

1. The metricraven_visitor_id passed through checkout.
2. The metricraven_user_id (or the provider's customer external ID), matched to a visitor you linked with the Identify API.
3. An earlier payment from the same provider customer, so renewals keep the original attribution.
4. The checkout email, matched to an email you sent to the Identify API.
5. The checkout email, matched to a browser that called payment({ email }) within an hour of the payment.

Can't set metadata on your checkout? See Other Polar methods to match by the buyer's email.