RefCampaign SDK Documentation

Track affiliate conversions seamlessly with automatic session ID capture and Stripe metadata injection. Set up your entire affiliate tracking system in under 5 minutes.

Installation

Install the RefCampaign SDK using your preferred package manager:

npm install @refcampaign/sdk
# or
pnpm add @refcampaign/sdk
# or
yarn add @refcampaign/sdk

Browser Setup (Client-Side)

Capture affiliate session IDs automatically from cookies, URL parameters, or localStorage.

1. Initialize the SDK

Import and initialize RefCampaignBrowser with your public key. This should be done once when your app loads.

app/layout.tsx

import { RefCampaignBrowser } from '@refcampaign/sdk'

// Initialize with your public key
RefCampaignBrowser.init({
  publicKey: 'pk_test_your_key_here'
})

2. Capture the session ID

Call captureSession() on page load to automatically detect and store the affiliate session ID.

// Capture session ID on page load
const { sessionId, source } = RefCampaignBrowser.captureSession()

console.log(`Session captured from ${source}:`, sessionId)
// → Session captured from url: abc123
// → Session captured from cookie: xyz789

Complete Next.js Example

app/layout.tsx

'use client'

import { useEffect } from 'react'
import { RefCampaignBrowser } from '@refcampaign/sdk'

export default function RootLayout({ children }) {
  useEffect(() => {
    // Initialize SDK
    RefCampaignBrowser.init({
      publicKey: process.env.NEXT_PUBLIC_REFCAMPAIGN_PUBLIC_KEY
    })

    // Capture session ID
    RefCampaignBrowser.captureSession()
  }, [])

  return (
    <html>
      <body>{children}</body>
    </html>
  )
}

Server Setup (Backend)

Use RefCampaignServer to inject session IDs into Stripe metadata for automatic conversion tracking.

1. Initialize the server SDK

import { RefCampaignServer } from '@refcampaign/sdk'

const rc = new RefCampaignServer(process.env.REFCAMPAIGN_SECRET_KEY)

2. Get Stripe metadata

Generate metadata to inject into your Stripe checkout sessions:

// Get session ID from cookie
const sessionId = req.cookies.get('_rc_sid')?.value

// Generate Stripe metadata
const metadata = rc.getStripeMetadata(sessionId)

// Returns: { refcampaign_session: 'abc123' }

Stripe Integration

This is where the magic happens. By adding RefCampaign metadata to your Stripe checkout, every successful payment automatically attributes commissions to the right affiliate.

Critical Step

You MUST include the RefCampaign metadata in your Stripe checkout for conversion tracking to work. Without it, affiliates won't receive credit for sales.

app/api/checkout/route.ts

import { NextRequest, NextResponse } from 'next/server'
import { RefCampaignServer } from '@refcampaign/sdk'
import Stripe from 'stripe'

const rc = new RefCampaignServer(process.env.REFCAMPAIGN_SECRET_KEY!)
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

export async function POST(req: NextRequest) {
  // Get session ID from cookie
  const sessionId = req.cookies.get('_rc_sid')?.value

  // Get price from request
  const { priceId } = await req.json()

  // Create Stripe checkout
  const checkout = await stripe.checkout.sessions.create({
    line_items: [{ price: priceId, quantity: 1 }],

    // 🎯 CRITICAL: Inject RefCampaign metadata
    metadata: rc.getStripeMetadata(sessionId),

    mode: 'subscription',
    success_url: `${process.env.NEXT_PUBLIC_APP_URL}/success`,
    cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
  })

  return NextResponse.json({ url: checkout.url })
}

That's it!

RefCampaign automatically tracks conversions via Stripe webhooks when it detects the refcampaign_session metadata. No additional code needed.

API Reference

RefCampaignBrowser

init(config: RefCampaignBrowserConfig): void

Initialize the browser SDK with your public key and optional debug mode.

RefCampaignBrowser.init({
  publicKey: 'pk_test_...',  // Required
  debug: true                 // Optional
})

captureSession(): SessionCaptureResult

Capture and store the affiliate session ID from URL parameters, cookies, or localStorage. Returns the session ID and its source.

const { sessionId, source } = RefCampaignBrowser.captureSession()
// source: 'url' | 'cookie' | 'localStorage' | 'none'

getSessionId(): string | null

Retrieve the current session ID from localStorage.

const sessionId = RefCampaignBrowser.getSessionId()

RefCampaignServer

getStripeMetadata(sessionId?: string): StripeMetadata

Generate Stripe metadata object with the RefCampaign session ID. Pass this to Stripe checkout sessions for automatic conversion tracking.

const metadata = rc.getStripeMetadata('abc123')
// Returns: { refcampaign_session: 'abc123' }

Environment Variables

You need two API keys to use RefCampaign: a public key for browser-side code and a secret key for server-side code.

.env.local

# Public key (safe to expose in browser)
NEXT_PUBLIC_REFCAMPAIGN_PUBLIC_KEY=pk_test_...

# Secret key (server-side only, NEVER expose in browser)
REFCAMPAIGN_SECRET_KEY=sk_prod_...

Security Warning

Never expose your secret key in browser code or commit it to version control. Only use it in server-side code.

Get your API keys

Get API Keys

Support & Resources

Need help? We're here for you.