Coupons API

Manage discount coupons for your Stripe integration. Coupons provide discounts on subscriptions or invoice items.

Endpoints

GET /api/admin/stripe/coupons

List all coupons from your Stripe account.

Query Parameters

Parameter	Type	Description
`limit`	number	Maximum number of coupons to return (default: 10, max: 100)
`starting_after`	string	Cursor for pagination

Response

{
  "data": [
    {
      "id": "coupon_1234567890",
      "object": "coupon",
      "name": "Summer Sale",
      "amount_off": null,
      "percent_off": 20,
      "currency": null,
      "duration": "once",
      "duration_in_months": null,
      "max_redemptions": 100,
      "redeem_by": 1234567890,
      "times_redeemed": 5,
      "valid": true,
      "created": 1234567890
    }
  ],
  "has_more": false
}

POST /api/admin/stripe/coupons

Create a new coupon.

Request Body - Percentage Discount

{
  "id": "SUMMER20",
  "name": "Summer Sale 20%",
  "percent_off": 20,
  "duration": "once",
  "max_redemptions": 100
}

Request Body - Fixed Amount Discount

{
  "id": "SAVE10",
  "name": "$10 Off",
  "amount_off": 1000,
  "currency": "usd",
  "duration": "once"
}

Request Body - Repeating Duration

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

Parameters

Parameter	Type	Required	Description
`id`	string	No	Unique identifier for the coupon (auto-generated if not provided)
`name`	string	No	Display name for the coupon
`percent_off`	number	*	Percentage discount (required if not using `amount_off`)
`amount_off`	number	*	Fixed amount discount in cents (required if not using `percent_off`)
`currency`	string	*	Required when using `amount_off` (e.g., "usd")
`duration`	string	Yes	Discount duration: `once`, `forever`, or `repeating`
`duration_in_months`	number	*	Required if `duration` is `repeating`
`max_redemptions`	number	No	Maximum number of times the coupon can be redeemed
`redeem_by`	timestamp	No	Unix timestamp after which the coupon expires
`metadata`	object	No	Key-value pairs for storing additional information

Response

{
  "id": "SUMMER20",
  "object": "coupon",
  "name": "Summer Sale 20%",
  "amount_off": null,
  "percent_off": 20,
  "currency": null,
  "duration": "once",
  "duration_in_months": null,
  "max_redemptions": 100,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true,
  "metadata": {},
  "created": 1234567890
}

DELETE /api/admin/stripe/coupons

Delete a coupon. Deleted coupons can no longer be redeemed, but existing subscriptions using the coupon will continue to receive the discount.

Request Body

{
  "id": "SUMMER20"
}

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The coupon ID to delete

Response

{
  "id": "SUMMER20",
  "object": "coupon",
  "deleted": true
}

Duration Types

Duration	Description
`once`	Discount applies only to the first invoice
`repeating`	Discount applies for a limited number of months
`forever`	Discount applies to all invoices indefinitely

Example Usage

Create a Percentage Coupon

curl -X POST /api/admin/stripe/coupons \
  -H "Content-Type: application/json" \
  -d '{
    "id": "WELCOME25",
    "name": "Welcome 25% Off",
    "percent_off": 25,
    "duration": "once",
    "max_redemptions": 500
  }'

Create a Fixed Amount Coupon

curl -X POST /api/admin/stripe/coupons \
  -H "Content-Type: application/json" \
  -d '{
    "id": "SAVE5",
    "name": "$5 Off",
    "amount_off": 500,
    "currency": "usd",
    "duration": "once"
  }'

Create a Multi-Month Discount

curl -X POST /api/admin/stripe/coupons \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ANNUAL30",
    "name": "30% Off for 12 Months",
    "percent_off": 30,
    "duration": "repeating",
    "duration_in_months": 12
  }'

List All Coupons

curl /api/admin/stripe/coupons?limit=20

Delete a Coupon

curl -X DELETE /api/admin/stripe/coupons \
  -H "Content-Type: application/json" \
  -d '{
    "id": "SUMMER20"
  }'

Coupons

On this page