A referral click is only useful if the affiliate still gets credit when the customer reaches checkout. Rewardful referral cookies store that attribution in the visitor’s browser, then give your signup and billing flow a referral ID to pass forward.
The setup is simple when your marketing site, app, and payment flow share one domain. It needs tighter controls when you use separate domains, custom URLs, or Stripe Checkout. Start with the supported Rewardful controls. Add custom application code only where it has a clear job.
How Rewardful Referral Cookies Work
Rewardful uses first-party cookies for referral tracking. A visitor arrives through an affiliate URL such as https://example.com/?via=partner-token. Rewardful reads the valid via token, creates the referral, and stores its ID for later use.
The current referral ID is available in the browser through Rewardful.referral. If the visitor has no valid referral, the value is an empty string. Review the Rewardful JavaScript API before adding custom code around this value.
Install the tracking script on every entry page
Add Rewardful’s dashboard-provided bootstrap snippet and tracking script to every public page where an affiliate may land. That normally includes the homepage, pricing page, blog, signup page, and campaign landing pages.
Don’t load the script only on checkout. By then, the original via parameter may be gone. The cookie must exist before the visitor moves through your funnel.
If you accept legacy or alternate affiliate links, Rewardful supports the data-rewardful-params script attribute. This lets the script recognize parameters such as rfsn or ref alongside your standard links.
Set the cookie window in the campaign
Rewardful’s default cookie window is 60 days. Change it in Campaigns, open the campaign, then edit Cookie window. This is the supported way to control referral-cookie duration.
The cookie window settings should match your real sales cycle. A 14-day window may work for a low-cost self-serve product. A B2B product with demos, procurement, and annual contracts may need more time.
Rewardful does not document a JavaScript option for setting a custom cookie name or expiry date. Don’t write directly to a cookie that imitates Rewardful’s attribution record.
A separate app cookie can support your own interface logic. It does not replace Rewardful attribution.
Configure Attribution Rules Before You Send Links
Your cookie setup and attribution rule need to match. Rewardful campaigns support First Touch Attribution and Last Touch Attribution. First touch keeps the original affiliate. Last touch gives credit to the most recent qualifying affiliate.
Set this before affiliates begin promoting. Changing the rule during an active campaign creates support work and payout disputes.
Use via for affiliate links
Give affiliates their normal Rewardful URLs with the via parameter. Don’t substitute UTM values for referral tracking. UTM parameters help analytics tools classify traffic, but Rewardful does not use them to create referrals.
Use UTMs as an addition, not a replacement. A working link can include both values, such as ?via=partner-token&utm_source=affiliate&utm_campaign=launch.
Use direct page tracking with care
Rewardful also documents direct page tracking for cases where your application already knows the affiliate token. The supported command is:
rewardful('source', 'partner-token')
This overwrites an existing referral stored in the browser. Use it only when your business rule requires a known source to replace the previous one. Don’t fire it automatically after every login, form completion, or page view.
A safer custom pattern reads the referral without changing it:
const referralId = window.Rewardful?.referral || "";
Store that value temporarily in your app state only if you need it for signup or checkout. Treat it as an attribution identifier, not a user permission or account credential.
Track Visitors Across Domains
Subdomains are the easy case. Install the Rewardful script on each relevant subdomain, such as www.example.com and app.example.com. Rewardful can then track referrals across those subdomains.
Separate top-level domains need configuration. If your marketing site is on example.com and checkout runs on examplecheckout.com, add the data-domains attribute to the Rewardful tracking script. List the approved domains as comma-separated values.
Let Rewardful pass the referral ID
With data-domains configured, Rewardful appends referral=<UUID> to links between the domains. The receiving domain reads that value and restores the referral context.
Follow Rewardful’s cross-domain tracking instructions instead of building your own query-string transfer. A custom redirect can strip parameters, create duplicate attribution, or expose an ID to domains that should never receive it.
Test the whole route in a clean browser profile:
- Open a valid affiliate link on the marketing domain.
- Click through to the app or checkout domain.
- Confirm the referral remains available through
Rewardful.referral. - Complete a controlled test purchase and inspect the Rewardful record.
Pass the Referral ID Into Stripe Checkout
A browser cookie records the visit. Your billing integration connects that visit to the customer and subscription. For client-side Stripe Checkout, Rewardful documents passing the referral ID as Stripe’s clientReferenceId.
Use this before calling Stripe Checkout:
if (window.Rewardful?.referral) checkoutParams.clientReferenceId = window.Rewardful.referral;
Then send checkoutParams through your existing checkout call. The Stripe Checkout client-side guide shows the full pattern.
Keep browser data in its lane
Don’t use a browser-supplied referral ID to grant discounts, unlock admin access, or calculate a payout in your own code. The browser can be modified. Use it only as the documented handoff value for your payment flow.
For server-side Checkout, send the referral ID to your server through an authenticated request. Validate the request context, log the expected value, and pass it using Rewardful’s documented Stripe method. Keep the original test record and any correction as separate entries. Don’t overwrite the first result when attribution changes.
Troubleshooting Referral Cookie Failures
Check these items before you contact support:
- Confirm the landing URL contains a valid
viatoken or a validreferral=<UUID>value. - Test in an incognito window with extensions disabled. Ad blockers and strict browser settings can block scripts or storage.
- Check that the Rewardful script loads on the original landing page, not only after signup.
- Verify the campaign cookie window has not expired.
- Review First Touch or Last Touch settings before calling an attribution result incorrect.
- Confirm every cross-domain destination is listed in
data-domains. - Inspect the Stripe Checkout session for the expected
client_reference_id.
Build a reproducible support record. Save the landing URL, campaign name, affiliate token or referral ID, test date, browser, checkout session, report date range, and screenshots. State the expected result and the result you received.
Final Checks Before You Scale
Rewardful referral cookies work when the landing page, campaign rule, domain path, and checkout handoff all agree. Configure the cookie window in Rewardful. Keep custom code limited to reading Rewardful.referral and passing it through supported billing fields.
Run controlled tests before publishing affiliate links. A clean test record is more useful than a dashboard full of clicks you can’t reconcile.
