Docs
Revenue attribution
The tracker alone counts visitors. To see which channel brought the money, two things have to happen: Peregrine has to read your sales, and each sale has to carry the id of the visitor who made it. This page is about the second part.
How a sale finds its first visit
- The first time someone visits, the tracker gives them a random visitor id and keeps it in your site’s own cookie
peregrine_vidand in local storage. Peregrine records the channel they arrived from. - When they go to checkout, the id goes with them, as a reference the payment provider stores on the order.
- Peregrine reads the order from the provider, finds the reference, and credits the sale to the channel that first brought that visitor. That holds even if they paid weeks later, after arriving some other way.
Reading sales is one pasted key in Settings. Each provider has its own page: Polar, Lemon Squeezy and Dodo Payments.
How the id reaches checkout depends on how your buyers get there. There are three cases.
1. Checkout links: nothing to do
If your buy buttons are ordinary links to the provider’s checkout, the tracker adds the visitor id to them by itself:
| Provider | Links to | Parameter added |
|---|---|---|
| Polar | buy.polar.sh, polar.sh | reference_id |
| Lemon Squeezy | *.lemonsqueezy.com | checkout[custom][reference_id] |
| Dodo Payments | checkout.dodopayments.com | metadata_reference_id |
It changes the link’s href rather than catching the click, so middle-click, “copy link” and keyboard navigation carry the id too. Links that appear later, after a route change or when clicked, are tagged as well.
Keep them real links. A checkout opened from a click handler with window.location or window.open is never seen by the tracker, so it carries no id. Either make it an <a href>, or treat it as case 3.
To check: load your page, right-click the buy button, copy the link, and look for the parameter at the end.
2. Checkout on your own domain
Some providers let you serve checkout from your own address, such as buy.your-domain.com. Nothing in that URL says which provider it is, so the tracker does not touch it, and sales through it arrive with no channel and no error. Tell the tracker with data-checkout, as host:parameter:
<script defer src="…/js/peregrine.js" data-site="your-domain.com"
data-checkout="buy.your-domain.com:checkout[custom][reference_id]"></script>Use the parameter for your provider from the table above. Separate several hosts with commas. If you leave out :parameter, it is reference_id.
3. Checkouts created on your server
If your server creates the checkout session and sends the buyer to the URL it gets back, the tracker never sees a link. Your server attaches the id instead. The tracker keeps it in a cookie for exactly this reason: a server cannot read local storage.
// app/api/checkout/route.ts (Next.js). Any server works the same way:
// read the peregrine_vid cookie from the request and attach it to the checkout.
import { cookies } from 'next/headers';
export async function POST() {
const vid = (await cookies()).get('peregrine_vid')?.value;
const checkout = await createCheckout({
// ...your product, price and customer as before
...(vid && { metadata: { reference_id: vid } }) // Polar, Dodo Payments
});
return Response.json({ url: checkout.url });
}Where the id goes for each provider:
| Provider | Field on the checkout you create |
|---|---|
| Polar | metadata.reference_id |
| Lemon Squeezy | checkout_data.custom.reference_id |
| Dodo Payments | metadata.reference_id |
If the cookie is missing, because the visitor blocks cookies or arrived before you installed the tracker, create the checkout exactly as before. The sale is still recorded, just without a channel.
Sales without a reference
A sale that arrives with no visitor id is still counted. Its money appears in your totals and its channel is left blank, which is the honest answer. That includes the last 30 days of sales Peregrine reads when you first connect a provider, because those were made before the tracker existed.
If new sales keep arriving without a channel, the cause is almost always one of the three cases above: a checkout opened from JavaScript, a custom checkout domain, or a server-side checkout that does not attach the cookie.
Testing it
Test-mode orders are counted, so the whole chain can be checked before real money moves. Visit your site from a link with a utm_source you will recognise, buy in your provider’s test mode, and the sale should show up under that channel.
Stripe
Stripe is not supported yet. The tracker already adds client_reference_id to Stripe Payment Links and Checkout links, but Peregrine does not read Stripe sales.
More docs
- Install the tracker
- Goals and custom events
- Sale notifications on Telegram
- How channels are decided
- Bots and filtering
- What is collected
- Peregrine for Polar
- Peregrine for Lemon Squeezy
- Peregrine for Dodo Payments
Something missing? Write to us from the footer. Or see a real dashboard in the demo, or start a free trial.