Coupons & Promo Codes

Create discount coupons and shareable promotion codes to reduce prices for specific users or campaigns.

Creating coupons

Coupons define the discount terms. A coupon is a reusable discount template — promotion codes are the shareable codes that apply a coupon to a subscription.

Navigate to Billing → Coupons → New Coupon in the dashboard.

Discount type

Duration

{
  "name": "3 Months 50% Off",
  "percent_off": 50,
  "duration": "repeating",
  "duration_in_months": 3
}

{
  "name": "$20 Welcome Credit",
  "amount_off": 2000,
  "currency": "usd",
  "duration": "once"
}

Promotion codes

Promotion codes are user-facing codes that users enter at checkout (e.g. LAUNCH50). Each promotion code is linked to a coupon and can have its own restrictions on top of the coupon's discount terms.

Creating a single promotion code

1. Open a coupon in the dashboard
2. Click Add Promotion Code
3. Enter a code (or leave blank to auto-generate one)
4. Set optional restrictions (max redemptions, expiry date, first-time customers only)

{
  "code": "LAUNCH50",
  "coupon_id": "cpn_abc123",
  "max_redemptions": 500,
  "expires_at": "2025-12-31T23:59:59Z",
  "first_time_only": true
}

Applying a promotion code at checkout

Pass the promotion code to the checkout session:

curl -X POST https://your-authgate-instance.com/api/proxy/billing/checkout \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "price_id": "price_abc123",
    "promotion_code": "LAUNCH50"
  }'

The discount is shown on the checkout summary and applied automatically to the first invoice (or all invoices, depending on the coupon's duration).

Bulk generation and CSV import

For email campaigns or partner codes, generate multiple promotion codes at once.

Bulk generate

In the dashboard, open a coupon and click Generate Codes in Bulk. Set:

• Quantity — number of codes to generate (max 10,000 per batch)
• Prefix — optional prefix for generated codes (e.g. PARTNER-)
• Length — total code length including prefix (8–20 characters)

Generated codes are available to download as a CSV immediately after generation.

CSV import

To import your own list of codes, upload a CSV with a single code column:

code
WELCOME2025
EARLY100
FRIEND50

Navigate to Billing → Coupons → [Coupon] → Import Codes and upload the file. AuthGate validates for duplicates and invalid characters before importing.

Redemption limits and expiry

Control how and when promotion codes can be used:

Coupon and promotion code redemption history is visible in the dashboard under Billing → Coupons → [Coupon] → Redemptions.