# Coupons & Credits

## Overview

This area covers the two levers you use to win and reward customers at checkout:

- Coupons (Admin → Coupons) — discount codes a customer types at checkout. Percent or fixed, time-bounded, plan-scoped, and capped however you like.
- Credit packages (Admin → Credit packages) — pay-as-you-go bundles that sell a fixed number of message credits for a fixed price.

Both live under the Billing & Plans group in the admin sidebar, and both feed the same checkout that powers your plans and billing.

## The Coupons List

The coupon index shows every code in your catalog, newest first, 12 per page. A four-card KPI strip sits at the top:

KPI | Meaning
--- | ---
Total coupons | Every coupon in the catalog, active or not.
Active | Coupons currently accepting redemptions.
Expired | Coupons whose expiry date is in the past.
Total redemptions | All-time uses summed across every coupon.

Below the KPIs are status pills (All, Active, Disabled, Expired) and a search box that matches the code or its description. The table lists each coupon's code and description, its discount (a percentage, or a fixed amount in your default currency), a uses counter shown as `used / max` (or `used / ∞` when uncapped), and a validity range. Expired rows are dimmed.

Each row has an inline Active toggle that flips the coupon on or off instantly, and a menu with Edit and Delete.

> Deleting is safe for past buyers: Removing a coupon returns its code to the pool for reuse but does not claw back discounts — workspaces that already redeemed it keep what they got. If you only want to stop new redemptions, just toggle it off rather than deleting.

## Creating & Editing a Coupon

Creating and editing a coupon use the same form, organised into four numbered sections. The fields below match the form exactly.

### Section 1 — Identity

Field | What it does
--- | ---
Code (required) | What the customer types at checkout, e.g. `WELCOME10`. Always uppercased on save and must be unique.
Description | Shown to the customer at checkout (for example "10% off the first month for new signups").
Admin note | Internal only, never shown to customers — a place for batch/campaign context.
Active | When on, customers can redeem it at checkout. On by default.

### Section 2 — Discount

Field | What it does
--- | ---
Type (required) | Percent (%) or Fixed amount.
Amount (required) | For percent type, `10` means 10% off. For fixed, `10` means 10 currency units off.
Max discount cap | Percent type only. Caps the discount value — e.g. "20% off, but never more than $50." Blank = no cap.
Currency lock | Restricts redemption to a single currency. Most relevant for fixed-amount coupons so "10 off" doesn't mean wildly different things across currencies. Blank = any currency.
Minimum order amount | The order must reach this subtotal before the coupon applies. `0` = no minimum.

> Always cap percentage coupons: A 30%-off code with no cap behaves very differently on a $9 plan versus a $384 annual plan. Set a Max discount cap on any percent coupon you don't want applied to your highest tiers.

### Section 3 — Eligibility

Field | What it does
--- | ---
Applicable plans | A multi-select of your active plans. Leave it empty to apply to any plan; pick one or more to scope the coupon to just those tiers.
Starts at | When the coupon becomes redeemable. Blank = available immediately.
Expires at | When it stops working. Blank = never expires. Must be on or after the start date.

### Section 4 — Limits & Behaviour

Field | What it does
--- | ---
Max total redemptions | How many times the code can be used across all customers. Blank = unlimited.
Per-user limit | How many times a single customer can redeem it. Blank = unlimited.
First purchase only | When on, only workspaces with no paid orders yet can use it — ideal for acquisition codes.
Stackable with other coupons | When on, the code can be combined with another active coupon at checkout. Off by default.

Save with Create coupon (or Save changes when editing). From then on, the code is checked against all these rules whenever a customer applies it at checkout.

> Recipe — a launch promo: Type `Percent`, Amount `25`, Max discount cap `50`, turn on First purchase only, set Max total redemptions to your budget (say 200), set an Expires at date, and leave Applicable plans empty. That's "25% off your first order, capped at $50, first 200 new customers, time-limited."

## Credit Packages

Credit packages are pay-as-you-go bundles: a customer pays a fixed price and receives a fixed number of message credits. They're sold from the checkout page and shown on a workspace's wallet. They sit alongside subscriptions — a workspace can be on a plan and top up with credits.

The index lists every package with its name, slug, price, credit count, a computed credits-per-currency-unit value, an optional badge, and an active/disabled status. Each row has Edit, Enable/Disable, and Delete.

> Fixed conversion, by design: Each package buys exactly the credit count you set, independent of the per-unit conversion rate configured in Settings. That lets you offer volume deals — a bigger bundle can include proportionally more credits than the base rate — without touching the global rate.

## Creating & Editing a Credit Package

Creating and editing a credit package use the same three-section form.

### Section 1 — Identity

Field | What it does
--- | ---
Name (required) | The package's display name (Starter / Growth / Scale).
Slug | A short, unique name used in the package's checkout link. Leave blank to generate it automatically from the name.
Description | A short blurb shown on the wallet page.

### Section 2 — Pricing

Field | What it does
--- | ---
Price (required) | In whole currency units (e.g. `100` = 100 of the chosen unit). Decimal amounts like cents and paise are preserved.
Currency | One of your active currencies (INR, USD, EUR, GBP, AED).
Credits (required) | The whole number of message credits this package grants on purchase.

### Section 3 — Display & Visibility

Field | What it does
--- | ---
Badge | An optional label above the price ("Most popular", "Best value").
Sort order | Lower numbers appear first on the wallet page. Use it to order your bundle ladder.
Active | When on, the package is visible on the user-side wallet. On by default.
Featured | Highlights the card on the wallet page to draw the eye to your hero bundle.

Save with Create package (or Save changes).

> Disabling vs deleting: Turning a package off (Disable) simply removes it from the customer-facing wallet list — credits customers already bought are untouched. Deleting also leaves existing purchases intact. Prefer Disable when retiring a bundle so its name and history stay on record.

## Related Pages

- Plans & Packages — the subscription tiers coupons can be scoped to.
- Billing & Finance — where credit-bundle purchases appear as add-on orders and coupon discounts show on invoices.
- Localization — manage the active currencies offered in both forms.
- System Settings — the global credit conversion rate that credit packages override.