Know what must work before you launch
Connect client-side referral capture to a server-created Stripe Checkout Session
- Best fit
- Teams evaluating AffiliateBase for a Next.js affiliate workflow.
- Checkout handoff
- The checkout path must receive the generated AffiliateBase referral ID.
- Proof required
- Complete one referred checkout and confirm the attributed sale and commission.
Follow the attribution evidence
Illustrative scenario · fictional values
-
Referred visit
?via=partner
AffiliateBase captures the visit and generates a referral record.
-
Checkout handoff
referral ID
The checkout must carry the generated identifier into Stripe.
-
Paid event
$99 paid
A supported Stripe event confirms the attributed payment.
-
Commission
$19.80 due
An eligible attributed sale creates the commission record.
-
Payout prep
Payout ready
Review the commission and prepare the next step with your payout provider.
This guide is for teams building their own merchant affiliate program in a Next.js application. It covers the App Router and the same client/server boundary also applies to Pages Router projects.
AffiliateBase captures the generated referral ID in the browser. A Route Handler, Server Action, or API route cannot read that browser value unless the client submits it. The server then creates Stripe Checkout with that generated ID, not the public token in the affiliate link.
Next.js documents sitewide third-party scripts in the root layout. Pair that placement with the Stripe handoff instructions and the verification checklist.
Implement and test the browser-to-server handoff:
Map the Checkout Request
Identify the Client Component that starts checkout and the server boundary that creates the Stripe Checkout Session. Hosted checkout alone does not preserve affiliate state.
Load the Tracking Script
Use Next.js’s supported Script component in the root or sales-route layout, preserving the account ID and data attributes from your AffiliateBase snippet.
<script async src="https://app.affiliatebase.io/track.js" data-account-id="YOUR_ACCOUNT_ID"></script>Submit the Generated Referral ID
Read the generated referral ID in the browser and include it in the checkout request. Validate it on the server, set Stripe client_reference_id, and mirror it to the documented AffiliateBase metadata fields.
Test a Fresh Browser Session
Open the exact generated test affiliate link, start checkout from the tracked page, and complete a test-mode payment through the same server route used in production.
Confirm Sale and Commission
Verify the checkout event contains the generated UUID and that AffiliateBase creates the expected sale and commission. Test recurring billing separately.
What the Next.js Integration Separates
Client Referral Capture
The browser owns the affiliate click and generated referral state.
Server Checkout Creation
Your protected Stripe secret and Checkout Session creation remain server-side.
End-to-End Proof
A completed test checks the handoff, webhook processing, sale, and commission together.
Next.js Affiliate Tracking Questions
Can a Server Component read window.AffiliateBase?
Should client_reference_id contain the ?via value?
Does loading the script prove checkout attribution?
Related platform guides
Stripe Affiliate Program Setup
Run an affiliate or referral program on Stripe. Connect your account, give partners referral links or promo codes, and track recurring commissions.
Add Affiliate Tracking to a React Checkout
Capture affiliate referrals in a React app, send the generated referral ID to your checkout backend, and verify Stripe attribution.
Add an Affiliate Program to Remix
Capture referrals in a Remix app, submit the generated referral ID through an action, and verify Stripe checkout attribution.
Verify Your Next.js Checkout Path
Test one referral through the same client and server path your customers use.