API reference

Authentication#

Send your program's server key as a bearer token. Find it in Settings → Server API key. Keys start with sk_kr_, belong to one program, and must stay on your server.

curl https://kickrail.com/api/v1/affiliates \
  -H "Authorization: Bearer sk_kr_..."

There is one key per program. Rolling it in Settings replaces it at once, and the old key stops working immediately. Running several programs? Each has its own key, and a key only sees its own program.

Requests and responses#

• Send bodies as JSON with Content-Type: application/json.
• Times are ISO 8601 in UTC. Money is an integer in the currency's smallest unit (1500 USD is $15.00) with a lowercase currency.
• Ids carry a prefix: aff_, ref_, com_, po_, cmp_.

Pagination

List endpoints return the newest first:

{ "object": "list", "data": [ ... ], "has_more": true }

To get the next page, pass the last id you received as starting_after, and keep going while has_more is true.

async function* all(path) {
  let after;
  while (true) {
    const url = new URL("https://kickrail.com/api/v1" + path);
    url.searchParams.set("limit", "100");
    if (after) url.searchParams.set("starting_after", after);
    const res = await fetch(url, { headers: { Authorization: "Bearer " + process.env.KICKRAIL_SECRET_KEY } });
    const page = await res.json();
    yield* page.data;
    if (!page.has_more) return;
    after = page.data.at(-1).id;
  }
}

for await (const c of all("/commissions?status=pending")) console.log(c.id, c.amount_cents);

Errors

Errors use standard HTTP status codes with a JSON body: {"detail": "no such affiliate"}. For 422 from validation, detail is a list of the fields that failed.

Referrals#

Tell Kickrail who signed up and what referred them. Full guide: Report signups from your server.

At least one of email, user_id, stripe_customer_id is required. Returns {"referred": false} or {"referred": true, "created": bool, "referral": {...}}.

Query with one of email, user_id or stripe_customer_id. Returns {"referred": bool, "referral": {...} | null}.

The referral object

Affiliates#

Add an affiliate from your own app, for example when a customer opts into your partner program. People without a Kickrail login get one, and the welcome email carries a link to set their password. If they are already an affiliate of this program, that affiliate is returned with created: false.

curl https://kickrail.com/api/v1/affiliates \
  -H "Authorization: Bearer $KICKRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Jane Doe","code":"JANE20","metadata":{"crm_id":"42"}}'

Send only the fields you want to change. The response is the updated affiliate, plus a warning string when Stripe refused to create a promotion code for a new code.

The affiliate object

{
  "id": "aff_2Lp...",
  "object": "affiliate",
  "status": "approved",
  "email": "[email protected]",
  "name": "Jane Doe",
  "campaign_id": "cmp_...",
  "token": "jane",
  "link": "https://yourapp.com/?via=jane",
  "code": "JANE20",
  "code_redeemable_at_checkout": true,
  "links": [
    { "id": "lnk_...", "token": "jane-yt", "url": "https://yourapp.com/pricing?via=jane-yt",
      "landing_url": "https://yourapp.com/pricing", "label": "YouTube", "created_at": "..." }
  ],
  "codes": [{ "id": "cod_...", "code": "JANEPOD", "redeemable_at_checkout": true, "created_at": "..." }],
  "rate_override": null,
  "metadata": { "crm_id": "42" },
  "created_at": "2026-10-17T15:04:05Z"
}

rate_override comes back in stored form: {"type": "percent", "bps": 4000} (basis points, so 4000 is 40%) or {"type": "flat", "cents": 1500, "currency": "usd"}.

Commissions#

The commission object

Payouts#

Record that you paid affiliates yourself, in cash or in kind (a discount, account credit). It works like a manual payout in the dashboard: their payable commissions become paid, they get the payout email if it's on, and payout.paid goes out. Commissions still in their hold aren't included. Returns the payout object, or 409 if nothing is payable.

The payout object

Campaigns#

All campaigns, oldest first, in one list (no pagination). Each has id, name, rule, duration, hold_days, min_payout_cents, lead_bounty, product_rules, stripe_coupon_id, is_default, public, slug, join_url (null for a private campaign), landing_url, and a readable description such as "30% of every payment for 12 months". Create and edit campaigns in the dashboard.

Portal domains#

Serve the join page and affiliate portal from your own subdomain, as in Settings → Portal domains. Adding domains also needs room on your plan (Starter 1, Growth 3, Scale 10).

Every domain on the program, in one list.

Body: {"host": "partners.yourapp.com"}. Returns the domain with the dns_record to create, and checks it straight away. The first domain becomes primary.

Checks DNS and HTTPS again, like the Check DNS button. Call it after adding the CNAME; the first check after DNS is verified also requests the certificate.

Makes it the domain used in affiliate links and emails. Returns the full list.

Removes it. If it was primary, the next verified domain takes over.

The domain object