Coupon codes

What it is for

A link is awkward in a podcast, on a slide, or in a video description that gets copied around. A code is not: "use LAUNCH20" survives every one of those. It also gives the customer a reason to use it, which a bare link never does.

The discount is always yours to decide. On Stripe, Klibon can create each affiliate's code for you under a coupon you made. Everywhere else, you create the code in Polar, Creem or Paddle and register it here, and Klibon learns to recognise it.

Automatic codes on Stripe

Instead of making a code per affiliate by hand, give Klibon a second Stripe key that can do one thing: create and switch off promotion codes. The key Klibon tracks sales with stays read-only.

1. Create one coupon in Stripe (Product catalog → Coupons), for example 20% off for 3 months. That is the discount every affiliate code gives. A coupon is not a code anyone types: leave its customer-facing codes off, and set no redemption limit, or every affiliate's code stops working when it is reached.
2. Open your program's Settings → Coupons and find A code for each affiliate. Create the key with the button there: a restricted key with only Coupons: Read and Promotion Codes: Write. A secret key is refused.
3. Pick the coupon and switch it on. Every affiliate you approve from then on gets a code made of their name and the discount, like SARAH20. A button creates codes for the affiliates you had already approved.

A code is shown to its affiliate, prefilled at checkout and credited only once Stripe has confirmed it exists. If Stripe refuses one — the key lost a permission, the coupon was deleted — the affiliate's coupons show why, with a button to try again. Blocking or removing an affiliate, or archiving their code, switches it off in Stripe too. Removing the key stops new codes; the existing ones keep working until you disable them in Stripe.

Going live without the tracking script

Switched on, automatic codes count as your program's tracking. A program on Stripe can be activated with no script on your site, and so no cookie: step 3 of Setup passes once the switch is on. The trade-off is plain: a sale is credited only when the customer types their affiliate's code. Someone who follows a link and pays without a code is not credited, and the checkout is not prefilled for them. Make sure your checkout shows a promotion code field (allow_promotion_codes on a Stripe Checkout session).

Removing the coupon key, or switching the codes off, takes a program that relies on them off the marketplace and closes it to new affiliates until the script is installed.

Registering a code

1. Create the discount in your processor. A promotion code in Stripe, a discount in Polar or Creem, a discount in Paddle. Set it to whatever the customer gets.
2. Open the affiliate on your program's Affiliates tab and click Coupons. Enter the code exactly as customers will type it — letters, digits, - and _, no spaces, no dots. Case does not matter.
3. Add the processor's ids when it has any. Some processors name a discount by its id on their webhooks rather than by the code: Stripe sends the promotion code's promo_… id and the coupon's id; Paddle sends only dsc_…; Polar and Creem send both the id and the code. Adding the id is what makes the match certain.

An affiliate can hold several live codes, one per campaign. Archiving a code stops new sales from matching it; customers it already brought in stay with the affiliate. For a code you registered by hand, disable the discount in your processor too — Klibon cannot do that for you. An automatic code is switched off in Stripe for you.

How a sale is credited

When a payment arrives, Klibon looks at three things and takes the first that applies:

1. A customer you already know. If this customer was attributed before — a renewal, a second purchase — they stay with that affiliate, whatever the payment carries. A coupon never takes a returning customer away from the affiliate who brought them.
2. A coupon. If the payment used a code registered to an affiliate, that affiliate is credited.
3. The link's code. The referral code the cookie carried into the checkout.

So on a new customer, a coupon beats the cookie. Typing a code at checkout is something the customer did on purpose; a cookie is something that happened to them. When the two name different affiliates the coupon's affiliate is credited and the event is marked Conflict on the Sales → Event log tab, with the reason, so nothing is decided silently.

Everything else works as for a link: the same hold period, the same rules per product, the same statement. A 100% coupon opens the referral without a commission, and the next paid invoice is that affiliate's first.

Prefilling the code at checkout

When a visitor arrives through an affiliate's link, the script stores that affiliate's code alongside the referral in the _klb cookie, and the tracked link itself carries it as ?kc=. On the checkouts that accept one, the code is prefilled for you: prefilled_promo_code on a Stripe Payment Link, discount_code on a Polar or Creem checkout link, data-discount-code on a Paddle button. A value you set yourself is never overwritten.

For a checkout you create server-side, read it in the browser and send it along:

// The coupon to prefill for this visitor, or null. The affiliate's own code first,
// then your program-wide one — and only for a referred visitor.
const coupon = window.Klibon ? window.Klibon.coupon() : null

// Stripe Checkout Session, server side. `code` is the referral your page sent
// with window.Klibon.referral(), checked first (see Install the tracking script):
const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: priceId, quantity: 1 }],
  client_reference_id: code,
  // Either resolve the code to its promotion_code id and pass it as a discount…
  discounts: promotionCodeId ? [{ promotion_code: promotionCodeId }] : undefined,
  // …or let the customer see it prefilled in the code field.
  allow_promotion_codes: true
})

Klibon.coupon() returns the affiliate's own code first and your program-wide coupon otherwise. It returns null for a visitor who was not referred — most of them — so guard for it.

Double-sided rewards: a discount for every referred customer

On Growth and Scale, Settings → Coupons has a discount for referred customers. Anyone who arrives through any affiliate link gets it prefilled at checkout — the customer gets a discount, the affiliate gets the commission, and both have a reason to make the sale happen. It is a perk, not attribution: sales are still credited by link or by the affiliate's own coupon, and the same code cannot be both.

The conversions API

Reporting a payment yourself? Send the code the customer used as discount_code. It counts as a way to attribute the sale on its own.

POST /api/v1/conversions
{
  "event_id": "order_1042",
  "type": "sale",
  "amount": 4900,
  "currency": "USD",
  "discount_code": "LAUNCH20",
  "customer_id": "cust_7"
}

Limits

• A code is unique within a program while it is live. Two of your programs may use the same code; one program may not hand the same code to two affiliates.
• A Stripe subscription created through the API with a promotion code shows only opaque di_… ids on its invoices. Register the promo_… id, or pass the referral code as metadata.klibon as described in Connect Stripe.
• A blocked affiliate's codes stop matching, like their links. A removed affiliate's codes stop matching for new customers; the ones they already brought in keep renewing.
• Your own test relationship has a test link, not a coupon.