Coupons & Promo Codes

The atomic discount unit on ABc. An owner (or platform admin) generates a code, configures who/when/how-much, and the system applies it deterministically at checkout — on the public site or in a manual booking. Every redemption is tracked, capped and audit-logged.

Discount types

Configurable rules — every coupon carries these

Lifecycle states

Coupons list UI

Create / edit coupon — UI

Where coupons get applied

Public checkout — code entry

Validation logic — order of checks

1. Code exists & is active

   Otherwise: "That code isn't valid."

2. Within booking window

   Today must be between valid_from and valid_until. Otherwise: "This code has expired."

3. Stay window (if set)

   Booking's check-in date must be in stay_from..stay_until. Otherwise: "Not valid for these dates."

4. Property + room-type scope

   This booking's property and room type must match scope. Otherwise: "Not valid for this property."

5. Channel scope

   Booking source must be in channels. OTA bookings always rejected. Otherwise: "Not valid for OTA bookings."

6. Min booking value & min nights

   Otherwise: "Spend ₹X more to use this code."

7. Per-guest cap

   How many times has this email/phone already used this code? Otherwise: "You've already used this code."

8. Global cap

   max_total_uses not yet reached. Otherwise: "This code is fully redeemed."

9. First-time-only check

   If first_time_only, the guest must have zero prior confirmed bookings. Otherwise: "Only for new guests."

10. Compute discount

    Apply value, then cap. Return discount amount + line label.

Data model

API contract

// Request — sent during checkout when a user enters a code
{
  "code": "SUMMER25",
  "booking_draft": {
    "property_id": "prp_…",
    "room_type_id": "rt_…",
    "check_in": "2026-07-12",
    "check_out": "2026-07-15",
    "subtotal": 12600,
    "channel": "direct"
  },
  "guest": { "email": "priya@...", "phone": "+91…" }
}

// Response — 200 valid
{
  "valid": true,
  "coupon_id": "cpn_01HX…",
  "label": "SUMMER25 — 25 % off (capped at ₹2,000)",
  "discount_amount": 2000,
  "new_subtotal": 10600
}

// Response — 422 invalid (one example)
{
  "valid": false,
  "reason": "channel_excluded",
  "message": "This code isn't valid for OTA bookings."
}

Cancellation & the cap

Anti-abuse

• Velocity limits — max 5 code-validation attempts per IP per minute (prevents brute-force guessing).
• Code complexity — system-generated codes are 8 random chars (≈ 2.8 × 10¹² combos); owner-typed codes must be ≥ 4 chars.
• Per-guest cap — enforced by verified email AND verified phone (anti same-person-two-accounts).
• First-time check — runs against all confirmed bookings for this phone OR email, across all owners.
• Audit log — every coupon create/edit/disable + every redemption + every void written to audit_log.
• Suspicious-burst alert — if a single coupon hits 50 redemptions in <1 hour, owner gets an alert.

Integration with other modules

MVP vs later