Coupons & Promo Codes

Coupons let us run marketing promotions that discount the buyer’s total at checkout. The system is bespoke — we don’t use Stripe’s native coupon feature. Instead, we manage coupon logic internally and create ephemeral Stripe coupons on-the-fly at checkout for clean display.

Why Not Stripe-Native Coupons?

We evaluated Stripe’s built-in coupon system and decided against it for several reasons:

Instead, the platform absorbs the discount cost as a marketing expense. Sellers receive their full payout regardless of whether a coupon was used.

How It Works — The Big Picture

Coupon Types

Coupons support two discount types:

Coupon Configuration

Each coupon has a rich set of configuration options:

Validation Rules

When a buyer applies a coupon, we run through these checks in order:

Reservation Pattern

A key challenge is preventing over-consumption of limited coupons. If a coupon has maxRedemptions: 100 and 100 people try to check out simultaneously, we need exactly 100 to succeed.

We use a reservation pattern similar to inventory reservations:

// Only succeeds if capacity remains
CouponModel.findOneAndUpdate(
  { _id: couponId, $expr: { $lt: ["$redemptionCount", "$maxRedemptions"] } },
  { $inc: { redemptionCount: 1 } },
  { session }  // Inside MongoDB transaction
)

// Guard: only decrement if count > 0 (prevents going negative)
CouponModel.updateOne(
  { _id: couponId, redemptionCount: { $gt: 0 } },
  { $inc: { redemptionCount: -1 } },
  { session }
)

Checkout Integration

When a buyer provides a couponCode in the checkout request, the flow is:

stripe.coupons.create({
  amount_off: discountAmount,
  currency,
  duration: "once",
  max_redemptions: 1,
  name: `Promo: ${code}`,
})

Minimum Order Amount

Orders below 100 cents (1.00 in any currency) are rejected at checkout with an ORDER_TOTAL_TOO_LOW error. This prevents tiny/accidental orders that would cost more to process than they’re worth.

const MINIMUM_ORDER_AMOUNT = 100 // cents

However, this check is bypassed when a promo code is present. The rationale: a coupon might intentionally bring the total to zero (or near-zero), and that’s a valid marketing scenario. If someone has a 100% coupon, we don’t want to reject their free order.

// Only enforce minimum when no promo code
if (!couponCode && subtotalWithShipping + buyerFee.total < MINIMUM_ORDER_AMOUNT) {
  return err(CheckoutErr.orderTotalTooLow(MINIMUM_ORDER_AMOUNT, cart.currency))
}

Stripe Minimum Charge Auto-Absorb

Stripe enforces minimum charge amounts that vary by currency. If a coupon brings the payable total below the minimum but above zero, Stripe would reject the payment with an amount_too_small error.

To prevent this, the checkout service auto-absorbs the remaining amount into the discount when it falls into the danger zone (between 1 cent and the Stripe minimum). The discount is increased to cover the full order total, making the order effectively free.

const remainder = stripeTotal - cappedDiscount
const stripeMin = STRIPE_MINIMUM_CHARGE[cart.currency] ?? 50
 
// If remainder is between 1 cent and Stripe's minimum, absorb it
if (remainder > 0 && remainder < stripeMin) {
  cappedDiscount = stripeTotal // order becomes free
}

Example: A buyer has a $10.00 cart and applies a$9.80 coupon. The remainder would be $0.20 — below Stripe's USD minimum of$0.50. Instead of failing, the discount is bumped to $10.00 and the order goes through as free.

The three possible outcomes when a coupon is applied:

How Discounts Flow Through Orders

Coupons apply at the transaction level (all sellers combined). When orders are created from a transaction, the discount is prorated across orders proportionally by subtotal:

Order discount = couponDiscount × (orderSubtotal / transactionSubtotal)

The last order absorbs any rounding remainder to ensure the sum exactly matches.

Example: $10 coupon on a transaction with two orders ($60 and $40 subtotals):

• Order 1: $10 × 60/100 =$6
• Order 2: $10 × 40/100 =$4

Seller Payout Math

The coupon discount reduces the charged (what Stripe holds for each order), but the transfer formula compensates for this. Sellers are completely unaffected:

transferAmount = charged - refunded - sellerFee - buyerFee - tax - transferred + couponDiscount

Without a coupon: charged includes the full amount, couponDiscount is 0. With a coupon: charged is reduced by the discount, but + couponDiscount adds it back.

Net result: sellerTransfer = orderSubtotal + shipping - sellerFee — identical with or without a coupon.

Error Reference

Errors are surfaced through two endpoints with different error granularity.

Validate Endpoint (coupon.validate)

The validate endpoint exposes each coupon error as a separate typed oRPC error. The frontend can match on the error code directly for granular user messaging.

Checkout Endpoint (checkout.create)

The checkout endpoint collapses all coupon validation errors into a single COUPON_INVALID error. It also adds checkout-level errors unrelated to coupons.

Admin API

Admins manage coupons through the marketplace-admin API:

Data Model

Code Locations