For brands and partners
Tracking and attribution
A partner link records a click and sends the visitor to your site with ?ref= and ?vp_click= in the address. When the sale is reported with that click id, coupon code or referral code, the sale is credited to the partner, as long as the click is inside the program's cookie window.
What happens on a click
- A visitor opens
/r/<handle>/<program>(or an older/r/<code>link). - If the partner is approved and the program is live, a click is recorded with a new click id.
- The visitor is sent to the program's destination with
?ref=<handle>&vp_click=<click id>added. A link may carry?to=<page>to land on another page of the same site. - Two first-party cookies,
vp_refandvp_click, are set on the ViralPayouts domain for the length of the cookie window.
ref and vp_click from the landing address, keep them (for example in your own cookie or the cart), and send them with the sale.What is not counted as a click
Crawlers, link-preview fetchers, uptime monitors, requests with no user agent, HEAD requests, browser prefetches, a repeat from the same visitor on the same partner within a few seconds, and floods from one address. These visitors are still redirected with ?ref=, but get no click id and no cookies, and the partner sees them in a "filtered" count.
How a sale is matched
Nothing is guessed. A sale is credited by the first of these that matches:
- Renewal: a payment for a subscription whose first payment was already credited goes to the same partner, inside the program's renewal period.
- Coupon code: a partner's code typed at checkout, while the offer is on, even with no link.
- Click id (
vp_click), if the click is inside the cookie window. - Referral code (
ref): the partner's handle or older link code.
A sale that matches nothing is recorded as unmatched, with the reason, so you can see it on the Integration tab. A second event with the same order id is a duplicate and is ignored.
Cookie window, first click and last click
| Setting | What it does |
|---|---|
| Cookie window | How long after a click a sale still counts: 7 to 365 days, 30 by default. The cookies last as long. |
| Last click (default) | The most recent partner link the visitor followed gets the sale. |
| First click | A vp_fc_<program id> cookie remembers the first click for the cookie window. Later partner links still count as clicks, but your site is sent the first click's id and code, so the first partner gets the sale. |
Sub IDs
A link takes sub1, sub2, sub3, sub4, sub5 (sub, subid and sub_id also work for the first). Each is trimmed to 80 characters, kept with the click and copied to the sale. An event you send may carry its own sub IDs; any it leaves out are taken from the click.
Coupons and renewals
- Turn coupons on in the program to give every approved partner a code: their handle plus your suffix (for example
AJSMITH15). Download the list as CSV for your checkout. A code stops earning when the offer ends. - Renewals earn for the period you choose: first payment only, a number of months, or for as long as the customer pays. Send the same
subscription_idon every payment (the Stripe integration does this for you).
Sales from Paddle, Polar, Dodo Payments, Creem, Lemon Squeezy and RevenueCat
If you sell through one of these, sales can come in the moment they happen, with nothing to send yourself. In the console, open Verify your sales, choose the provider, and create one webhook in its dashboard to the address shown there (/api/sales/<provider>/<program id>), ticking the events listed. Then paste the webhook's signing secret (for Lemon Squeezy and RevenueCat, ViralPayouts makes the secret for you to paste there). Every event is checked against the provider's own signature; refunds and lost chargebacks reduce the commission like any other refund. A payment the webhook delivered is never credited again by the hourly read of the same account.
| Provider | Where to create the webhook | How the checkout carries the partner |
|---|---|---|
| Paddle | Paddle, Developer tools, Notifications, New destination (type URL) | customData on Paddle.Checkout.open(), set from the vp_click and ref values ViralPayouts adds to your page address; Paddle copies it onto every renewal |
| Polar | Polar, Settings, Webhooks, Add Endpoint (format Raw) | checkout metadata vp_click and ref (or point partner links at a Polar checkout link: ViralPayouts adds reference_id, which Polar copies onto the order) |
| Dodo Payments | Dodo Payments, Developer, Webhooks, Add endpoint | checkout session metadata vp_click and ref, set from the vp_click and ref values ViralPayouts adds to your page address |
| Creem | Creem, Developers, Webhooks, Add webhook | checkout metadata vp_click and ref; Creem keeps it on the subscription and sends it with every webhook event, so one-off and subscription sales are credited live (the hourly read finds subscription payments) |
| Lemon Squeezy | Lemon Squeezy, Settings, Webhooks, add a webhook | checkout[custom][vp_click] and checkout[custom][ref] on the checkout link, set from the vp_click and ref values ViralPayouts adds to your page address |
| RevenueCat | RevenueCat, Integrations, Webhooks, Add new configuration (environment: Production) | a subscriber attribute vp_ref (or vp_click) the app sets with Purchases.setAttributes from the link that opened it; RevenueCat sends it with every purchase and renewal. Attributes are set by the app itself, so treat app sales as reported, not proven |
Fraud checks
A sale is flagged, not blocked, when the buyer's email matches the partner's, or when the click came from an address your console or the partner's portal was used from. You decide when you approve.
Something here does not match what you see in the product? Email max@viralpayouts.com.