K

Documentation

Add affiliate tracking to your website in minutes.

Emil Klitmose

Written by Emil Klitmose

Updated recently

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.revshare.so/tracking.js"
  data-program-id="YOUR_PROGRAM_ID"
  data-domain=".yourdomain.com"
  data-cookie-duration="30"
></script>

The data-domain enables tracking across subdomains (e.g., example.com and app.example.com). Replace with your domain, keeping the dot prefix.

Using different domains? If your landing page and app have completely different domains (like mysite.com → myapp.io), pass the ?ref=CODE in your redirect URL.

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.

We use last-click attribution. The cookie only resets when a user clicks a new referral link.

How cookies work

New referral click: When a user clicks a link with ?ref=... in the URL, the script sets a new cookie. This overwrites any existing cookie and resets the expiration date starting from now.

No new click: If a user returns to your site without a ?ref= parameter, the existing cookie is preserved. The affiliate who originally referred them still gets credit.

Last-click attribution

Day 1: User clicks ?ref=affiliate1 → cookie set for affiliate1

Day 5: User clicks ?ref=affiliate2 → cookie overwritten, affiliate2 gets credit

Day 10: User purchases → affiliate2 earns commission

Browser limits: While you can set data-cookie-duration up to 365 days, most browsers cap cookies to ~180 days due to Intelligent Tracking Prevention (ITP) and similar privacy policies. Safari is particularly strict.

Stripe Checkout

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.

Shopify Integration

For Shopify stores, use our dedicated tracking script that automatically handles cart attributes and checkout.

<script
  async
  src="https://www.revshare.so/shopify-tracking.js"
  data-program-id="YOUR_PROGRAM_ID"
  data-cookie-duration="30"
></script>

Add this script to your Shopify theme. Go to Online Store → Themes → Edit code → theme.liquid and paste it before the closing </head> tag.

How Shopify tracking works

1. The script captures ?ref=CODE from the URL and stores it in cookies + localStorage

2. It automatically injects ref_code and program_id into cart attributes

3. When checkout completes, our webhook receives the order with attribution data

4. Commission is calculated and credited to the affiliate

Dual storage: The script uses both cookies and localStorage as backup. This ensures tracking persists even if cookies are blocked or cleared.

Cart token sync

The script syncs the Shopify cart token with our server. This provides a fallback if cart attributes are lost during checkout (some themes clear attributes).

window.revshare_ref // the current ref code

Access the ref code via window.revshare_ref if you need it for custom integrations.

Referral API

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

Endpoint: POST https://www.revshare.so/api/referral

Header: x-api-key: YOUR_API_KEY

Find your API key in Dashboard → Account & Billing. The same key works for all your programs.

await fetch("https://www.revshare.so/api/referral", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.REVSHARE_API_KEY,
  },
  body: JSON.stringify({
    ref_code: refCode,           // from frontend
    program_id: "YOUR_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 Revshare distinguish first purchases from repeat customers.

Environment Variable

Add your API key to your environment variables:

REVSHARE_API_KEY="your_api_key_here"

Never expose your API key in client-side code. Always call the API from your backend.

Connect to Any Provider

Works with Paddle, Lemon Squeezy, Gumroad, Polar, Dodo, Razorpay, or any payment provider with 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 → your payment provider 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 your payment provider sends a 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.revshare.so/api/referral', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': process.env.REVSHARE_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 pattern is the same for any provider. 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.

Lead Tracking

Track form submissions and pay affiliates for qualified leads. Perfect for lead generation programs.

Endpoint: POST https://www.revshare.so/api/leads/submit

Header: x-api-key: YOUR_API_KEY

Find your API key in Dashboard → Account & Billing.

// Example: Call when form is submitted
await fetch("https://www.revshare.so/api/leads/submit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.REVSHARE_API_KEY,
  },
  body: JSON.stringify({
    program_id: "YOUR_PROGRAM_ID",
    ref_code: window.revshare_metadata?.ref_code, // from tracking script
    lead_data: {
      name: formData.name,
      email: formData.email,
      phone: formData.phone, // optional
      company: formData.company, // optional
      message: formData.message, // optional
      // Add any other form fields
    },
  }),
});

Request Body

program_id string, required

ref_code string, required — affiliate referral code from tracking script

lead_data object, required — must include email at minimum

• lead_data.email is required

• All other fields in lead_data are optional

How it works: The tracking script automatically captures the ref_code from the URL (?ref=CODE) and stores it in window.revshare_metadata.ref_code. When a form is submitted, call the API with this ref code to attribute the lead to the affiliate.

Important: Always call the API from your backend to keep your API key secure. Never expose it in client-side code.

Lead Approval

In your program settings, you can choose to auto-approve every lead or manually review each submission. Approved leads generate commissions for affiliates.