Node SDK

Server-side companion for SaaS backends: record the signup → attribution binding on your server (instead of, or in addition to, the browser), and pair it with Stripe so invoices turn into commissions. See the Web SaaS guide for the full flow.

Install

npm i @maa/sdk-node

Configure

import { createClient } from "@maa/sdk-node";
 
const maa = createClient({
  apiKey: process.env.MAA_SDK_KEY!,           // your app's SDK key
  baseUrl: "https://api.myappaffiliate.com",
});

Keep the key in server env — never ship it to the browser (that's what the Web SDK is for).

Track a signup

In your signup handler, pass the new user id plus whatever referral evidence the request carried — a referral code (?via= you threaded through the signup form) or a claim_token from a branded link:

const result = await maa.trackSignup({
  userId: user.id,                 // the id you'll put in Stripe metadata
  code: req.body.via,              // or: claimToken: req.body.claimToken
});
// → { attributionId, affiliateId } | null (no attributable referral — fine, move on)

Under the hood this is POST /sdk/install + POST /sdk/identify in one call, using the user id as the stable device identity. null means "organic signup" — it is not an error.

Pair with Stripe (the part that pays creators)

When you create the Stripe subscription/checkout, stamp the same user id into metadata so the Stripe webhook can match invoices back to the attribution:

await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: "price_…", quantity: 1 }],
  subscription_data: {
    metadata: { customer_user_id: user.id },  // ← required for attribution
  },
  metadata: { customer_user_id: user.id },    // also on the session (one-time payments)
  success_url: "https://yourapp.com/welcome",
  cancel_url: "https://yourapp.com/pricing",
});

Every invoice.paid that carries this metadata becomes a commission — including renewals, for the lifetime of the subscription.

API

Network failures resolve to null — a flaky attribution call must never fail your signup path.