Coupon Management

Overview

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

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

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

• 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

• 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

POST /v2/coupons

Custom / Headless

// 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 < usage_limit)
     RETURNING id`,
    [couponId]
  );
  if (result.rowCount === 0) throw new Error('COUPON_EXHAUSTED');

  await tx.couponRedemptions.insert({ coupon_id: couponId, customer_id: customerId, order_id: orderId, discount_cents: discountCents });
}

import crypto from 'crypto';

function generateCode(prefix = 'PROMO', length = 8): string {
  const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // no ambiguous chars
  return prefix + '-' + Array.from(crypto.randomBytes(length))
    .map(b => chars[b % chars.length]).join('');
}

async function bulkGenerate(template: CouponTemplate, quantity: number): Promise<string[]> {
  const codes: string[] = [];
  while (codes.length < quantity) {
    const batch = Array.from({ length: Math.min(500, quantity - codes.length) }, () => generateCode(template.prefix));
    const inserted = await db.coupons.insertMany(
      batch.map(code => ({ ...template, code, usage_limit: 1, per_customer_limit: 1 })),
      { onConflict: 'ignore' }
    );
    codes.push(...inserted.map(r => r.code));
  }
  return codes;
}

Best Practices

• Normalize codes to uppercase — store and compare codes in uppercase and trim whitespace to prevent "code not found" errors from minor formatting differences
• Use single-use codes for targeted campaigns — set usage limit to 1 per code when distributing unique codes via email to prevent sharing
• Validate at order creation, not just at cart — re-check coupon validity (expiry, usage limits) when the order is actually placed to handle race conditions
• Soft-delete coupons — deactivate rather than delete to preserve redemption history for accounting
• Track discount abuse — if a customer has abandoned and recovered with a discount code three or more times, consider excluding them from discount campaigns
• Cap maximum discount amounts — for percentage coupons, set a maximum dollar discount to prevent runaway promotions (e.g., 20% off capped at $50)

Common Pitfalls

UPDATE ... WHERE usage_count < usage_limit

INSERT ... ON CONFLICT DO NOTHING

Related Skills

• @discount-engine
• @price-rules-engine
• @ab-testing-pricing
• @loyalty-points-system
• @checkout-flow-optimization