Attribution integration guide

1. Capture the ref parameter

When a customer arrives from an affiliate link (e.g. https://yoursaas.com/pricing?ref=ABCD1234), capture the ref value. Store it in a cookie or session so it persists until checkout.

// Run on page load - captures ?ref=CODE and stores in cookie (30 days)
const params = new URLSearchParams(window.location.search);
const ref = params.get('ref') || params.get('ref_code');
if (ref) {
  document.cookie = `affiliate_ref=${ref}; path=/; max-age=${30 * 24 * 60 * 60}`;
}

Add this to your signup or pricing page—or a shared layout that runs on pages where affiliates send traffic.

2. Pass to Stripe metadata

When creating the Stripe customer or subscription, read the ref from your cookie/session and add it to metadata. Referish will resolve it to the affiliate and attribute the commission.

Supported metadata keys: ref, ref_code, affiliate_id (UUID)

// Read ref from cookie (client) or session (server)
const refCode = document.cookie.match(/affiliate_ref=([^;]+)/)?.[1];

// When creating a Stripe customer
const customer = await stripe.customers.create({
  email: customerEmail,
  metadata: { ref: refCode || undefined },
});

// Or when creating a subscription
const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: priceId }],
  metadata: { ref: refCode || undefined },
});

3. Optional: Resolve ref to affiliate_id

If you prefer to pass affiliate_id (UUID) instead of ref_code, call our API first:

GET https://referish.com/api/attribution/resolve?ref=ABCD1234&accountId=YOUR_ACCOUNT_UUID

// Response: { "affiliateId": "uuid-here", "refCode": "ABCD1234" }

// Then use affiliateId in Stripe metadata:
metadata: { affiliate_id: response.affiliateId }

4. Webhook handles the rest

When an invoice is paid, our webhook reads the metadata (from invoice, subscription, or customer), resolves the affiliate, and creates a commission. No extra work on your side.