coupon-management

What this skill does

# Coupon Management

## Overview

Coupon systems let merchants create promotional codes with configurable rules: percentage or fixed-amount discounts, minimum order requirements, usage limits per coupon or per customer, and expiration dates. Every major e-commerce platform includes a built-in coupon system — you almost never need to build one from scratch. This skill walks you through setting up coupon management on each platform and explains when to reach for an app or plugin for advanced requirements like bulk unique codes or campaign tracking.

## When to Use This Skill

- When adding promotional codes to a checkout flow for the first time
- When migrating from a simple discount field to a rule-based coupon engine
- When running marketing campaigns that require unique, single-use codes for each recipient
- When building an admin interface to create and monitor coupon performance
- When enforcing complex coupon rules such as product/category exclusions or customer segment restrictions

## Core Instructions

### Step 1: Determine the merchant's platform and the right tool

| Platform | Built-in Capability | When to Add an App/Plugin |
|----------|-------------------|--------------------------|
| **Shopify** | Shopify Discounts — supports percentage, fixed amount, free shipping, BOGO; usage limits, expiry, minimum purchase | When you need bulk unique codes (Shopify supports import), customer-group-specific coupons, or loyalty integration (Smile.io, LoyaltyLion) |
| **WooCommerce** | WooCommerce Coupons — built into core; percentage, fixed cart, fixed product, free shipping types | When you need bulk unique code generation: WooCommerce Smart Coupons plugin; advanced rules: YITH WooCommerce Dynamic Pricing & Discounts |
| **BigCommerce** | Coupon codes built in — percentage, fixed amount, free shipping, free product types | When you need B2B-specific codes or advanced restrictions; BigCommerce app marketplace has options like Coupon Manager Pro |
| **Custom / Headless** | Must build — see Custom section below | N/A — you are building the system |

### Step 2: Set up standard coupons on your platform

---

#### Shopify

1. Go to **Discounts** in the Shopify admin sidebar
2. Click **Create discount** and choose the type:
   - **Amount off products** — percentage or fixed amount off specific products/collections
   - **Amount off order** — percentage or fixed amount off the entire cart
   - **Buy X get Y** — BOGO and bundle offers
   - **Free shipping** — removes shipping cost when code is applied
3. Configure the code:
   - Enter a code (e.g., `SUMMER20`) or click **Generate code** for a random one
   - Set **Minimum purchase requirements** (minimum subtotal or minimum quantity)
   - Set **Customer eligibility** — all customers, specific customer segments, or specific customers
   - Set **Maximum discount uses** — total uses and/or one use per customer
   - Set **Active dates** — start and optional end date
4. Click **Save discount**

**Bulk unique codes on Shopify:**
1. In the same Discounts screen, choose **Generate codes** instead of entering a single code
2. Set the quantity (up to 100 at a time from the UI; use the Shopify Admin API for larger volumes)
3. All generated codes share the same rules (discount value, expiry, usage limits)
4. Export the codes to CSV for use in your email marketing platform

**Shopify Plus — Shopify Scripts for advanced stacking:**
- Use **Shopify Scripts** (Shopify Plus only) for custom coupon logic: e.g., different discount percentages by customer tag, auto-apply coupons without a code
- Access via **Apps → Script Editor** in your Shopify admin

---

#### WooCommerce

1. Go to **WooCommerce → Coupons → Add coupon**
2. Set the **Coupon code** (unique identifier customers type at checkout)
3. Under **General** tab:
   - **Discount type**: Percentage discount, Fixed cart discount, Fixed product discount
   - **Coupon amount**: The discount value
   - **Free shipping**: Toggle to make this code grant free shipping
   - **Coupon expiry date**: Date after which the code stops working
4. Under **Usage restriction** tab:
   - **Minimum spend**: Cart subtotal must exceed this amount
   - **Maximum spend**: Cart subtotal cannot exceed this amount
   - **Individual use only**: Cannot be combined with other coupons
   - **Exclude sale items**: Don't apply to already-reduced items
   - **Products** and **Exclude products**: Restrict or exclude specific products
   - **Product categories** and **Exclude categories**: Restrict or exclude by category
   - **Email restrictions**: Limit to specific customer emails
5. Under **Usage limits** tab:
   - **Usage limit per coupon**: Total number of times this code can be used
   - **Usage limit per user**: How many times a single customer can use it
6. Click **Publish**

**Bulk unique codes on WooCommerce:**
- Install **WooCommerce Smart Coupons** (premium plugin, ~$99/year from StoreApps)
- Go to **WooCommerce → Smart Coupons → Generate Coupons**
- Set quantity, discount amount, expiry, and prefix — generates a CSV of unique codes
- Import or distribute via your email platform

---

#### BigCommerce

1. Go to **Marketing → Coupon Codes → Create Coupon Code**
2. Fill in:
   - **Code**: The code customers enter (or use the auto-generate button)
   - **Type**: Percentage off order, Dollar amount off order, Percentage off product, Dollar amount off product, Free shipping, Free product
   - **Discount amount**: The value
   - **Applies to**: All items, items from specific categories, or specific products
3. Under **Restrictions**:
   - **Minimum order**: Subtotal must exceed this amount
   - **Max uses**: Total redemptions allowed
   - **Max uses per customer**: Per-account limit
   - **Expiration date**: When the code stops working
4. Click **Save**

**Bulk codes on BigCommerce:**
Use the BigCommerce Promotions API (`POST /v2/coupons`) to generate codes programmatically, then export for distribution.

---

#### Custom / Headless

For headless stores, you need to build the validation and redemption logic. The key requirements are atomic redemption (prevent race conditions when two customers use the last available redemption simultaneously) and idempotent order processing.

```typescript
// Coupon validation at checkout
async function validateCoupon(
  code: string,
  customerId: string,
  orderSubtotalCents: number
): Promise<{ valid: boolean; discountCents: number; error?: string }> {
  const coupon = await db.coupons.findOne({ code: code.toUpperCase().trim(), is_active: true });
  if (!coupon) return { valid: false, discountCents: 0, error: 'Code not found' };

  const now = new Date();
  if (coupon.expires_at && coupon.expires_at < now) return { valid: false, discountCents: 0, error: 'Code expired' };
  if (coupon.usage_limit && coupon.usage_count >= coupon.usage_limit) return { valid: false, discountCents: 0, error: 'Code fully used' };
  if (coupon.min_order_cents && orderSubtotalCents < coupon.min_order_cents) return { valid: false, discountCents: 0, error: `Minimum order $${coupon.min_order_cents / 100}` };

  // Per-customer limit check
  if (coupon.per_customer_limit) {
    const uses = await db.couponRedemptions.count({ coupon_id: coupon.id, customer_id: customerId });
    if (uses >= coupon.per_customer_limit) return { valid: false, discountCents: 0, error: 'Already used' };
  }

  const discountCents = coupon.type === 'percentage'
    ? Math.round(orderSubtotalCents * (coupon.value / 100))
    : Math.min(coupon.value_cents, orderSubtotalCents);

  return { valid: true, discountCents };
}

// Atomic redemption — use inside the order creation transaction
async function redeemCoupon(tx: Tx, couponId: string, customerId: string, orderId: string, discountCents: number) {
  // Atomic increment with guard — prevents over-redemption under concurrency
  const result = await tx.raw(
    `UPDATE coupons SET usage_count = usage_count + 1
     WHERE id = ? AND (usage_limit IS NULL OR usage_count