Coupons

The CouponController and CouponService manage promotional coupons and discount codes. Coupons can provide percentage discounts, fixed amount discounts, or credits. They support usage limits, expiration dates, and plan restrictions.

Coupon Management

Create Coupon

Endpoint: POST /api/v1/billing/coupons

curl -X POST http://localhost:8087/api/v1/billing/coupons \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "code": "LAUNCH2026",
    "description": "Launch promotion - 20% off for 3 months",
    "discountType": "PERCENTAGE",
    "discountValue": 20,
    "maxRedemptions": 1000,
    "expiresAt": "2026-06-30T23:59:59",
    "applicablePlanIds": ["plan-pro", "plan-enterprise"],
    "durationMonths": 3
  }'

List Coupons

Endpoint: GET /api/v1/billing/coupons

Get Coupon

Endpoint: GET /api/v1/billing/coupons/:couponId

Deactivate Coupon

Endpoint: POST /api/v1/billing/coupons/:couponId/deactivate

Coupon Validation

Endpoint: POST /api/v1/billing/coupons/validate

Validates whether a coupon code can be applied to a specific tenant and plan.

curl -X POST http://localhost:8087/api/v1/billing/coupons/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "code": "LAUNCH2026",
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "planId": "plan-pro"
  }'

Response:

{
  "valid": true,
  "couponId": "c-001",
  "discountType": "PERCENTAGE",
  "discountValue": 20,
  "message": "Coupon is valid for this plan"
}

Coupon Redemption

Endpoint: POST /api/v1/billing/coupons/redeem

Applies a coupon to a tenant subscription.

curl -X POST http://localhost:8087/api/v1/billing/coupons/redeem \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "code": "LAUNCH2026",
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "subscriptionId": "sub-001"
  }'

Discount Types

Type	Description	Example
`PERCENTAGE`	Percentage discount on subscription cost	20% off monthly bill
`FIXED_AMOUNT`	Fixed currency amount off the bill	$50 off
`CREDIT`	Account credit added to balance	$100 credit

Coupon Restrictions

Restriction	Description
`maxRedemptions`	Maximum number of times the coupon can be used across all tenants
`maxRedemptionsPerTenant`	Maximum uses per individual tenant
`expiresAt`	Coupon expiration date
`applicablePlanIds`	List of plans the coupon can be applied to
`durationMonths`	Number of months the discount applies
`minimumSpend`	Minimum invoice amount required to use the coupon

Referral Codes

The ReferralService extends the coupon system with referral-based discounts. When a referred tenant signs up and subscribes, both the referrer and the new tenant receive credits or discounts.

Quotas Realtime Cost