Coupon Overview

Authentication

All coupon endpoints support multiple authentication methods:

Recommended for frontend apps: Use JWT authentication. Your proxy server issues JWTs after user login, and the frontend calls Phoenix APIs directly with the token.

See Getting Started for authentication setup details.

Key Features

• Reward Coupons: Grant reward items to users upon redemption
• Custom Codes: Support for promotional codes like NEWYEAR2025
• Auto-Generation: Automatically generate coupons when users reach milestones
• Bulk Generation: Generate coupons for multiple users at once
• Start/Expiration Dates: Control when coupons become valid and expire
• Code Validation: Validate coupon codes before redemption
• Redemption Tracking: Track coupon usage and redemption history
• Case Sensitivity Control: Configure whether codes are case-sensitive

How Coupons Work

All coupons are reward-based - they grant a configured reward item when redeemed. The workflow is:

1. Create a Reward Item - Define what the user receives (points, virtual goods, etc.)
2. Create a Coupon Definition - Configure how coupons are generated and used
3. Generate Coupons - Bulk generate for users, or let auto-generation handle it
4. Users Redeem - When a user enters a valid code, they receive the reward

Code Generation

Coupons support two code formats:

Random Codes

Automatically generated alphanumeric codes:

{
  "code_format": "random",
  "code_prefix": "REWARD",
  "code_length": 8
}

This generates codes like REWARD8X4F2K9P.

Custom Codes

Use a specific promotional code:

{
  "code_format": "custom",
  "custom_code": "NEWYEAR2025"
}

All users who receive this coupon will have the same code (useful for promotional campaigns).

Case Sensitivity

By default, coupon codes are case-insensitive. This means SAVE10, save10, and Save10 are treated as the same code.

To enable case-sensitive codes:

{
  "case_sensitive": true
}

When case_sensitive: false (default):

• Code lookup uses case-insensitive matching
• Users can enter codes in any case

When case_sensitive: true:

• Code lookup requires exact case matching
• REWARD10 and reward10 are different codes

Start and Expiration Dates

Control when coupons become valid:

{
  "starts_at": "2025-01-01T00:00:00Z",
  "expires_at": "2025-12-31T23:59:59Z"
}

• starts_at: Coupon is invalid before this time (returns "Coupon not yet active")
• expires_at: Coupon is invalid after this time (returns "Coupon has expired")
• Both are optional - omit for no time restrictions

Usage Limits

Control how many times a coupon can be used:

{
  "usage_limit": {
    "limit_type": "per_user",
    "max_uses": 1
  }
}

• per_user: Each user can use their coupon max_uses times
• global: Total uses across all users (first-come-first-served)
• unlimited: No usage limit

Auto-Generation

Coupons can be automatically generated when certain events occur:

Streak Milestone

Generate a coupon when a user reaches a streak milestone:

{
  "auto_generate": {
    "enabled": true,
    "trigger": "streak_milestone",
    "trigger_config": {
      "streak_id": "uuid-of-streak-definition",
      "milestone_threshold": 7
    }
  }
}

Achievement Completion

Generate a coupon when a user completes an achievement:

{
  "auto_generate": {
    "enabled": true,
    "trigger": "achievement_completed",
    "trigger_config": {
      "achievement_id": "uuid-of-achievement-definition"
    }
  }
}

Leaderboard Rank

Generate a coupon when a user reaches a specific rank:

{
  "auto_generate": {
    "enabled": true,
    "trigger": "leaderboard_rank",
    "trigger_config": {
      "leaderboard_id": "uuid-of-leaderboard",
      "rank_threshold": 10
    }
  }
}

Definition Status

Coupon definitions have the following statuses:

• active: Processing events, generating coupons normally
• paused: No generation, no processing (existing coupons still valid)
• archived: Soft-deleted, no processing, history preserved

Coupon Status

Individual user coupons have the following statuses:

• active: Available for redemption
• redeemed: Already used
• expired: Past expiration date
• revoked: Manually revoked by admin

Next Steps

• Creating Coupons - Learn how to create coupon definitions
• Redeeming Coupons - Learn how to validate and redeem coupons