Skip to content
OpenPartner docs

Integrate your site

Three small pieces connect your product to OpenPartner. Budget about an hour, including the end-to-end test.

partner link click → your site (SDK captures referral)
                   → signup     (identify stitches user ↔ click)
                   → payment    (server event drives attribution + commission)

1. Add the SDK to your website

Install @openpartner/sdk on your marketing site and app, and initialize it once per page load:

import { OpenPartner } from '@openpartner/sdk';


export const op = OpenPartner.init({
  apiUrl: 'https://app.openpartner.dev/api/t/<your-workspace>',
});

On a white-label domain use https://portal.yourbrand.com/api; self-hosted installs use their own API URL.

That’s the whole page-level integration: when a visitor arrives through a partner’s link, the SDK captures the referral token and keeps it alive across sessions — surviving Safari’s cookie limits and multi-week gaps between first click and signup.

2. Identify users when they sign up

In your signup and login flows, one call:

await op.identify(user.id);

This links “anonymous visitor who clicked partner X’s link” to “customer #123”. Use the same user ID your backend will report events with — it’s the join key for everything.

3. Report revenue from your backend

When a customer pays — first purchase, subscription, renewal — your server reports one event, authenticated with an API key you mint under Admin → CRM integration:

import { OpenPartnerServer } from '@openpartner/sdk/server';


const op = new OpenPartnerServer({
  apiUrl: process.env.OPENPARTNER_API_URL!,
  apiKey: process.env.OPENPARTNER_API_KEY!,
});


await op.trackEvent({
  userId: user.id,
  type: 'invoice_paid',
  value: 49.0, // major units — dollars, not cents
  currency: 'USD',
  metadata: { stripeInvoiceId: invoice.id },
});

(Or raw HTTP: POST /attribution/events.) If you bill with Stripe, the natural place for this call is inside the Stripe webhook handler you already have — when Stripe confirms an invoice, forward one event. Also worth sending signup and trial_started events even though they carry no revenue; they power the funnel view.

Common questions

Do I need to give OpenPartner access to my database? No — nothing ever connects to your database. Data flows one way, through the snippet and the events API, and you can export everything from your dashboard at any time.

Do I need to point a Stripe webhook at OpenPartner? No. Keep Stripe pointed at your own systems and add the one trackEvent call where you confirm payment. (This also means the integration is identical if you ever change billing providers.)

Can OpenPartner notify my systems? Yes — that’s separate, and optional: outbound webhooks with HMAC signatures fire on commission events, so your CRM or Slack can react to partner activity.

Test the loop end to end

Before inviting real partners:

  1. Create a test partner in Admin → Partners and grant them your program.
  2. Open the partner’s referral link in a private browser window — you should land on your site with ?cref=… in the URL.
  3. Sign up as a fake customer in that window — this fires identify().
  4. Trigger a test payment (or call trackEvent by hand with the fake user’s ID).
  5. Watch the dashboard: the event should appear attributed to your test partner, with a commission accrued under Admin → Partners → [partner] → Commissions.

If the event comes back no_identity, identify() never ran for that user; if no_click, the browser session didn’t carry a referral token (make sure you landed via the partner link in the same browser profile). The events response tells you which.

Once one test partner works, the integration is done — invite real partners, or share your public application page (/join on your portal, configurable under Settings → Partner signups).