Integration Guide

Add affiliate tracking to your website in minutes.

1. Add the Tracking Script

Add this script to the <head> of your website. Replace the program ID with your own from the dashboard.

<script
  async
  src="https://www.revshares.app/tracking.js"
  data-program-id="YOUR_PROGRAM_ID"
></script>

2. Access Referral Data

The script automatically captures referral codes from URLs (?ref=CODE) and stores them in cookies. Access the data via:

window.revshare_metadata.program_id // your program ID

window.revshare_metadata.ref_code // affiliate's referral code

window.revshare_metadata.referrer // where visitor came from

Tip: Open your browser console and type console.log(window.revshare_metadata) to verify tracking is working.

3a. Stripe Checkout

Recommended

Pass the referral data as metadata when creating a Stripe Checkout session. We automatically track sales via webhook.

const session = await stripe.checkout.sessions.create({
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  metadata: window.revshare_metadata, // pass referral data
});

Connect your Stripe account in the dashboard to enable automatic tracking.

3b. Referral API

For custom payment providers, call our API directly when a sale is made.

Endpoint: POST https://www.revshares.app/api/referral

Header: x-api-key: YOUR_API_KEY

await fetch("https://www.revshares.app/api/referral", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    ref_code: window.revshare_metadata.ref_code,
    program_id: window.revshare_metadata.program_id,
    spent_amount: 5000,       // amount in cents
    currency: "USD",
    transaction_id: "order_123", // unique per transaction
    customer_id: "cust_456",  // optional: for recurring tracking
  }),
});

Request Body

ref_code string, required

program_id string, required

spent_amount integer, required — amount in cents

transaction_id string, required — unique per transaction

currency string, optional — defaults to USD

customer_id string, optional — for recurring revenue tracking

Important: Include customer_id if you track recurring revenue. This lets Revshares distinguish first purchases from repeat customers.

Paddle / Lemon Squeezy Integration

Here's how to integrate with Paddle, Lemon Squeezy, or any payment provider that supports webhooks.

TL;DR — The Flow

1. Visitor clicks affiliate link → yoursite.com?ref=john123

2. Our script saves the ref code → stored in cookie + window.revshare_metadata

3. Customer buys something → Paddle/Lemon Squeezy sends you a webhook

4. Your webhook handler calls our API → we handle the rest

Step 1: Pass ref_code to your checkout

When opening checkout, pass the referral data in custom_data (Paddle) or custom (Lemon Squeezy):

// Paddle example
Paddle.Checkout.open({
  items: [{ priceId: 'pri_xxx', quantity: 1 }],
  customData: {
    ref_code: window.revshare_metadata?.ref_code,
    program_id: window.revshare_metadata?.program_id,
  },
});

// Lemon Squeezy example
LemonSqueezy.Url.Open('https://yourstore.lemonsqueezy.com/buy/xxx', {
  custom: {
    ref_code: window.revshare_metadata?.ref_code,
  },
});

Step 2: Create a webhook handler

When Paddle/Lemon Squeezy sends a payment webhook, call our API:

// Example: /api/paddle-webhook (Next.js)
export async function POST(req) {
  const event = await req.json();
  
  // Verify webhook signature here...
  
  if (event.event_type === 'transaction.completed') {
    const { custom_data, details, customer_id, id } = event.data;
    
    // Only call if there's a ref_code (affiliate sale)
    if (custom_data?.ref_code) {
      await fetch('https://www.revshares.app/api/referral', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': process.env.REVSHARES_API_KEY,
        },
        body: JSON.stringify({
          ref_code: custom_data.ref_code,
          program_id: custom_data.program_id,
          spent_amount: details.totals.total, // amount in cents
          currency: details.totals.currency_code,
          customer_id: customer_id,  // for recurring tracking
          transaction_id: id,        // unique transaction ID
        }),
      });
    }
  }
  
  return Response.json({ received: true });
}

Tip: The same pattern works for Gumroad, Polar, Dodo, Razorpay, or any provider with webhooks. Just extract the sale amount, customer ID, and transaction ID from their webhook payload.

Recurring Revenue Tracking

To track recurring payments from the same customer, always pass the same customer_id.

TL;DR — How it works

Same customer_id = we know it's the same customer paying again.

Sale 1: { customer_id: "cust_abc", amount: 4900 } → First purchase ✓

Sale 2: { customer_id: "cust_abc", amount: 4900 } → Recurring ✓

Sale 3: { customer_id: "cust_abc", amount: 4900 } → Recurring ✓

Use whatever customer ID your payment provider gives you:

Paddle: event.data.customer_id

Lemon Squeezy: event.data.attributes.customer_id

Stripe: session.customer

Or use: Customer email as a fallback

Commission rules: In your program settings, you can configure whether affiliates earn commission on first purchase only, for X months, or lifetime.

Need help? Contact us at support@revshares.app