Integrations

Stripe Checkout metadata

Code that passes the partner click to Stripe Checkout, one-time and subscription, plus a renewal handler for a Stripe webhook you host yourself.

View as Markdown

This guide has the code for the Stripe sale path. How Affitor reads these payments (the events, the lookup order, subscriptions and repeat purchases) is on the Stripe page. Other framework guides (Next.js, Express, etc.) link here for Step 3. If you need click capture or signup tracking first, start with the Next.js guide or the framework guide for your stack.

Info

The @affitor/sdk package is Beta. The documented happy-path works; report issues on GitHub.

Prerequisites

  • Your program ID (program menu → Program settings → Business)
  • A program API key (program menu → Program settings, then Developers → API keys)
  • Stripe Checkout or Stripe Billing already working in your app
  • Your Stripe account connected to the program (program menu → Program settings → Payments, Connect Stripe). Affitor then receives the account's events through Stripe Connect; you do not add a webhook

1. Capture clicks and track signups

These two steps are identical to the framework integration. Follow Step 1 and Step 2 in the Next.js guide, or your framework's equivalent.

The key thing to take away: when you call signup(userId) or trackLead({ customerExternalId: userId }), keep that userId: you will attach it to every Checkout Session as affitor_customer_key.

2. Attach Affitor metadata to the Checkout Session

When you create a Stripe Checkout Session on your server, attach three metadata fields: affitor_click_id, affitor_customer_key, and program_id.

How to read affitor_click_id server-side: the browser SDK stores the click id in a first-party cookie called affitor_click_id. Read it from the incoming HTTP request and forward it to your server. For example, in a Next.js Route Handler you can read cookies().get('affitor_click_id')?.value. In a plain Express handler you can read req.cookies.affitor_click_id.

Info

affitor_customer_key must be the same stable user ID you sent at signup: signup(userId) on the client, customerExternalId: userId on the server, and affitor_customer_key: userId in Stripe metadata are all the same field. Mismatching them breaks attribution.

One-time payment (mode: 'payment')

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  success_url: 'https://yoursite.com/success',
  cancel_url:  'https://yoursite.com/cancel',
  metadata: {
    affitor_click_id:      clickId,          // from the affitor_click_id cookie
    affitor_customer_key:  user.id,          // SAME id you used at signup
    program_id:            'YOUR_PROGRAM_ID',
  },
});

Affitor listens to the checkout.session.completed webhook event and attributes the payment automatically. No extra call needed.

Subscription (mode: 'subscription')

For subscriptions, put the same fields in subscription_data.metadata: an invoice carries the subscription's metadata, not the Checkout Session's (why subscriptions need it).

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  success_url: 'https://yoursite.com/success',
  cancel_url:  'https://yoursite.com/cancel',
  metadata: {
    affitor_click_id:      clickId,
    affitor_customer_key:  user.id,
    program_id:            'YOUR_PROGRAM_ID',
  },
  // The subscription's invoices (first payment and renewals) read the click from here
  subscription_data: {
    metadata: {
      affitor_click_id:      clickId,
      affitor_customer_key:  user.id,
      program_id:            'YOUR_PROGRAM_ID',
    },
  },
});

3. How Affitor attributes payments

Which Stripe events record a sale and how Affitor finds the partner, from the click in the metadata to the customer key, are on the Stripe page: the events and the lookup order.

4. Alternative: server-side tracking (non-Stripe)

If you are not using Stripe Checkout, or you need to report a sale from a different payment provider, report it from your server after the payment is confirmed: server-side tracking on the Stripe page, and Track Sale for every field.

Verify

Verify success
Browser
  • Open a partner link from your program. It carries the partner code in the Partner link parameter set on the Tracking settings page (?via= by default for new programs; programs created before October 16, 2026 keep ?aff=), and the tracker reads both ?via= and ?aff=. An affitor_click_id cookie is set
Network
  • At checkout, confirm the Stripe Session metadata contains affitor_click_id, affitor_customer_key, and program_id
Dashboard
  • The sale appears under your program's tracking events with the partner correctly attributed
