Enterprise-grade coupon and discount management system for Shopify stores. Build powerful coupons with 20+ condition types, 8 reward types, bulk code generation, and detailed analytics.

• Features
• Quick Start
• Architecture
• Condition Types
• Reward Types
• API Reference
• Billing Plans
• Development
• Testing
• Deployment
• Troubleshooting

• Visual Rule Builder: Drag-and-drop interface for creating complex coupon conditions with AND/OR logic
• 20+ Condition Types: Cart, customer, product, collection, and time-based conditions
• 8 Reward Types: Percentage, fixed amount, free shipping, BOGO, tiered discounts
• Bulk Code Generation: Generate thousands of unique codes instantly
• Analytics Dashboard: Track usage, revenue impact, and conversion rates
• 4-Tier Billing: Free, Starter ($9/mo), Pro ($29/mo), Enterprise ($99/mo)
• Redis Caching: High-performance coupon validation
• Reusable Templates: Save and reuse common discount configurations
• Shopify Extensions: Native checkout UI and discount functions

• Node.js >= 20.0.0
• Docker and Docker Compose
• Shopify Partner Account
• ngrok (for development)

1. Clone and install dependencies

git clone <repository-url>
cd coupon-engine
npm install

2. Set up environment variables

cp .env.example .env

Edit .env with your Shopify app credentials:

SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret
SHOPIFY_APP_URL=https://your-ngrok-url.ngrok-free.app
SCOPES=read_products,read_orders,read_customers,read_discounts,write_discounts
DATABASE_URL=postgresql://coupon_user:coupon_pass@localhost:5432/coupon_engine
REDIS_URL=redis://localhost:6379

3. Start Docker services

npm run docker:up

This starts PostgreSQL (port 5432), Redis (port 6379), and Adminer (port 8080).

4. Initialize database

npm run setup        # Generate Prisma client and push schema
npm run db:seed      # Seed with sample data (optional)

5. Start development server

npm run dev

The app will be available at your ngrok URL.

coupon-engine/
├── app/
│   ├── components/          # React components
│   │   └── rules/          # Rule Builder components
│   │       ├── RuleBuilder.tsx
│   │       ├── RuleGroup.tsx
│   │       ├── ConditionRow.tsx
│   │       └── RewardBuilder.tsx
│   ├── routes/             # Remix routes
│   │   ├── app._index.tsx  # Dashboard
│   │   ├── app.coupons.*   # Coupon management
│   │   ├── app.billing.*   # Billing pages
│   │   ├── app.analytics.* # Analytics pages
│   │   ├── app.templates.* # Template management
│   │   ├── app.settings.*  # Settings
│   │   └── api.*           # API endpoints
│   ├── services/           # Business logic
│   │   ├── coupon.server.ts       # Coupon CRUD
│   │   ├── billing.server.ts      # Billing operations
│   │   ├── rule-engine.server.ts  # Condition evaluation
│   │   ├── code-generator.server.ts # Code generation
│   │   ├── analytics.server.ts    # Analytics queries
│   │   └── redis.server.ts        # Caching layer
│   └── types/              # TypeScript types
│       ├── condition.ts    # Condition types
│       ├── reward.ts       # Reward types
│       └── billing.ts      # Billing types
├── extensions/
│   ├── checkout-ui/        # Checkout UI extension
│   └── discount-function/  # Discount function extension
├── prisma/
│   ├── schema.prisma       # Database schema
│   └── seed.ts            # Seed data
└── test/                   # Test files
    ├── setup.ts           # Test configuration
    └── services/          # Service tests

Validates a coupon code against cart and customer data.

Endpoint: POST /api/validate-coupon

Request:

{
  "code": "SUMMER20",
  "cartTotal": 150.00,
  "itemCount": 3,
  "totalQuantity": 5,
  "customerEmail": "customer@example.com",
  "customerOrderCount": 2,
  "customerTotalSpent": 500.00,
  "productIds": ["gid://shopify/Product/123"],
  "collectionIds": ["gid://shopify/Collection/456"]
}

Response:

{
  "valid": true,
  "couponId": "clx...",
  "rewards": [
    {
      "type": "percentage_off",
      "value": 20,
      "appliesTo": "cart"
    }
  ],
  "message": "Coupon applied successfully"
}

