Discounts & Promotions

The boilerplate ships two independent discount paths, one for each checkout mode:

• The native discounts engine powers the default quote flow. Admins create codes in the dashboard; shoppers type a code in the cart before requesting a quote, or the cart applies an automatic promotion for them. The applied code and the dollar amount it took off are stored on the resulting quote and surfaced in the admin dashboard and quote emails.
• Stripe promotion codes power card checkout. When Stripe is enabled, the Checkout Session opens with allow_promotion_codes: true, so shoppers enter Stripe-managed codes on Stripe's hosted payment page. The native codes never touch this path.

The native discounts engine (quote flow)

Data model

A discount is stored in Firestore at discounts/{CODE} — the document id is the uppercase code, so a lookup is a single document read and saving the same code twice overwrites it in place. The model lives in src/lib/firebase/firebaseDataConverters.ts:

export const DISCOUNT_TYPES = ["percent", "fixed"] as const;
export type DiscountType = (typeof DISCOUNT_TYPES)[number];

export interface Discount {
  /** Firestore document id = the UPPERCASE code (set when read back). */
  id?: string;
  /** The code customers type, e.g. "WELCOME10". Stored uppercase. */
  code: string;
  type: DiscountType;
  /** Percent 1-100 for `"percent"`, a dollar amount > 0 for `"fixed"`. */
  value: number;
  /** Inactive codes are kept but cannot be applied. */
  active: boolean;
  /** Optional expiry; the code is usable through this instant. */
  expiresAt?: Date | null;

Discount math

All discount logic lives in src/lib/discounts.ts as pure, backend-free functions (unit-tested in tests/discounts.test.ts). They take an injectable now clock and never touch Firebase.

isDiscountUsable decides whether a code can currently be applied — it must be active, not past its expiresAt, and under its usage cap:

export function isDiscountUsable(
  discount: DiscountUsability,
  now: Date = new Date()
): boolean {
  if (!discount.active) return false;
  if (discount.expiresAt && discount.expiresAt.getTime() < now.getTime()) {
    return false;
  }
  if (
    typeof discount.maxUses === "number" &&
    discount.maxUses > 0 &&
    (discount.usedCount ?? 0) >= discount.maxUses
  ) {
    return false;
  }
  return true;
}

computeDiscountedTotal applies a code to a subtotal and returns the amount taken off and the new total:

• "percent" takes value% of the subtotal, rounded to cents.
• "fixed" takes value dollars, clamped to the subtotal so the total never goes negative.
• Non-finite or negative inputs are treated as 0, so the result is always 0 <= discountAmount <= subtotal and total = subtotal - discountAmount.

export interface DiscountedTotal {
  /** Dollar amount taken off the subtotal (rounded to cents, never negative). */
  discountAmount: number;
  /** Subtotal minus the discount (rounded to cents, never negative). */
  total: number;
}

The commerce service API

Discounts are exposed through the commerce service layer as commerce.discounts. Import it once and stay backend-agnostic — the same calls work whether the active backend is Firebase (default) or a SQL adapter over HTTP:

import { commerce } from "@/lib/commerce";

const discount = await commerce.discounts.findUsable("WELCOME10");
// -> Discount when the code exists, is active, and has not expired;
//    null otherwise.

The DiscountService interface (src/lib/commerce/types.ts) has five methods. Two are public; three are admin-only:

The access column above is enforced by the RPC route when a SQL backend is active. In src/app/api/commerce/[service]/[method]/route.ts the policy is:

discounts: {
    findUsable: "public",
    // Automatic promotions are public by design (they need no secret code —
    // the cart applies them for everyone), unlike the full `list`.
    listAutomatic: "public",
    list: "admin",
    save: "admin",
    remove: "admin",
  },

See Commerce RPC for how public / user / admin are checked on the server.

Usage limits

Give a code a max uses cap and it stops validating once its redemptions reach that number — the shopper sees the same "invalid code" message as for an expired one.

A redemption is counted when a quote carrying the discount is submitted, not when the code is typed. Every adapter increments the counter atomically:

The increment is best-effort and runs after the quote persists — a failed increment never fails a submitted quote. And save never writes usedCount, so editing a code in the admin cannot reset a live counter.

Automatic promotions

Mark a discount automatic and the cart applies it with no code entry, whenever it is usable and the subtotal meets its optional min. subtotal threshold. The shopper sees a "Promotion applied" banner instead of typing anything.

Selection is pure and lives beside the rest of the math:

export function isPromotionApplicable(
  promotion: PromotionCandidate,
  subtotal: number,
  now: Date = new Date()
): boolean {
  if (!promotion.automatic) return false;
  if (!isDiscountUsable(promotion, now)) return false;
  const threshold = promotion.minSubtotal;
  if (typeof threshold === "number" && threshold > 0 && subtotal < threshold) {
    return false;
  }
  return true;
}

When several promotions qualify, pickBestAutomaticPromotion takes the one with the highest savings on the current subtotal. Ties break deterministically — older created first, then the lexicographically smaller code — so a re-render never flips which promotion is showing. A promotion that would save nothing is never applied.

The cart fetches the candidate list once and re-derives the winner on every render, so changing quantities moves the cart across a minSubtotal threshold correctly. Typing a manual code always overrides the automatic promotion; removing the code brings it back.

How a code flows through the cart

The record stored on the quote is the AppliedDiscount shape (distinct from the reusable Discount — it captures a point-in-time application, not the live code):

export interface AppliedDiscount {
  code: string;
  type: DiscountType;
  value: number;
  /** Dollar amount deducted from the quote subtotal. */
  amount: number;
}

It rides along on the quote submission as quoteData.discount and is stored on the quote verbatim (and later carried onto the order when the quote is converted). Both Quote and Order carry an optional discount?: AppliedDiscount.

Where applied discounts show up

• Admin quotes dashboard — each quote that carried a code shows Discount: {code} (−{amount}).
• Quote emails — the quote email template renders Discount {code}: −{amount} when a discount is present (emails require Resend to be configured; see Emails).

Managing codes in the admin dashboard

The admin page at /admin/discounts (source: src/app/[locale]/admin/discounts/page.tsx) is a full CRUD table over commerce.discounts.

Creating a code. The "New discount" dialog validates before saving:

Toggling active. Each row has a switch that flips active and re-saves the code. Inactive codes stay in the table but findUsable returns null for them, so shoppers cannot apply them.

Deleting. The trash action asks for confirmation, then calls commerce.discounts.remove(code). Deletion is permanent.

Card checkout: Stripe promotion codes

When Stripe is enabled, discounts on the card path are handled entirely by Stripe. The native codes are ignored there — the Checkout Session in src/app/api/checkout/route.ts turns on Stripe's own promotion-code field:

const session = await stripe.checkout.sessions.create({
  mode: "payment",
  line_items: lineItems,
  // Let shoppers enter Stripe promotion codes on the payment page.
  allow_promotion_codes: true,
  success_url: `${origin}/checkout/success?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${origin}/cart`,
  metadata: encodeItemsMetadata(items),
  client_reference_id: customerId,
});

To offer a card-checkout discount:

Not yet implemented

The native engine is intentionally minimal. Still open:

• Per-customer limits — maxUses is a single global cap. There is no "once per customer" rule.
• Cart-condition promotions beyond a subtotal threshold — no "buy X get Y", no category or product targeting.
• Stacking — exactly one discount applies at a time; a typed code replaces the automatic promotion rather than combining with it.

(These constraints apply to the native quote-flow engine only — Stripe promotion codes enforce their own rules on the card path.)