Stripe Checkout Integration

Track conversions from Stripe Checkout Sessions

Table of Contents

Stripe Checkout Integration

For the most reliable conversion tracking, pass the AffiliateBase referral ID to Stripe Checkout using client_reference_id. This guide shows you how.

How It Works

  1. Visitor clicks an affiliate link → referral ID stored in browser
  2. Visitor starts checkout → you pass referral ID to Stripe
  3. Payment completes → Stripe webhook notifies AffiliateBase
  4. Conversion attributed → affiliate earns commission

Prerequisites

Before starting:

Implementation

Step 1: Get the Referral ID

The tracking script stores the referral ID in window.affiliatebase_referral:

// Get current referral ID
const referralId = window.affiliatebase_referral;

Step 2: Pass to Checkout Session

When creating a Stripe Checkout Session, include the referral ID:

// Server-side (Node.js example)
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

app.post('/create-checkout-session', async (req, res) => {
  const { referralId } = req.body;

  const session = await stripe.checkout.sessions.create({
    line_items: [{
      price: 'price_xxxxx',
      quantity: 1,
    }],
    mode: 'payment',
    success_url: 'https://yoursite.com/success',
    cancel_url: 'https://yoursite.com/cancel',
    // Pass the referral ID here
    client_reference_id: referralId || undefined,
    // Recommended: always create a customer
    customer_creation: 'always',
  });

  res.json({ url: session.url });
});

Step 3: Client-Side Request

Send the referral ID from the browser:

// Client-side
async function startCheckout() {
  const referralId = window.affiliatebase_referral;

  const response = await fetch('/create-checkout-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ referralId }),
  });

  const { url } = await response.json();
  window.location.href = url;
}

Complete Example

React Component

function CheckoutButton({ priceId }) {
  const handleCheckout = async () => {
    // Get referral ID from tracking script
    const referralId = window.affiliatebase_referral;

    const response = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        priceId,
        referralId
      }),
    });

    const { url } = await response.json();
    window.location.href = url;
  };

  return (
    <button onClick={handleCheckout}>
      Subscribe Now
    </button>
  );
}

Next.js API Route

// pages/api/checkout.js
import Stripe from 'stripe';

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

export default async function handler(req, res) {
  const { priceId, referralId } = req.body;

  const session = await stripe.checkout.sessions.create({
    line_items: [{ price: priceId, quantity: 1 }],
    mode: 'subscription',
    success_url: `${req.headers.origin}/success`,
    cancel_url: `${req.headers.origin}/pricing`,
    client_reference_id: referralId || undefined,
    customer_creation: 'always',
  });

  res.json({ url: session.url });
}

For Subscriptions

Subscription tracking works the same way:

const session = await stripe.checkout.sessions.create({
  line_items: [{
    price: 'price_monthly_xxxxx',
    quantity: 1,
  }],
  mode: 'subscription', // Subscription mode
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel',
  client_reference_id: referralId || undefined,
  customer_creation: 'always',
});

Affiliates earn commission on:

  • Initial subscription payment
  • Recurring payments (if recurring commissions enabled)

Using Form Submission

If you prefer form-based checkout, use the data-affiliatebase attribute:

<form action="/create-checkout" method="POST" data-affiliatebase="true">
  <input type="hidden" name="price_id" value="price_xxxxx">
  <button type="submit">Buy Now</button>
</form>

The tracking script automatically injects a hidden referral_id field.

Best Practices

Always Include customer_creation

customer_creation: 'always'

This ensures Stripe creates a customer record even for one-time payments, which helps with:

  • Tracking returning customers
  • Subscription upgrades
  • Refund handling

Handle Missing Referral IDs

// Only include if referral exists
client_reference_id: referralId || undefined

Don’t pass empty strings or null—use undefined so Stripe ignores the field.

Validate on Server

For security, consider validating the referral ID server-side:

// Optional: Validate referral ID format
const isValidReferral = (id) => {
  return id && typeof id === 'string' && id.length > 0;
};

client_reference_id: isValidReferral(referralId) ? referralId : undefined

Testing

  1. Click an affiliate link to set the referral
  2. Check window.affiliatebase_referral has a value
  3. Start checkout process
  4. Complete purchase with test card 4242 4242 4242 4242
  5. Verify conversion appears in AffiliateBase dashboard

Troubleshooting

Referral ID is undefined

  • Ensure tracking script is loaded before checkout
  • Check you’re not on localhost (tracking doesn’t work locally)
  • Verify the affiliate link was clicked

Conversion not appearing

  • Check Stripe webhook logs for delivery status
  • Verify client_reference_id was included in session
  • Ensure webhook endpoint is configured correctly

See Conversions Not Tracking for more help.

Next Steps