Error Response:

{
  "valid": false,
  "error": "INVALID_CODE",
  "message": "Coupon code not found"
}

Records coupon usage after checkout completion.

Endpoint: POST /api/track-usage

Request:

{
  "couponId": "clx...",
  "code": "SUMMER20",
  "orderId": "gid://shopify/Order/123",
  "customerId": "gid://shopify/Customer/456",
  "orderTotal": 120.00,
  "discountAmount": 30.00
}

Response:

{
  "success": true,
  "usageId": "clx..."
}

Generates bulk coupon codes asynchronously.

Endpoint: POST /api/generate-codes

Request:

{
  "couponId": "clx...",
  "count": 100,
  "prefix": "SUMMER",
  "length": 8
}

Response:

{
  "success": true,
  "batchId": "clx...",
  "codesGenerated": 100,
  "codes": ["SUMMER-ABCD1234", "SUMMER-EFGH5678", ...]
}

# Development
npm run dev              # Start Shopify app dev server
npm run dev:remix        # Start Remix dev only

# Database
npm run db:push         # Push schema changes
npm run db:studio       # Open Prisma Studio
npm run db:seed         # Seed database
npm run db:reset        # Reset database
npm run db:migrate      # Run migrations

# Docker
npm run docker:up       # Start containers
npm run docker:down     # Stop containers
npm run docker:logs     # View logs
npm run docker:reset    # Reset with fresh data
npm run docker:ps       # Container status

# Testing
npm run test            # Run tests
npm run test:watch      # Run tests in watch mode
npm run test:coverage   # Run with coverage

# Build & Quality
npm run build           # Build for production
npm run typecheck       # TypeScript check
npm run lint            # ESLint check

1. Add type to app/types/condition.ts:

export type ConditionType =
  | "cart_total"
  | "your_new_condition"  // Add here
  | ...

2. Add evaluation logic in app/services/rule-engine.server.ts:

case "your_new_condition":
  actualValue = context.your.field;
  passed = compareNumeric(actualValue, operator, value as number);
  break;

3. Add UI in app/components/rules/ConditionRow.tsx:

const conditionOptions = [
  { label: "Your New Condition", value: "your_new_condition" },
  ...
];

4. Add validation in rule-engine.server.ts:

case "your_new_condition":
  if (typeof condition.value !== "number") {
    errors.push("your_new_condition requires a numeric value");
  }
  break;

1. Add type to app/types/reward.ts:

export type RewardType =
  | "percentage_off"
  | "your_new_reward"  // Add here
  | ...

2. Update app/components/rules/RewardBuilder.tsx with UI

3. Update discount function extension to handle the new type

Tests are written using Vitest with 100% mock coverage for external services.

# Run all tests
npm run test

# Run in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

test/
├── setup.ts                    # Global test setup with mocks
└── services/
    ├── rule-engine.test.ts     # Rule engine tests (39 tests)
    └── billing.test.ts         # Billing helper tests (26 tests)

• Rule Engine: Condition evaluation, logical operators (AND/OR), nested groups, edge cases
• Billing: Plan configuration, feature checking, limits, upgrade prompts

• Set NODE_ENV=production
• Configure production database URL
• Configure production Redis URL
• Run npm run build
• Run npx prisma migrate deploy
• Set up monitoring (Sentry, DataDog, etc.)
• Configure webhook endpoints
• Test billing flow with live payments
• Deploy Shopify extensions

# Build the app
npm run build

# Deploy extensions
npx shopify app deploy

Database connection failed

# Check Docker containers are running
npm run docker:ps

# Reset Docker containers
npm run docker:reset

Redis connection failed

# Verify Redis is running
docker exec -it coupon-redis redis-cli ping

TypeScript errors

# Run type check
npm run typecheck

# Regenerate Prisma client
npx prisma generate

Build fails

# Clear build cache
rm -rf build node_modules/.cache
npm run build

Extension not loading

# Check extension build
cd extensions/checkout-ui
npm install
npm run build

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for new functionality
4. Ensure all tests pass (npm run test)
5. Ensure TypeScript passes (npm run typecheck)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Private - All rights reserved