Integration
Polar analytics: see which channel your paying customers came from
Polar tells you what you sold. Peregrine tells you which channel found the buyer. Connect Polar with one token and every paid order is credited to the visit that first brought that person to your site, even if they paid weeks later.
How it connects
- Add the Peregrine tag to your site. Links to your Polar checkout are stamped with the visitor’s id automatically.
- In Polar, create an access token with the orders:read scope and nothing else, then paste it into Peregrine. It is checked against Polar before it is saved, so a typo or a missing scope tells you immediately instead of by quietly reporting no sales.
- That is all. There is no webhook to register, no endpoint and no event to choose.
How a sale is credited
The tag adds your visitor’s id to the Polar checkout link as reference_id. Polar returns it with the order, and Peregrine matches it to that visitor’s first visit.
If you create Polar checkouts on your own server, read the peregrine_vid cookie from the request and pass it as metadata.reference_id. If the cookie is missing, create the checkout as before.
import { cookies } from 'next/headers';
const visitor = (await cookies()).get('peregrine_vid')?.value;
// when you create the checkout:
metadata: { reference_id: visitor }What you see
- Which channel sent the most visitors, beside which channel earned the most money.
- Your last 30 days of orders on the first sync, so a new dashboard is not empty. Those orders predate the tag, so their channel shows as unattributed: the money is right and the channel is blank.
- Only paid orders. Each one is dated when it happened, not when Peregrine read it.
- Orders are fetched when you open the dashboard, and anything created in between is picked up then.
What to know
- An order refunded before Peregrine reads it is never recorded, and a refund issued afterwards is not unwound.
- The token can read your orders, so it is stored encrypted. Give it the one scope and no other.
- A sandbox token works against sandbox orders, and they are flagged as test.
- Verified end to end with a real order in Polar’s sandbox.
Questions
How do I see which channel my Polar customers came from?
Add the Peregrine tag to your site and connect Polar with an orders:read token. The tag stamps the visitor’s id onto your Polar checkout links, Polar returns it as reference_id on the order, and Peregrine credits the sale to that visitor’s first visit.
Do I need to set up a Polar webhook?
No. Peregrine reads your orders from Polar when you open the dashboard, so there is no endpoint to register and no event to choose.
Which Polar token scope does Peregrine need?
Only orders:read. The token is checked against Polar when you paste it, so a wrong scope is reported immediately.
Does it work with the Polar sandbox?
Yes. A sandbox token works against sandbox orders, and they are flagged as test.
Why does an older order show no channel?
Orders from before the tag was installed carry no visitor id, so they show as unattributed. The amount is right and the channel is blank, which is the true answer.