Strapi Plugin - Coupon Management

A centralized coupon management system for Strapi that handles validation, redemption, and tracking across multiple service domains.

Requirements

• Strapi 5.0.0 or higher
• Node.js 18.0.0 or higher
• npm 6.0.0 or higher
• PostgreSQL, MySQL, or SQLite

Features

• Centralized coupon creation and management
• Flexible discount types (percentage, flat)
• Max discount cap for percentage coupons (e.g., 50% off, max 100 AED)
• Per-user and global usage limits
• Validity period enforcement
• User restriction lists (phone number blocklist)
• Complete redemption audit trail
• Bulk CSV import (up to 10,000 coupons)
• RESTful API endpoints
• Race condition protection via optimistic locking
• Rate limiting on public endpoints
• TypeScript with full type definitions

Installation

1. Install the package

# npm
npm install mumz-strapi-plugin-coupon

# yarn
yarn add mumz-strapi-plugin-coupon

# From GitHub (private repo)
npm install git+https://github.com/mumzworld-tech/mumz-services-coupons-strapi-plugin.git#v3.1.0

2. Enable the plugin

Add to your Strapi project's config/plugins.ts (or config/plugins.js):

// config/plugins.ts
export default () => ({
  coupon: {
    enabled: true,
    resolve: './node_modules/mumz-strapi-plugin-coupon',
  },
});

3. Build and restart Strapi

npm run build
npm run develop

On first startup, Strapi auto-creates the coupons and redemptions tables. No manual migration needed.

4. Configure permissions (optional)

By default, all routes have auth: false. To restrict admin endpoints:

1. Go to Settings > Roles > Public in Strapi admin
2. Under the Coupon plugin, enable only the endpoints you want public (typically validate and redeem)
3. Disable create, update, delete, bulk-create for public access

API Endpoints

Base path: /api/coupon

| Method | Path | Description | Rate Limit | |--------|------|-------------|------------| | POST | /validate | Validate coupon for a user/order | 10 req/min | | POST | /redeem | Redeem coupon after payment | 5 req/min | | POST | / | Create a single coupon | None | | GET | / | List all coupons | None | | GET | /:id | Get coupon by ID | None | | PUT | /:id | Update coupon | None | | DELETE | /:id | Delete coupon | None | | GET | /csv-template | Download CSV template | None | | POST | /bulk-create | Bulk create from CSV data | None |

Validate Coupon

Check if a coupon is valid for a user and calculate the discount.

POST /api/coupon/validate
Content-Type: application/json

{
  "couponCode": "SUMMER25",
  "phoneNumber": "971501234567",
  "orderAmount": 500
}

Response (success):

{
  "isValid": true,
  "discountType": "percentage",
  "discountValue": 25,
  "maxDiscountAmount": 100,
  "discountAmount": 100,
  "finalAmount": 400,
  "message": "Coupon applied successfully."
}

Note: discountAmount is 100 (capped), not 125 (25% of 500), because maxDiscountAmount is 100.

Response (error):

{
  "isValid": false,
  "errorCode": "COUPON_EXPIRED",
  "message": "This coupon has expired."
}

Redeem Coupon

Redeem after successful payment. Creates an audit trail and increments usage counter.

POST /api/coupon/redeem
Content-Type: application/json

{
  "couponCode": "SUMMER25",
  "phoneNumber": "971501234567",
  "orderId": "ORD-12345",
  "orderAmount": 500
}

Response:

{
  "success": true,
  "message": "Coupon redeemed successfully.",
  "redemptionId": "redeem_42"
}

Create Coupon

POST /api/coupon
Content-Type: application/json

{
  "code": "SUMMER25",
  "discountType": "percentage",
  "discountValue": 25,
  "maxDiscountAmount": 100,
  "maxUsage": 1000,
  "maxUsagePerUser": 1,
  "validFrom": "2025-06-01T00:00:00.000Z",
  "validTo": "2025-08-31T23:59:59.000Z",
  "description": "Summer sale - 25% off, max 100 AED",
  "userRestrictions": ["971500000000"]
}

