Coupons

Coupons are promotional codes that customers can redeem to get discounts on purchases and invoices.

Coupon Fields

Field	Description
Code	Unique code, stored in uppercase
Name	Internal coupon name
Description	Promotion details
Discount type	percentage or fixed_amount
Discount value	Percentage or amount in subcents
Currency	Default: BRL
Minimum purchase	Minimum order amount to use the coupon
Maximum discount	Discount cap (for percentage coupons)
Total usage limit	Maximum redemptions allowed
Per-customer limit	Maximum redemptions per billing account
Valid from / until	Validity period
Applies to	Specific plans and/or products (JSON)
Excludes	Excluded plans and/or products (JSON)
Active	Whether the coupon is enabled

Coupon Validation

When validating a coupon, the system checks:

1. The coupon exists and the code matches
2. The coupon is active (isActive = true)
3. It is within the validity period
4. The total usage limit has not been reached
5. The per-customer usage limit has not been reached
6. The purchase meets the minimum amount

Discount Calculation

If percentage: discount = subtotal × percentage / 100
If fixed: discount = discount_value

Apply cap: discount = min(discount, maxDiscountCents)
Cannot exceed subtotal: discount = min(discount, subtotal)

Redeeming a Coupon

When applying a coupon:

1. Validates all conditions
2. Creates a CouponRedemption record with the discount amount
3. Increments the coupon's usage counter
4. Returns the redemption with the discounted amount

The process is atomic (transaction) to prevent race conditions.

Operations

• Activate/Deactivate: Controls whether the coupon can be validated
• Delete: Only if never used (no redemptions recorded)
• Update: Code, name, limits, dates, and values are editable

Redemption Report

For each coupon, the system tracks:

• Who redeemed it (billing account)
• When it was redeemed
• Discount amount applied
• Associated invoice (optional)