If it doesn't work
  • Send a test sale straight to POST /api/v1/track/sale with additional_data: { test_mode: true } (the SDK's trackSale() has no field for it); a test sale creates no commission

Common mistakes

Common mistakes
  • Putting the click only in the session metadata of a subscription checkout. Affitor records subscription payments from invoices, which carry subscription_data.metadata, not the session's. On your own Checkout Session, put the click in subscription_data.metadata so it reaches the invoices. Without a click in invoice metadata, Affitor can still match an existing customer or use a valid Affitor client_reference_id from the subscription's Checkout Session, subject to account and program checks.
  • Different customer IDs at signup vs checkout: affitor_customer_key must equal the customerExternalId / customer_key you sent at signup.
  • Reading affitor_click_id from the wrong place on the server: it is a browser cookie, not a query param. Forward it from req.cookies or cookies() in your server handler.
  • Tracking a sale from the browser: sale tracking is server-side only. Stripe metadata and @affitor/sdk/server both run on your server.
  • Using a different program_id than the one in your init() call: all three metadata fields must reference the same program.

Appendix: self-hosted webhook

Subscription Renewals

If you self-host the Stripe webhook and call trackSale yourself (rather than relying on Affitor's Connect webhook), renewals need their own handler. The first payment fires as checkout.session.completed; every subsequent renewal arrives as a separate invoice.paid event with billing_reason: 'subscription_cycle'. Without a dedicated case, every renewal commission is silently missed.

Stripe copies the subscription_data.metadata you set at checkout creation onto the Subscription, and stamps it onto every renewal invoice. For a real server-side sale, customer_key matches a key already stored on a customer in your program. A default browser-only signup does not store it. Pass the subscription's affitor_click_id as clickId as well: a successful server-side sale does not save the customer key for later sales.

Two nuances matter:

  • Skip $0 renewals. 100%-off coupons and fully credit-covered cycles produce invoice.paid events with amount_paid of 0. The SDK rejects a non-positive amount, so guard against it.
  • Stripe Basil metadata path. Stripe API version Basil (2025-03-31+) moved subscription_details under invoice.parent. Pre-Basil accounts still expose it at the legacy top level (invoice.subscription_details). Read the Basil path first and fall back to the legacy one so the handler works on both.

The handler calls the server SDK:

import Affitor from '@affitor/sdk/server';
const affitor = new Affitor({ apiKey: process.env.AFFITOR_API_KEY! });

Add this as a separate case in the same Stripe webhook handler that processes checkout.session.completed:

case 'invoice.paid': {
  const invoice = event.data.object;
  // Only renewals: the first invoice is already counted at checkout.session.completed.
  if (invoice.billing_reason !== 'subscription_cycle') break;
  // Skip $0 renewals (100%-off coupons, fully credit-covered): the SDK rejects a non-positive amount.
  if (!invoice.amount_paid || invoice.amount_paid <= 0) break;
  // The Tracking API reads ISO 4217 minor units. Stripe uses the same units except ISK and UGX
  // (sent with two extra decimals) and MGA (sent with none), so convert those three.
  const c = invoice.currency; // lowercase from Stripe; Affitor reads it case-insensitively
  const amount = c === 'isk' || c === 'ugx' ? invoice.amount_paid / 100
    : c === 'mga' ? invoice.amount_paid * 100 : invoice.amount_paid;
  await affitor.trackSale({
    // Stripe Basil (2025-03-31+) moved subscription_details under invoice.parent;
    // read the Basil path first, fall back to the legacy top-level for pre-Basil accounts.
    customerExternalId: invoice.parent?.subscription_details?.metadata?.affitor_customer_key
      ?? invoice.subscription_details?.metadata?.affitor_customer_key,
    clickId: invoice.parent?.subscription_details?.metadata?.affitor_click_id
      ?? invoice.subscription_details?.metadata?.affitor_click_id,
    amount,                                 // ISO minor units of invoice.currency (cents for USD)
    currency: c,
    invoiceId: invoice.id,                  // idempotency key; a 409 means this id was used before (the API's error.details.sale_id: yours, or null for another program)
    isRecurring: true,
    saleType: 'subscription',
    // Basil relocated the subscription id under invoice.parent.subscription_details;
    // fall back to the legacy top-level invoice.subscription for pre-Basil accounts.
    subscriptionId: invoice.parent?.subscription_details?.subscription
      ?? (typeof invoice.subscription === 'string' ? invoice.subscription : invoice.subscription?.id),
  });
  break;
}
Info

This handler is only needed when you self-host sale tracking via trackSale. If Stripe is connected, Affitor already records each renewal from Stripe's events, so do not also call trackSale. Both record the renewal under the invoice id and Affitor refuses the second, but if your call lands first, its sale is not linked to the Stripe payment, so a refund in Stripe does not reverse its commission.

Next recommended step
Using Express or a non-Next.js server?

See the Node.js server guide (Express and Fastify) for server-side wiring.

Continue →

Share feedback

Tell us what is missing or unclear on “Stripe Checkout metadata”.

Last updated Nov 8, 2026