Create a Coupon

Create percentage or fixed-amount discount coupons via API or dashboard.

Via API

curl -X POST https://us.api.flexprice.io/v1/coupons \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Sale",
    "type": "percentage",
    "percentage_off": "15.00",
    "cadence": "once",
    "coupon_code": "SUMMER15",
    "redeem_after": "2025-07-01T00:00:00Z",
    "redeem_before": "2025-08-31T23:59:59Z",
    "max_redemptions": 1000
  }'

Response

{
  "id": "coup_01abc123",
  "name": "Summer Sale",
  "type": "percentage",
  "percentage_off": "15.00",
  "cadence": "once",
  "coupon_code": "SUMMER15",
  "redeem_after": "2025-07-01T00:00:00Z",
  "redeem_before": "2025-08-31T23:59:59Z",
  "max_redemptions": 1000,
  "total_redemptions": 0,
  "status": "active"
}

Request fields

Field	Type	Required	Description
name	string	Yes	Display name shown in the dashboard and invoice details
type	string	Yes	percentage or fixed
cadence	string	Yes	once, repeated, or forever
percentage_off	decimal string	When type=percentage	Discount as a percent, e.g. "15.00" for 15%
amount_off	decimal string	When type=fixed	Flat discount amount, e.g. "50.00"
currency	string	When type=fixed	ISO currency code, e.g. "USD"
duration_in_periods	int	When cadence=repeated	Number of billing cycles the discount applies. Must not be set for other cadences.
coupon_code	string	No	Human-readable code customers can enter to redeem (e.g. "SUMMER15"). Auto-generated if omitted.
redeem_after	timestamp	No	Earliest time a new association can be created
redeem_before	timestamp	No	Expiry. New associations cannot be created after this time.
max_redemptions	int	No	Cap on total associations across all subscriptions
metadata	object	No	Key-value pairs for your own tracking

Cadence behaviour

Cadence	What happens
once	Discount applies to the first invoice in the association window only
repeated	Discount applies for duration_in_periods consecutive billing cycles
forever	Discount applies to every invoice for the life of the subscription

Fixed-amount coupon

For a fixed dollar amount off, set type: fixed and provide both amount_off and currency:

curl -X POST https://us.api.flexprice.io/v1/coupons \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Customer Credit",
    "type": "fixed",
    "amount_off": "50.00",
    "currency": "USD",
    "cadence": "once"
  }'

Recurring coupon

To discount multiple billing cycles, use cadence: repeated with duration_in_periods:

curl -X POST https://us.api.flexprice.io/v1/coupons \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quarterly Promo",
    "type": "percentage",
    "percentage_off": "20.00",
    "cadence": "repeated",
    "duration_in_periods": 3
  }'

This applies a 20% discount for the first 3 billing cycles of each association.

Manage existing coupons

# List coupons
curl https://us.api.flexprice.io/v1/coupons \
  -H "x-api-key: <API_KEY>"

# Get a coupon
curl https://us.api.flexprice.io/v1/coupons/<coupon_id> \
  -H "x-api-key: <API_KEY>"

# Search coupons by status
curl -X POST https://us.api.flexprice.io/v1/coupons/search \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

# Update a coupon (only name and metadata are updatable)
curl -X PUT https://us.api.flexprice.io/v1/coupons/<coupon_id> \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Summer Sale 2025" }'

# Delete a coupon
curl -X DELETE https://us.api.flexprice.io/v1/coupons/<coupon_id> \
  -H "x-api-key: <API_KEY>"

Via dashboard

Go to Product Catalog > Coupons > Create Coupon and fill in the same fields described above.

Next step

Apply the coupon to a subscription at creation time or post-creation via the subscription modification API.