Bulk Create (CSV)

POST /api/coupon/bulk-create
Content-Type: application/json

{
  "coupons": [
    {
      "_row": 1,
      "code": "BULK001",
      "discountType": "percentage",
      "discountValue": 20,
      "maxDiscountAmount": 50,
      "maxUsage": 100,
      "maxUsagePerUser": 1,
      "validFrom": "2025-01-01T00:00:00.000Z",
      "validTo": "2025-12-31T23:59:59.000Z"
    }
  ]
}

Coupon Schema

| Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | code | string | Yes | - | Unique, 3-50 uppercase alphanumeric | | discountType | enum | Yes | percentage | percentage or flat | | discountValue | decimal | Yes | - | Discount value (% or AED) | | maxDiscountAmount | decimal | No | null | Max discount cap in AED (percentage only) | | maxUsage | integer | No | null | Total redemptions allowed (null = unlimited) | | maxUsagePerUser | integer | No | null | Per-user redemptions (null = 1, 0 = unlimited) | | currentUsage | integer | Yes | 0 | Current total redemption count | | validFrom | datetime | Yes | - | Start of validity period | | validTo | datetime | Yes | - | End of validity period | | isActive | boolean | Yes | true | Manual on/off toggle | | description | text | No | null | Admin-facing description | | userRestrictions | json | No | null | Array of blocked phone numbers |

maxUsagePerUser Logic

| Value | Behavior | |-------|----------| | null | 1 use per user (default) | | 0 | Unlimited uses per user | | N | N uses per user |

maxDiscountAmount Logic

Only applies when discountType is percentage. Ignored for flat discounts.

| Coupon | Order | Raw Discount | Cap | Final Discount | |--------|-------|-------------|-----|----------------| | 50% off, max 100 AED | 500 AED | 250 AED | 100 AED | 100 AED | | 50% off, max 100 AED | 150 AED | 75 AED | 100 AED | 75 AED | | 50% off, no cap | 500 AED | 250 AED | - | 250 AED | | 10 AED flat | 500 AED | 10 AED | ignored | 10 AED |

Error Codes

| Code | Description | |------|-------------| | COUPON_NOT_FOUND | Coupon code does not exist | | COUPON_EXPIRED | Coupon is inactive or outside validity period | | COUPON_ALREADY_USED | Per-user usage limit reached | | USAGE_LIMIT_REACHED | Global usage limit reached | | INVALID_REQUEST | Invalid input (bad phone, negative amount, etc.) | | USER_RESTRICTED | Phone number is on the blocklist |

CSV Bulk Import

Template columns

code,discountType,discountValue,maxDiscountAmount,maxUsage,maxUsagePerUser,validFrom,validTo,isActive,description,userRestrictions

Download template via GET /api/coupon/csv-template.

Admin Panel

The plugin adds a Coupon Bulk menu item in the Strapi admin sidebar. From there you can:

1. Download the CSV template
2. Upload a CSV file to bulk create coupons
3. View import results (created/failed with row-level errors)

Integration Guide

Typical flow for client applications

1. Customer enters coupon code at checkout
2. Client calls POST /api/coupon/validate with code + phone + orderAmount
3. If isValid=true, display discountAmount and finalAmount to customer
4. After payment succeeds, call POST /api/coupon/redeem with orderId
5. Store the redemptionId for reference

Concurrent redemption safety

The plugin uses optimistic locking on currentUsage. If two requests try to redeem the same coupon simultaneously, only one succeeds. The other gets USAGE_LIMIT_REACHED. No external locking or Redis required.

Environment considerations

• Development: Schema auto-syncs on Strapi restart
• Production: The new maxDiscountAmount column is nullable with default null, so existing data is unaffected. No manual migration needed.