promo-code-system

name	promo-code-system
description	Add, manage, and track promotional/discount codes in web applications. Use when adding promo codes to existing apps, creating discount code systems, tracking code usage, implementing coupon functionality, managing promotional campaigns, or when users ask about discount codes, free access codes, or promotional features.
license	MIT

Promo Code System

Add promotional and discount code functionality to web applications with tracking, analytics, and flexible discount types.

Overview

This skill helps implement promo code systems in web apps. Supports:

• Quick implementation (hardcoded codes, 5 minutes)
• Proper implementation (database-driven, 45 minutes)
• Multiple discount types (free access, percentage off, fixed amount)
• Usage tracking and analytics
• Expiration dates and limits
• Stripe integration

When to Use This Skill

• User wants to add promo codes to their app
• User asks "how do I remember my codes?"
• User needs to track which codes are being used
• User wants to offer free access via codes
• User has existing discount system that needs extension

Quick Start Workflow

Follow these steps in order:

Step 1: Discover Existing System

Run the discovery script to find existing promo code implementation:

python3 scripts/discover_promo_system.py /path/to/project

If you don't have the project path, locate it by:

1. Checking Supabase projects (MCP)
2. Checking Vercel deployments (MCP)
3. Checking GitHub repositories (gh repo list)
4. Asking user for local path

The script identifies:

• Hardcoded discount codes
• Database tables
• API endpoints
• Payment processor integration

Step 2: Analyze Current State

Based on discovery results, determine implementation type:

No System Found

• No promo code patterns detected
• → Recommend Path A (Quick Start)

Hardcoded System Found

• Found DISCOUNT_CODES object or similar
• Codes defined in source code
• → Extend existing system or upgrade to database

Database System Found

• Found promo_codes table
• Has API endpoints
• → Enhance existing system

Step 3: Choose Implementation Path

Path A: Quick (Hardcoded) - 5 minutes

• Best for: MVPs, <20 codes, simple needs
• Use: templates/hardcoded_codes_template.js
• Pros: Fast, simple, no database changes
• Cons: No tracking, must redeploy to add codes

Path B: Proper (Database) - 45 minutes

• Best for: Production, >20 codes, need tracking
• Use: templates/promo_schema.sql + API templates
• Pros: Full tracking, expiration, limits, analytics
• Cons: More complex, requires database

Step 4: Implement Solution

For Path A (Quick/Hardcoded):

1. Copy templates/hardcoded_codes_template.js content
2. Add to user's server file (e.g., server.js, index.js)
3. Customize DISCOUNT_CODES object with their codes
4. Update checkout endpoint to use calculateDiscountedPrice()
5. Deploy

Example codes to add:

const DISCOUNT_CODES = {
  'FREE': { type: 'free', value: 0 },
  'FRIEND': { type: 'free', value: 0 },
  'SAVE10': { type: 'amount', value: 10 },
  'HALF': { type: 'percentage', value: 50 },
};

For Path B (Database-Driven):

1. Create database tables:

   • Run templates/promo_schema.sql in Supabase SQL Editor

2. Implement validation functions:

   • Add server-side validation (see references/implementation_guide.md)

3. Update API endpoints:

   • POST /api/validate-promo-code - Validate code
   • POST /api/create-checkout - Apply discount
   • POST /api/verify-payment - Track usage

4. (Optional) Deploy admin panel:

   • Use templates/admin_panel.html for visual management

5. Test end-to-end

Step 5: Create Reference Documentation

Always create a quick reference guide for the user:

1. Copy templates/quick_reference_template.md
2. Fill in placeholders:
   • Project name
   • File path where codes are stored
   • List of active codes
   • Instructions for adding more codes
   • Instructions for remembering codes
3. Save as MY_PROMO_CODES.md in their project

This answers the common question: "How do I remember my codes?"

Step 6: Test Implementation

Run through testing checklist:

Basic Tests:

• Valid code applies discount correctly
• Invalid code returns error
• Free code sets price to $0
• Case insensitivity works (FRIEND = friend)

Integration Tests (if using Stripe):

• Checkout with discount code
• Free checkout (skip Stripe for $0)
• Payment verification
• Usage tracking (if database-driven)

Test cards for Stripe:

• Success: 4242 4242 4242 4242
• Decline: 4000 0000 0000 9995

Tech Stack Specific Instructions

Node.js + Express

Use templates/hardcoded_codes_template.js directly:

// Add to server.js
const { validateDiscountCode, calculateDiscountedPrice } = require('./promo-codes');

app.post('/api/validate-promo-code', (req, res) => {
  const { code } = req.body;
  const result = validateDiscountCode(code);
  res.json(result);
});

Next.js (App Router)

Create API routes in app/api/:

// app/api/validate-promo/route.ts
export async function POST(request: Request) {
  const { code } = await request.json();
  const result = validateDiscountCode(code);
  return Response.json(result);
}

Next.js (Pages Router)

Create API routes in pages/api/:

// pages/api/validate-promo.ts
export default function handler(req, res) {
  const { code } = req.body;
  const result = validateDiscountCode(code);
  res.json(result);
}

Python + Flask/FastAPI

For Python implementations, adapt the JavaScript logic to Python:

DISCOUNT_CODES = {
    'FREE': {'type': 'free', 'value': 0},
    'SAVE10': {'type': 'amount', 'value': 10},
}

