Connect Polar

You need a Polar organization and a website in Revfaro with tracking installed. Open Website settings › Setup, go to Connect payments and choose the Polar tab.

These steps work with the script or npm SDK. With npm, initialize tracking on checkout and return pages. Use your shared tracker.attribution() to read visitor metadata in the browser; the SDK does not create window.revfaro.

1. Add the webhook in Polar

   In Polar, go to Settings › Webhooks and add an endpoint with your website's address from the Polar tab:

   Copy

   https://revfaro.com/api/webhooks/polar/YOUR_SITE_ID

   Set the format to Raw and select the events order.paid and order.refunded. Add it in your production organization; sandbox orders would count as real ones.

2. Paste the signing secret

   Copy the endpoint's signing secret (it starts with whsec_), paste it into Paste its signing secret and click Save. The tab shows Connected.

3. Pass the visitor to your checkout

   When your server creates a checkout, add the visitor's cookies as metadata and put {CHECKOUT_ID} in the success URL:

   checkout.tsCopy

   const jar = await cookies(); // next/headers
   
   await polar.checkouts.create({
     products: ['PRODUCT_ID'],
     successUrl: 'https://example.com/thanks?checkout_id={CHECKOUT_ID}',
     metadata: {
       rf_visitor_id: jar.get('rf_vid')?.value ?? '',
       rf_session_id: jar.get('rf_sid')?.value ?? '',
     },
   });

   Polar fills in {CHECKOUT_ID}, and Revfaro links the order to the visitor who lands on that page, even without metadata. Using the @polar-sh/nextjs checkout handler? Merge the same two keys into its metadata.

Using Checkout Links

Checkout Links (buy.polar.sh/…) need no code. When a visitor clicks one on your pages, the script adds reference_id=rf_<visitor id>__<session id>, unless the link already has your own reference_id. Polar copies it into the order's metadata.

Also set each link's success URL to:

https://example.com/thanks?checkout_id={CHECKOUT_ID}

so payments are matched on that page too. The page must load the script and must not be excluded.

One organization, several websites

A Polar organization sends every order to every webhook. Add the webhook to each website in Revfaro: a payment counts where its buyer was tracked, or where the same customer paid before. Orders with neither signal count on every website that has the webhook, so pass the visitor at checkout.

What Revfaro records

• Orders from order.paid.
• Renewals (billing_reason subscription_cycle) keep the visitor who subscribed, because Polar copies checkout metadata to the subscription.
• Refunds from order.refunded are subtracted, partial refunds included.