Skip to main content

Quick Start

Get from zero to a working affiliate setup in under 30 minutes. This guide walks you through adding the Selgeo tracking snippet to your website, connecting it to Stripe, and verifying your first test conversion.

API Version: v1

Prerequisites​

  • A Selgeo merchant account
  • Access to your website's HTML (or tag manager)
  • A Stripe account connected to Selgeo (for Stripe-based conversion tracking)

Step 1: Obtain your API keys​

Log in to the Selgeo merchant dashboard and navigate to Settings > API Keys. You will see two key pairs:

Key typeFormatPurpose
Public key (test)pk_test_*JS snippet on your website (test mode)
Public key (live)pk_live_*JS snippet on your website (live mode)
Secret key (test)sk_test_*Server-side API calls (test mode)
Secret key (live)sk_live_*Server-side API calls (live mode)

Public keys (pk_*) are safe to embed in frontend code. They can only register clicks.

Secret keys (sk_*) must never be exposed to the browser. Use them only on your server.

Start with test keys

Use pk_test_* and sk_test_* while integrating. Test mode tracks everything the same way but creates no real commissions. Switch to live keys when you are ready to go live.

Step 2: Add the tracking snippet​

Add the following <script> tag to every page of your website, just before the closing </body> tag:

<script
  async
  src="https://cdn.selgeo.com/v1/selgeo.js"
  data-merchant="pk_test_YOUR_KEY"
></script>

Replace pk_test_YOUR_KEY with your actual public key from Step 1.

For your framework, see the dedicated guide​

The <script> tag above works on any HTML page. If you build on a modern frontend stack, the equivalent integration is one of the following guides:

  • HTML / plain script — static sites, tag managers, custom server-rendered pages.
  • Next.js — next/script for App Router and Pages Router.
  • React (Vite) — index.html placement, with a useEffect fallback.
  • WordPress — Site Editor, footer.php, or a header-footer plugin.

What the snippet does:

  1. When a visitor arrives via a partner referral link (e.g., https://your-site.com/?ref=abc123), the snippet registers the click with Selgeo and stores a click_id in the browser's sessionStorage.
  2. If you use Stripe Payment Links, the snippet automatically appends the click_id to those links as client_reference_id -- no backend work needed.
  3. The snippet is cookieless. It uses sessionStorage only, which is cleared when the browser tab closes. No cookie consent banner required.

Step 3: Verify your installation​

  1. Create a tracking link in the Selgeo dashboard under Programs > Tracking Links.
  2. Open a new browser tab and visit your site using the tracking link, e.g.: 
    https://your-site.com/?ref=YOUR_TRACKING_REF
  3. Open your browser's Developer Tools (F12) and check the Console tab. If you added data-debug to your script tag, you will see log messages from the snippet: 
    [selgeo] ref detected YOUR_TRACKING_REF
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  4. To enable debug mode temporarily, add the data-debug attribute: 
    <script
      async
      src="https://cdn.selgeo.com/v1/selgeo.js"
      data-merchant="pk_test_YOUR_KEY"
      data-debug
    ></script>
  5. Verify the click_id is stored by running this in the browser console: 
    __selgeo.getClickId()
    This should return a UUID string. If it returns null, the snippet did not detect a ?ref= parameter in the URL.
  6. Check the Selgeo dashboard -- the click should appear in Analytics within a few seconds.
Remove data-debug before going live

The data-debug attribute is for development only. Remove it in production to keep the browser console clean.

Step 4: Track conversions via Stripe​

Selgeo supports three Stripe integration paths. Choose the one that matches your setup:

If you use Stripe Payment Links (buy.stripe.com URLs), the snippet handles everything automatically.

How it works: The snippet detects all <a> tags pointing to https://buy.stripe.com/... and appends ?client_reference_id=CLICK_ID to them. When the customer completes payment, Stripe includes the client_reference_id in the webhook payload, and Selgeo matches it to the partner who referred the click.

No backend code needed. Just make sure the snippet is loaded on the page where the Payment Link appears.

<!-- Your existing Payment Link -- the snippet rewrites it automatically -->
<a href="https://buy.stripe.com/test_abc123">Subscribe Now</a>

After the snippet runs, the link becomes:

https://buy.stripe.com/test_abc123?client_reference_id=CLICK_ID

For a detailed walkthrough, see Stripe Payment Links guide.

Option B: Stripe Checkout (one line of frontend code)​

If you create Stripe Checkout Sessions on your server, you need to pass the click_id from the browser to your backend.

Frontend -- read the click ID from the snippet:

const clickId = __selgeo.getClickId();

// Send it to your backend when the user initiates checkout
fetch('/api/create-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    priceId: 'price_xxx',
    clickId: clickId, // may be null if no referral
  }),
});

Backend -- pass it as client_reference_id when creating the Checkout Session:

const stripe = require('stripe')('sk_test_YOUR_STRIPE_KEY');

app.post('/api/create-checkout', async (req, res) => {
  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    line_items: [{ price: req.body.priceId, quantity: 1 }],
    success_url: 'https://your-site.com/success',
    cancel_url: 'https://your-site.com/cancel',
    client_reference_id: req.body.clickId || undefined,
  });
  res.json({ url: session.url });
});

Selgeo reads client_reference_id from the Stripe webhook automatically. For the full guide, see Stripe Checkout guide.

Option C: Non-Stripe conversions (Conversion API)​

For conversions that do not go through Stripe (form submissions, free trials, custom events), use the Conversion API to report them from your server:

curl -X POST https://api.selgeo.com/api/v1/conversions \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "CLICK_ID_FROM_FRONTEND",
    "external_transaction_id": "signup_12345",
    "event_type": "signup",
    "amount_cents": 0
  }'

Step 5: Test a conversion end-to-end​

Run through the full cycle in test mode to confirm everything works:

  1. Create a test program in the Selgeo dashboard with at least one partner and a tracking link.
  2. Click the tracking link in a fresh browser tab. This registers a click and stores a click_id.
  3. Complete a purchase using one of the methods above:
    • Payment Links: Click a Stripe Payment Link on your site. Use Stripe test card 4242 4242 4242 4242.
    • Checkout: Trigger your checkout flow. The click_id is passed as client_reference_id.
    • Conversion API: Send a POST /api/v1/conversions request from your server with the click_id.
  4. Check the dashboard: Navigate to Analytics in the Selgeo dashboard. You should see:
    • The click registered under the partner
    • The conversion attributed to the partner
    • A commission calculated (if commission rules are configured)
Stripe test cards

Use Stripe's test card numbers to simulate payments without real charges. The most common one is 4242 4242 4242 4242 with any future expiration date and any CVC.

What's next?​

  • Snippet Setup -- advanced snippet configuration (SPAs, debug mode, custom API URL)
  • Stripe Metadata -- pass click_id through Checkout Session metadata (alternative to client_reference_id)
  • Conversion API -- full API reference for non-Stripe conversions
  • Test Mode -- detailed guide for testing your integration
  • Go-Live Checklist -- steps to switch from test to live mode