def validate_discount_code(code):
    code = code.upper().strip()
    if code not in DISCOUNT_CODES:
        return {'valid': False, 'error': 'Invalid code'}
    return {'valid': True, **DISCOUNT_CODES[code]}

Stripe Integration

Read references/stripe_integration.md for detailed Stripe patterns.

Key Points:

1. Apply discount by adjusting line item price (recommended):

   unit_amount: Math.round(finalAmount * 100)
   

2. Handle $0 checkouts separately (Stripe doesn't allow $0):

   if (finalAmount === 0) {
     return { accessToken: generateToken() };
   }
   

3. Store promo code in metadata:

   metadata: {
     promo_code: discountCode,
     original_amount: originalAmount,
     final_amount: finalAmount
   }
   

Generating Promo Codes

Use the code generator script to create secure codes:

python3 scripts/generate_codes.py --count 10 --prefix FRIEND

Options:

• --count N - Number of codes to generate
• --prefix PREFIX - Code prefix (e.g., SAVE, FRIEND)
• --length N - Random part length (default: 8)
• --format - alphanumeric, alpha, or numeric
• --separator - Separator character (default: -)

Output includes ready-to-paste formats:

• JavaScript object
• SQL INSERT statements
• Markdown list
• Plain text

Common Patterns

Free Access Codes

'FREE': { type: 'free', value: 0 }
'FRIEND': { type: 'free', value: 0 }
'BETA': { type: 'free', value: 0 }

Fixed Amount Discounts

'SAVE10': { type: 'amount', value: 10 }  // $10 off
'SAVE20': { type: 'amount', value: 20 }  // $20 off

Percentage Discounts

'HALF': { type: 'percentage', value: 50 }     // 50% off
'QUARTER': { type: 'percentage', value: 25 }  // 25% off

Database Schema (Path B)

For database-driven systems, use templates/promo_schema.sql:

Main table: promo_codes

• code - The promo code (unique)
• discount_type - 'free', 'amount', or 'percentage'
• discount_value - Discount amount
• is_active - Enable/disable code
• max_uses - Usage limit (NULL = unlimited)
• current_uses - Usage counter
• expires_at - Expiration date (NULL = never)

Tracking table: promo_code_usage

• promo_code_id - Link to promo code
• user_email - Who used it
• used_at - When used
• stripe_session_id - Payment session

Analytics Queries

Most Used Codes

SELECT code, current_uses 
FROM promo_codes 
ORDER BY current_uses DESC 
LIMIT 10;

Recent Usage

SELECT pc.code, pcu.user_email, pcu.used_at
FROM promo_code_usage pcu
JOIN promo_codes pc ON pcu.promo_code_id = pc.id
ORDER BY pcu.used_at DESC
LIMIT 50;

Revenue Impact

SELECT 
  pc.code,
  COUNT(*) as uses,
  SUM(CASE WHEN pc.discount_type = 'amount' 
      THEN pc.discount_value ELSE 0 END) as total_discount
FROM promo_code_usage pcu
JOIN promo_codes pc ON pcu.promo_code_id = pc.id
GROUP BY pc.code;

Security Best Practices

1. Always validate server-side - Never trust client input
2. Rate limit validation - Prevent brute force guessing
3. Use secure code format - Hard-to-guess codes (e.g., PROMO-2024-XJ9K)
4. Normalize codes - Convert to uppercase, trim whitespace
5. Track usage patterns - Monitor for abuse

Troubleshooting

Code not working

• Check code is active (is_active = true)
• Check not expired (expires_at > NOW())
• Check usage limit not reached (current_uses < max_uses)
• Verify case-insensitive comparison

$0 checkout fails

• Stripe doesn't allow $0 checkouts
• Skip Stripe for free codes
• Generate access token directly

Usage not tracked

• Verify recordPromoCodeUsage() is called after payment
• Check database connection
• Verify promo_code_id is passed correctly

Discount not applied in Stripe

• Stripe shows final amount only
• Store original amount in metadata for tracking
• Verify calculation logic is correct

Reference Files

• references/implementation_guide.md - Detailed implementation workflows
• references/stripe_integration.md - Stripe-specific patterns
• templates/promo_schema.sql - Database schema
• templates/hardcoded_codes_template.js - Quick implementation template
• templates/quick_reference_template.md - User reference doc template

Deliverables

Always provide user with:

1. Implementation code - Ready to paste into their project
2. Quick reference guide - MY_PROMO_CODES.md with their codes
3. Testing instructions - How to verify it works
4. Deployment steps - How to deploy changes

Example Complete Workflow

User says: "I need to add promo codes to my poker quiz app"

1. Discover: Run discovery script, find existing hardcoded system
2. Analyze: They have DISCOUNT_CODES object with 2 codes
3. Choose: Recommend extending existing system (Path A)
4. Implement: Add 10 new codes to their DISCOUNT_CODES object
5. Document: Create MY_PROMO_CODES.md with all codes
6. Test: Verify codes work on live site
7. Deliver: Send updated code + reference doc

User asks: "How do I remember my codes?"

Answer: "Your codes are in MY_PROMO_CODES.md (attached). They're also in your server.js file at line 159."

Success Criteria

✅ User can add promo codes in < 5 minutes (Path A)
✅ User has reference doc to remember codes
✅ Codes work on live site
✅ User understands how to add more codes
✅ (Optional) User has path to upgrade to database system