How do I offer a longer free trial to customers referred by affiliates?

Yes. This works with every payment provider natively supported by Affonso. Affonso identifies the affiliate referral; your checkout code decides the trial length in the payment provider.

For example, you can give everyone a 15-day trial and give customers referred by an affiliate a 30-day trial.

1. Detect the affiliate referral when creating checkout

When a visitor arrives through an affiliate link, Affonso stores the referral ID in the affonso_referral cookie. Read that cookie on your server when you create the checkout or subscription.

Use the presence of that referral to choose the trial length. Then pass the same referral value into the payment provider's metadata or custom-data field, following that provider's Affonso integration guide.

The checkout API and trial parameter differ by provider, but the decision is always the same:

const trialPeriodDays = affiliateReferral ? 30 : 15;

Stripe example

Stripe Checkout uses subscription_data.trial_period_days for the trial and metadata.affonso_referral for attribution:

import { cookies } from 'next/headers';

const cookieStore = await cookies();
const affiliateReferral = cookieStore.get('affonso_referral')?.value;
const trialPeriodDays = affiliateReferral ? 30 : 15;

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: priceId, quantity: 1 }],
  success_url: `${appUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${appUrl}/pricing`,
  subscription_data: {
    trial_period_days: trialPeriodDays,
  },
  metadata: affiliateReferral
    ? { affonso_referral: affiliateReferral }
    : {},
});

The Stripe metadata key must be exactly affonso_referral.

For another native provider, use the matching integration guide to pass affonso_referral and set its trial duration:

• Stripe
• Polar
• Paddle
• Creem
• Dodo Payments

What about affiliate coupon codes?

An affiliate coupon can also be used for attribution. Before you create the Checkout Session, have your backend determine whether the coupon being applied belongs to an affiliate, then use that result when selecting trialPeriodDays.

Do not trust a browser-provided isAffiliate flag for a trial benefit. Make the decision in your server-side checkout code, using the referral cookie and/or a coupon you have verified as an affiliate coupon. With Stripe Checkout, an affiliate coupon takes precedence for Affonso attribution when both are present.

See Auto-Apply Affiliate Coupons at Checkout for passing an affiliate coupon into your payment-provider checkout.

2. Test the complete flow

1. Open your site through an affiliate link and confirm the affonso_referral cookie exists in browser DevTools.
2. Start checkout and verify the payment-provider checkout includes the affonso_referral value in the field required by its integration guide.
3. Confirm the resulting subscription has a 30-day trial. A normal, non-referred checkout should have a 15-day trial.
4. Complete a live checkout and confirm the referral is attributed in Affonso.

For general tracking diagnostics, see Troubleshooting affiliate tracking.