Web SaaS Guide

End-to-end: a creator shares a link to your SaaS, a visitor signs up and subscribes, and the creator earns a commission on every invoice — renewals included. No mobile app, no app store. Works with Stripe, Paddle, or anything that can tell us your user id.

The loop

creator link  https://yourapp.com/?via=LUMI
   → landing page       (Web SDK captures ?via= and persists it)
   → signup             (identify(userId) binds your user id)
   → checkout           (your billing provider carries that same id)
   → paid invoice       (provider webhook → our API → commission)
   → renewals           (every recurring invoice keeps paying the creator)
   → dashboard + CSV    (pending → matured → paid out)

Integrate MyAppAffiliate into my project.

Documentation (read these first, they are the source of truth):
- Page: https://docs.myappaffiliate.com/web-saas.md
- Full docs index: https://docs.myappaffiliate.com/llms.txt

Task: Wire MyAppAffiliate through my web SaaS end to end: capture ?via= on the landing page, identify the user at signup, carry that same user id into my billing provider's checkout, and register the revenue webhook. Walk the steps in order and show me the code for each.

Rules:
- Follow the documented API exactly — no invented method names, endpoints, parameters or field names.
- Match the conventions already used in my codebase.
- Ask me for my SDK key instead of guessing, and never hard-code it — read it from config/environment.
- Do NOT set an API base URL anywhere. Every SDK compiles the production host in; a staging or self-hosted host belongs in a build setting, not in code.
- Tell me afterwards which steps I still have to do by hand (dashboard settings, capabilities, webhook configuration).

1. Give creators their link

Each affiliate gets a code (e.g. LUMI). Their link is just your site plus a query param — no redirect service needed:

https://yourapp.com/?via=LUMI

Branded go.myappaffiliate.com short links work too (they carry a claim_token instead); the Web SDK handles both, on any route.

2. Capture on the landing page

On a plain landing page, a script tag is the whole integration — no build step:

<script
  src="https://cdn.jsdelivr.net/npm/@myappaffiliate/sdk-web@0/dist/sdk.js"
  data-api-key="pk_live_…"
  async
></script>

In an app frontend, install it instead:

npm i @myappaffiliate/sdk-web

import { myAppAffiliate } from "@myappaffiliate/sdk-web";
 
myAppAffiliate.start("pk_live_…");

One call in your app shell or root layout. It captures ?via= (and claim_token) on load and on client-side route changes, then persists the winner in localStorage, so the referral survives navigation, a closed tab, and the days between landing and signup. There is no API URL to configure. Details: Web SDK.

3. Identify at signup

When the account is created, bind your user id to the attribution. Client-side:

await myAppAffiliate.identify(user.id);

…or server-side with the Node SDK, which also picks the referral out of the request URL for you:

await myAppAffiliate.trackSignup({ userId: user.id, from: req.url });

This id is the join key for everything that follows — it must be the exact string your billing provider reports back to us in step 4.

4. Carry the same id into checkout

Stripe:

await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: "price_…", quantity: 1 }],
  subscription_data: { metadata: { customer_user_id: user.id } },
  client_reference_id: user.id,
  success_url: "https://yourapp.com/welcome",
  cancel_url: "https://yourapp.com/pricing",
});

Paddle:

await paddle.transactions.create({
  items: [{ priceId: "pri_…", quantity: 1 }],
  customData: { customer_user_id: user.id },
});

Neither, if you'd rather skip this step: both providers fall back to their own customer id, so identify(stripeCustomerId) / identify(paddleCustomerId) in step 3 works instead. Pick whichever is less plumbing in your codebase.

5. Register the webhook

• Stripe → Developers → Webhooks → Add endpoint: https://api.myappaffiliate.com/webhooks/stripe/<appId>, events invoice.paid, charge.refunded, customer.subscription.deleted, checkout.session.completed.
• Paddle → Developer tools → Notifications: https://api.myappaffiliate.com/webhooks/paddle/<appId>.

Paste the provider's signing secret into your MyAppAffiliate app settings; every delivery is signature-verified. Full details, including the normalized event mapping for all providers, are in Billing & Webhooks.

6. Watch it pay

• The founder dashboard shows the funnel (clicks → signups → paid), revenue, and per-creator earnings.
• Creators get their own scoped view with earnings and next-payout date.
• Payouts are a CSV export of matured commissions — idempotent, reconciles to the payout total.

Commission is amount × rate_bps / 10000, attributed to the referral inside the attribution window, created pending and matured after the hold period — so refunds inside the hold never pay out.

Checklist

1. myAppAffiliate.start("pk_live_…") in your app shell
2. identify(userId) at signup (or trackSignup server-side)
3. That same id reaching your billing provider (metadata, or use theirs)
4. Webhook endpoint registered + signing secret saved
5. Test end-to-end with a test-mode subscription → commission appears on the dashboard