Integration Guides
Step-by-step guides for every Selgeo integration path. All guides use API version v1.
Selgeo integrates with your website and payment flow in two stages:
- Click tracking -- the JS snippet (
selgeo.js) records partner referral clicks and stores aclick_idin the visitor's browser. - Conversion tracking -- when the visitor converts (pays, signs up, submits a form), Selgeo attributes the conversion to the referring partner.
How you implement Stage 2 depends on your payment setup:
Choose your integration path
| Integration path | When to use | Backend work |
|---|---|---|
| Snippet Setup | Plain HTML, tag manager, or custom server-rendered pages | None |
| Next.js | App Router or Pages Router projects on Next.js | None |
| React (Vite) | Vite + React single-page applications | None |
| WordPress | Block themes, classic themes, or header-footer plugins | None |
| Stripe Payment Links | You use buy.stripe.com links on your site | None |
| Stripe Checkout | You create Checkout Sessions on your server | Minimal (pass client_reference_id) |
| Stripe Metadata | You use Checkout Sessions but need client_reference_id for your own purposes | Moderate (pass aff_click_id in metadata) |
| Conversion API | Non-Stripe conversions (signups, form submissions, custom events) | Moderate (server-side API call) |
| Webhooks | You want real-time notifications for domain events | Moderate (webhook endpoint + signature verification) |
Integration architecture
Every integration follows the same pattern:
┌─────────────────┐ ┌─────────────┐ ┌───────────────────┐
│ Visitor Browser │ │ Your Server │ │ Selgeo API │
│ │ │ │ │ │
│ 1. Clicks │────>│ │ │ Registers click │
│ partner link │ │ │ │ Returns click_id │
│ │ │ │ │ │
│ 2. Snippet │ │ │ │ │
│ stores │ │ │ │ │
│ click_id │ │ │ │ │
│ │ │ │ │ │
│ 3. User │────>│ 4. Create │────>│ 5. Selgeo reads │
│ converts │ │ Stripe obj │ │ click_id from │
│ (clicks buy) │ │ w/ click_id│ │ webhook/metadata │
│ │ │ │ │ and attributes │
└─────────────────┘ └─────────────┘ └───────────────────┘
For Stripe Payment Links, steps 3-5 happen automatically -- the snippet rewrites the link URL, and Selgeo reads client_reference_id from the Stripe webhook.
For the Conversion API, step 4 is a direct POST /api/v1/conversions call from your server to Selgeo instead of going through Stripe.
Key concepts
Public vs Secret keys
| Key type | Format | Use in |
|---|---|---|
| Public | pk_test_* / pk_live_* | JS snippet (data-merchant attribute) |
| Secret | sk_test_* / sk_live_* | Server-side API calls (Bearer token) |
Public keys are safe to embed in your HTML. Secret keys must never appear in frontend code.
Test vs Live mode
Keys with _test_ operate in test mode -- clicks and conversions are tracked but no real commissions are generated. Keys with _live_ operate in live mode. Test and live data are completely isolated.
Cookieless tracking
Selgeo does not use cookies. The click_id is stored in the browser's sessionStorage, which is automatically cleared when the tab or browser is closed. This means no cookie consent banners are needed for Selgeo tracking.
Attribution priority
When a conversion includes both a click_id and a promo_code, the promo code takes priority. This allows partners to get credit even when the customer arrives through a different channel.
Getting started
If you are new to Selgeo, start with the Quick Start guide which walks you through the entire setup in under 30 minutes. Then return here for the detailed guide matching your integration path.