Integration Guide

What the platform does for you

Every creator gets a unique link (creator-performance-network.vercel.app/r/<code>). When someone clicks it, the platform records the click and redirects them to your app or site — this part is automatic, nothing to build.

What the platform can't do on its own is know when that person actually converts (signed up, purchased, etc.) inside your app — it has no visibility into your systems. That's the one integration you need to build: reporting conversion events back to the platform via API.

1. Get your API key

From your app's page (Apps → your app → API keys), generate a key. It's shown once — store it as a server-side secret (Firebase Functions secret, environment variable, etc.). Never embed it in client-side/mobile app code — anyone who extracts it could report fake conversions and get paid for them.

2. Capture attribution

You need to know, for each user, which creator (if any) referred them — so that when they later convert, you can tell the platform who to credit. How you capture this depends on where people land.

Website

The redirect appends ?cpn_click=<id> to your destination URL and also sets a first-party cookie (cpn_attr, 30 days). Read either one and store it against the user's account when they sign up — a normal web session makes this reliable, no special handling needed.

Android app

A query param doesn't survive the trip through the Play Store, but Google's Install Referrer API does. If your app's Play Store / App Store links are set on your App record, the redirect automatically appends &referrer=cpn_click%3D<id> when sending an Android visitor to Play. Your app reads that referrer once on first launch and stores the id locally until the user signs up, then saves it to their account record — the same pattern as the website case from there on.

// On first app launch (Android only):
final referrer = await PlayInstallReferrer.get(); // e.g. "cpn_click=abc123"
final clickId = Uri.splitQueryString(referrer)['cpn_click'];
// store clickId locally, then attach it to the user record at signup

iOS app

There's no equivalent official mechanism for arbitrary referral links on iOS. Reliable iOS install attribution needs a Mobile Measurement Partner (Branch, AppsFlyer, Adjust) — set one up if iOS conversions need to be tracked, and have it call your backend (or the events API below) on a verified install/conversion.

3. Report the conversion

When a user does whatever your campaign is billed on (signup, purchase, etc.), call this from your backend — only after you've confirmed the event actually happened through your own authoritative source (a payment webhook, a verified receipt), never directly from client code:

POST https://creator-performance-network.vercel.app/api/v1/events
Authorization: Bearer <your API key>
Content-Type: application/json

{
  "appId": "your-app-id",
  "event": "first_purchase",
  "externalUserId": "user-123",
  "attributionId": "<the cpn_click value you stored at signup>",
  "value": 29.99,
  "currency": "USD",
  "idempotencyKey": "optional-unique-id-per-real-world-event"
}

event is one of: click, install, signup, verified_signup, trial_started, subscription_started, first_purchase, purchase, qualified_customer, refund. Only the event type your campaign's conversion event is set to actually creates a billable conversion — others are recorded but don't generate a commission.

If attributionId doesn't match a real click on file, or is omitted, the event is still recorded but no conversion is created — there's nobody to credit. The call is idempotent: retrying the same event (matched by idempotencyKey, or by all the other fields if you don't send one) is always safe and never double-counts.

4. Optional: verify purchases against your own Stripe data

If you charge through Stripe, you can go a step further than self-reporting. From Billing → Verified purchases, connect a restricted, read-only Stripe key (create one in your Stripe dashboard: Developers → API keys → Create restricted key, with read access to Charges, Checkout Sessions, PaymentIntents, and Invoices — never your full secret key). Once connected, include the Checkout Session, PaymentIntent, or Invoice id as stripeReference in your event report, and the platform looks it up directly in Stripe to confirm the purchase actually happened and the amount matches — independent of whatever your backend claims. Conversions show a "Verified with Stripe" badge when this checks out.

5. Review and approve

Reported conversions show up under your campaign's Conversions tab. Since the event only ever reaches the platform after your own backend already confirmed it really happened, approval is mostly a final business check (fraud flags, sanity-checking amounts) rather than re-verifying the payment itself. Approving is what actually reserves the creator's payout from your balance.

Troubleshooting

• Conversions aren't showing up: confirm the exact API call is succeeding (check the response status/body, not just that your app didn't crash) and that attributionId is the click id you actually captured, not empty or a placeholder.
• Right creator, wrong numbers: the amount you pay is always the creator's share plus the platform's fixed fee — see the campaign's commission section for the exact split.
• Nothing tracked for installs before a certain date: attribution code only exists in the app version it was added to — anyone who installed an earlier version has no attribution id and can't be retroactively matched.