Coupons

A coupon is a rule given to a segment: the customers who entered a code. There's no coupon object to learn: the code lives in your customer's metadata, and two things you already have do the rest.

	What it does	Ex.
A segment	Who has the code, and for how long.	data.coupon == 'SPRING50', for 30 days
A rule	The discount, given to that segment.	50% off the Pro base fee

Cloud applies the discount when it invoices and charges, so there's nothing to set up in Stripe: the charge it sends is already the discounted amount, and the invoice shows the price the customer paid. Rules are on Scale and Enterprise.

1. Who has the code

Your app saves the code a customer enters on that customer, with when they entered it, then saves the customer:

const customer = await limitr.customer('acme');
customer.metadata = { ...customer.metadata, coupon: 'SPRING50', coupon_at: Date.now() };
await limitr.setCustomer(customer);

On Segments, make a segment that matches the code, and how long it lasts for each customer, in Stof:

data.coupon == 'SPRING50' && Time.now() - data.coupon_at < 30days

Leave the time out for a code that lasts until you stop it. Cloud checks the segment against your customers again each day, so a customer stops matching within a day of their time running out.

2. The discount

On Policy, Rules, add a rule with a price change on what the code discounts, and under Who has it, give it to the segment. Then publish. In the policy, the rule names the segment by its ID:

policy:
  rules:
    spring50:
      label: Spring promo, half off
      segments: [seg_spring50]
      prices:
        credit:pro_month:
          modifier: { type: percent, amount: -50 }

Prices are keyed by credit, Ex. credit:pro_month for a Pro base fee in the pro_month credit. A percent modifier changes the list price by that percent; flat adds or takes off an amount a unit; a price replaces it. A code that should discount usage too gets a line for each credit it discounts (Ex. credit:ai_token).

From then on, a customer who enters the code has the rule. Their customer page lists it under Rules, from the segment, and given by spring50 where the price comes from. Or ask the Analyst: "half off the Pro base fee for 30 days for anyone with the coupon SPRING50".

To stop the code for everyone, take the segment off the rule and publish.

Which codes are real

Limitr doesn't decide which codes your app accepts: your app does, before it saves one. Check the code against the codes you offer, whether a customer has used one before, or anything else you need, in your own endpoint, so a code can be as plain or as clever as your business. A code no segment matches does nothing.

Save the code before the change it discounts. Cloud works out a customer's rules again moments after their settings change, so a charge made at that same moment (Ex. the base fee when they move to a paid plan) could be at the list price. Save the code, then change the plan.

How long a discount lasts

A code discounts what's charged while the customer has the rule:

• Fees charged when a period starts (Ex. a monthly base fee billed in advance): a code that lasts 30 days discounts one month's fee, and one that lasts about 80 days discounts three.
• Usage is priced at the rules in force while it happened, so usage before the code ran out stays discounted on the period's invoice.

A charge keeps the price it was charged at: a fee charged at the coupon's price stays at it, even if the code runs out before the period's invoice.