Skip to main content

​
Via API

curl -X POST https://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

FieldTypeRequiredDescription
namestringYesDisplay name shown in the dashboard and invoice details
typestringYespercentage or fixed
cadencestringYesonce, repeated, or forever
percentage_offdecimal stringWhen type=percentageDiscount as a percent, e.g. "15.00" for 15%
amount_offdecimal stringWhen type=fixedFlat discount amount, e.g. "50.00"
currencystringWhen type=fixedISO currency code, e.g. "USD"
duration_in_periodsintWhen cadence=repeatedNumber of billing cycles the discount applies. Must not be set for other cadences.
coupon_codestringNoHuman-readable code customers can enter to redeem (e.g. "SUMMER15"). Auto-generated if omitted.
redeem_aftertimestampNoEarliest time a new association can be created
redeem_beforetimestampNoExpiry. New associations cannot be created after this time.
max_redemptionsintNoCap on total associations across all subscriptions
metadataobjectNoKey-value pairs for your own tracking

​
Cadence behaviour

CadenceWhat happens
onceDiscount applies to the first invoice in the association window only
repeatedDiscount applies for duration_in_periods consecutive billing cycles
foreverDiscount 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://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://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://api.flexprice.io/v1/coupons \
  -H "x-api-key: <API_KEY>"

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

# Search coupons by status
curl -X POST https://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://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://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.