Overview and quickstart

How it works#

1. Click. An affiliate shares https://yourapp.com/?via=jane. The Kickrail script on your site records the click and keeps a referral id in a first-party cookie.
2. Signup. When the visitor submits your signup form, the script reports their email with the referral id. (Your server can report it instead, with your user id or Stripe customer id.) That ties the person to Jane.
3. Payment. Kickrail watches your Stripe account. Every paid invoice or one-off checkout from a referred customer earns a commission under the affiliate's campaign rules.
4. Refunds. A refund or dispute shrinks or voids an unpaid commission, or claws back a paid one against the next payout.
5. Payout. Once the hold period passes, the commission is payable. Pay by PayPal, Wise or bank and mark it paid, or send one Stripe payout to everyone.

Quickstart#

1. Create a program. Sign up, then give the program a name and your website. Every new program starts on a 14-day Growth trial with no card.

2. Connect Stripe. In Settings → Stripe, click Connect with Stripe and approve Kickrail on stripe.com. There is nothing to set up in Stripe itself.

Prefer not to grant OAuth access? Open Developers → API keys → Create restricted key in Stripe, grant the permissions below, and paste the key instead. Kickrail encrypts it and creates its own webhook endpoint on your account.

• Charges, Invoices, Checkout Sessions, Coupons: Read
• Customers, Promotion Codes, Webhook Endpoints: Write

3. Add the script to every page of your marketing site and app. Your exact tag, with your public key, is in Settings → Install.

<script async src="https://kickrail.com/api/kr.js?k=YOUR_PUBLIC_KEY"></script>

That's the whole install for most sites. When a referred visitor submits your signup form, the script reports their email, and their first Stripe payment earns the commission.

4. Optional: report signups from your server. For signups that aren't a plain form, or to rule out ad blockers, send the user's details and the kr_ref cookie to Kickrail right after you create them. Your server key is in Settings → Server API key.

await fetch("https://kickrail.com/api/v1/referrals", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.KICKRAIL_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    referral: req.cookies.kr_ref, // set by the script
    email: user.email,
    user_id: user.id,
  }),
});

5. Test it. Invite yourself as an affiliate from the Affiliates page (use a different email from your own account, or the self-referral check will hold the commission). Open your affiliate link with &kr_test=1 added, sign up, and pay with a Stripe test card. The click, the signup and the commission appear on the Referrals page within a few seconds.

Words used in these docs#

• Program: one product's affiliate program, with its own Stripe account, affiliates, rules and keys. One login can run several programs.
• Affiliate: a person promoting you. Each has a link token (jane), optional extra links, and optional creator codes.
• Referral: a person an affiliate brought in. It starts as a lead and becomes a customer on their first payment.
• Commission: what an affiliate earned from one payment, or a negative clawback after a refund.
• Campaign: the commission rules a group of affiliates is on.