Checkout Sessions

If your server creates Stripe Checkout Sessions, add one line so Stripe carries the referral to Supaffi. Payment Links, buy buttons and pricing tables need only the script: see Payment Links and pricing tables.

Add the referral to metadata

Wherever you create the Checkout Session, server side, read the __supaffi_referral cookie and pass it in the session metadata under supaffi_referral. This is the snippet the Tracking page shows under Checkout:

const referralToken = cookies.get("__supaffi_referral");

await stripe.checkout.sessions.create({
  // ...your existing options
  metadata: {
    // ...your existing metadata
    ...(referralToken && { supaffi_referral: referralToken }),
  },
});

• Keep any metadata you already set. Add the key next to it.
• When the visitor has no referral, the key is left out and the sale is simply not referred.
• Supaffi does not use client_reference_id for this, so you can keep your own value there.
• It works for one-time payments and subscriptions alike.

Copy AI prompt on the Tracking page copies instructions you can paste into a coding assistant to make the change for you.

Examples

The same change in two common setups. Your options, prices and URLs stay as they are.

import { cookies } from "next/headers";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST() {
  const referralToken = (await cookies()).get("__supaffi_referral")?.value;

  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    line_items: [{ price: "price_123", quantity: 1 }],
    success_url: "https://yourapp.com/welcome",
    metadata: {
      ...(referralToken && { supaffi_referral: referralToken }),
    },
  });

  return Response.json({ url: session.url });
}

Exclude a customer or sale

To stop a payment from earning a commission, set the metadata key supaffi to false (lowercase) on the invoice, the subscription or the customer in Stripe.

Set it before the customer pays. For a subscription, add it in subscription_data.metadata when you create the Checkout Session:

await stripe.checkout.sessions.create({
  // ...your existing options
  subscription_data: {
    metadata: { supaffi: "false" },
  },
});

• A flag added after payment only excludes later renewals.
• A one-time purchase can only be excluded through its customer or its post-purchase invoice.

Keep the script and checkout on one site

The referral cookie is first-party: it belongs to the site where the visitor landed from the affiliate link. The code that creates the Checkout Session must receive that cookie, so it has to run on the same site as the tracking script.

Payments that do not go through Stripe Checkout or a Payment Link do not earn: custom Stripe Elements checkouts, invoices sent by hand, and subscriptions created in the Stripe Dashboard or the API without Checkout. See What earns a commission.