Docs/Polar

Polar integration setup

Use signed Polar webhooks to send order and subscription events into Metrivo. Payment attribution stays confidence-labeled and does not invent matches.

Revenue Assurance reconciliation is not available for Polar: Metrivo has no read-only provider adapter for it, so Polar revenue is signed-webhook evidence only. Signed webhook attribution and lifecycle support remain available.

Signed inbound webhooks

Metrivo only needs the webhook signing secret. It is encrypted before storage and never rendered back after save. Polar signs deliveries with the Standard Webhooks scheme, and Metrivo verifies the signature before recording anything.

Setup steps

1. Open Metrivo Data Connections and generate the Polar webhook URL.
2. In your Polar dashboard, add a webhook endpoint and paste the Metrivo URL.
3. Select these events: order.paid, order.refunded, subscription.past_due, subscription.canceled, subscription.revoked.
4. Copy the signing secret Polar shows for that endpoint and save it in Metrivo.
5. Send a test delivery. Metrivo marks the provider active only after signature verification succeeds.

Polar retries a failed delivery up to 10 times with exponential backoff and disables an endpoint after 10 consecutive failures, so use the exact non-redirecting URL Metrivo generates.

Metadata for attribution

Pass Metrivo visitor/session identifiers through Polar checkout metadata. Polar copies that metadata onto the resulting order and subscription, so it arrives with the payment webhook. Without these fields, Metrivo may fall back to customer email or leave the payment unattributed.

// Client: send this object to your checkout endpoint
const metadata = window.Metrivo.getAttributionMetadata()

// Server: Polar copies checkout metadata onto the order and subscription
await polar.checkouts.create({
  products: ["<product_id>"],
  customer_email: "customer@example.com",
  external_customer_id: yourCustomerId,
  metadata: {
    ...metadata,
    plan: "growth"
  }
})

How Metrivo reads Polar events

order.paid is the only event that records revenue. Polar sends it once payment has actually been received.
order.created is ignored on purpose: it precedes order.paid for the same order, so counting both would double-count one payment.
order.refunded updates the existing payment instead of creating a new row. A partial refund is recorded as partially refunded rather than being treated as a full loss.
subscription.past_due is recorded as a failed payment so it appears in recovery reporting.
Other subscription and checkout events are stored as lifecycle evidence and carry no money.