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.

// Example: store ref in cookie when user lands
const params = new URLSearchParams(window.location.search);
const ref = params.get('ref');
if (ref) {
  document.cookie = `affiliate_ref=${ref}; path=/; max-age=2592000`;
}

2. Pass to Stripe metadata

When creating the Stripe customer or subscription, add the ref to metadata. Referish will resolve it to the affiliate and attribute the commission.

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

// When creating a Stripe customer
const customer = await stripe.customers.create({
  email: customerEmail,
  metadata: {
    ref: refCode,  // e.g. "ABCD1234" from affiliate link
  },
});

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

3. Optional: Resolve ref to affiliate_id

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

GET http://localhost:3000/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.