Redeem

A production-ready REST API for coupon management and validation built with Go and MongoDB. Perfect for e-commerce platforms, retail applications, or any system requiring flexible discount management.

Features

• Multi-type Coupons: One-time, multi-use, and time-based coupons
• Smart Validation: Context-aware validation with cart analysis
• Flexible Discounts: Percentage and fixed-amount discounts with product/category targeting
• High Performance: LRU cache with TTL for sub-millisecond responses
• Concurrency Safe: Mutex-based locking and atomic operations
• Complete API Documentation: OpenAPI 3.0 with Swagger UI

Quick Start

Using Docker (Recommended)

git clone https://github.com/MaheepTulsian/Redeem.git
cd Redeem
docker-compose up -d

Services will be available at:

• 🚀 API Server: http://localhost:8080
• 📚 API Documentation: http://localhost:8080/swagger/
• 🗄️ MongoDB: localhost:27017

Manual Setup

# 1. Environment setup
cp .env.example .env
# Edit .env with your MongoDB connection string

# 2. Install dependencies
go mod download

# 3. Run the application
go run cmd/server/main.go

API Endpoints

Core Endpoints

Endpoint	Method	Description
/health	GET	Health check
/api/v1/coupons/applicable	GET	Find applicable coupons for cart
/api/v1/coupons/validate	POST	Validate and apply coupon
/api/v1/admin/coupons	POST	Create new coupon (admin)
/api/v1/coupons/cache/stats	GET	Cache performance metrics

Example Usage

Get Applicable Coupons

curl "http://localhost:8080/api/v1/coupons/applicable" \
  -G \
  -d 'cart_items=[{"id":"product_001","category":"electronics","quantity":2,"price":25.0}]' \
  -d 'order_total=700' \
  -d 'user_id=user_001'

Validate Coupon

curl -X POST "http://localhost:8080/api/v1/coupons/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "coupon_code": "SAVE20",
    "cart_items": [
      {"id": "product_001", "category": "electronics", "quantity": 2, "price": 25.0}
    ],
    "order_total": 700,
    "user_id": "user_001"
  }'

Create Coupon

curl -X POST "http://localhost:8080/api/v1/admin/coupons" \
  -H "Content-Type: application/json" \
  -d '{
    "coupon_code": "NEWUSER25",
    "description": "25% off for new users",
    "usage_type": "multi_use",
    "max_uses_per_user": 1,
    "expiry_date": "2025-12-31T23:59:59Z",
    "min_order_value": 100,
    "discount_type": "percentage",
    "discount_value": 25,
    "discount_target": "inventory",
    "first_order_only": true,
    "is_active": true
  }'

Architecture

The system follows clean architecture principles:

Redeem/
├── cmd/server/          # Application entry point
├── internal/
│   ├── cache/           # LRU caching implementation
│   ├── db/              # Database layer & repositories
│   ├── handlers/        # HTTP request handlers
│   ├── middleware/      # HTTP middleware
│   ├── models/          # Data models & schemas
│   └── services/        # Business logic layer
├── docs/swagger/        # OpenAPI documentation
├── scripts/             # Database initialization scripts
└── docker-compose.yml   # Development environment

Key Components

Component	Technology	Purpose
API Layer	Gorilla Mux	HTTP routing and middleware
Business Logic	Go	Coupon validation and discount calculation
Caching	Custom LRU + TTL	Performance optimization
Database	MongoDB	Coupon and usage data persistence
Documentation	OpenAPI 3.0	Interactive API documentation

Database Schema

Coupons Collection

{
  "_id": ObjectId,
  "coupon_code": "string (unique)",
  "description": "string",
  "usage_type": "one_time | multi_use | time_based",
  "max_uses_per_user": number,
  "max_total_uses": number,
  "expiry_date": Date,
  "start_date": Date,
  "valid_start_hour": number, // 0-23
  "valid_end_hour": number,   // 0-23
  "applicable_product_ids": ["string"],
  "applicable_categories": ["string"],
  "excluded_product_ids": ["string"],
  "min_order_value": number,
  "discount_type": "percentage | fixed",
  "discount_value": number,
  "discount_target": "inventory | charges | both",
  "is_stackable": boolean,
  "is_auto_apply": boolean,
  "first_order_only": boolean,
  "is_active": boolean
}

Configuration

Environment Variables

# .env file
MONGO_URI=mongodb://localhost:27017/coupons
MONGO_DB_NAME=coupons
PORT=8080

Performance Settings

• Cache: 1000 items, 15min TTL
• MongoDB Pool: 5-100 connections
• HTTP Timeouts: 30s read/write, 120s idle

Development

Prerequisites

• Go 1.25+
• MongoDB 7.0+
• Docker (optional)

Building and Testing

# Run tests
go test ./...

# Build application
go build -o bin/redeem cmd/server/main.go

# Run with race detector
go run -race cmd/server/main.go

# Format code
go fmt ./...

Sample Test Data

The system includes sample coupons for testing:

• SAVE20: 20% off all products
• FIRST50: $50 off first orders
• ELECTRONICS15: 15% off electronics category

Use Cases

Perfect for:

• E-commerce platforms - Product discounts and promotional campaigns
• Retail applications - In-store and online coupon management
• Subscription services - New user incentives and retention offers
• Marketplace platforms - Vendor-specific and platform-wide discounts
• Mobile apps - Location-based and time-sensitive promotions

Performance

• Coupon Validation: < 50ms (cached)
• Cache Hit Ratio: > 80% typical usage
• Throughput: > 1000 req/s
• Concurrency: Safe with mutex protection

Features Deep Dive

Advanced Coupon Types

• Time-based: Hour restrictions (happy hour discounts)
• Category-specific: Target specific product categories
• Product exclusions: Exclude specific items from discounts
• Stackable coupons: Combine multiple discounts
• Auto-apply: Automatically apply best available coupons
• First-time user: Special discounts for new customers

Validation Rules

• Minimum/maximum order value requirements
• User-specific usage limits
• Global usage caps
• Date range restrictions
• Product applicability checks
• Cart composition analysis

Contributing

1. Follow Go best practices and conventions
2. Write tests for new features
3. Update API documentation for changes
4. Ensure Docker compatibility
5. Use semantic commit messages

License

MIT License - feel free to use this project for personal or commercial purposes.

---

Built with ❤️ using Go and MongoDB