Skip to main content
POST
/
api
/
v1
/
subscriptions
/
coupons
Create a coupon
curl --request POST \
  --url http://localhost:7701/api/v1/subscriptions/coupons \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "code": "SUMMER20",
  "name": "20% off Summer Sale",
  "discount_type": "percentage",
  "discount_value": 20,
  "valid_from": "2026-07-01",
  "description": "Applies to all monthly plans.",
  "valid_until": "2026-08-31",
  "max_redemptions": 100,
  "max_cycles": 3
}
'
{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "code": "SUMMER20",
    "name": "20% off Summer Sale",
    "description": "<string>",
    "discount_type": "percentage",
    "discount_value": 20,
    "max_redemptions": 100,
    "redemptions_count": 5,
    "max_cycles": 3,
    "valid_from": "2023-11-07T05:31:56Z",
    "valid_until": "2023-11-07T05:31:56Z",
    "is_active": true,
    "created_at": "2023-11-07T05:31:56Z"
  }
}

Authorizations

​
X-API-Key
string
header
required

Company API key. Send in the X-API-Key header.

Body

application/json
​
code
string
required

Unique alphanumeric code (max 50 chars). Case-sensitive.

Example:

"SUMMER20"

​
name
string
required

Display name for the coupon (max 255 chars).

Example:

"20% off Summer Sale"

​
discount_type
enum<string>
required

How the discount is calculated.

Available options:
percentage,
fixed
Example:

"percentage"

​
discount_value
integer
required

Discount amount: percentage (1–100) when type is percentage; cents when type is fixed.

Example:

20

​
valid_from
string<date>
required

Date from which the coupon can be applied.

Example:

"2026-07-01"

​
description
string | null

Optional description (max 1000 chars).

Example:

"Applies to all monthly plans."

​
valid_until
string<date> | null

Expiry date (must be after valid_from). Null = no expiry.

Example:

"2026-08-31"

​
max_redemptions
integer | null

Maximum total uses across all subscriptions. Null = unlimited.

Example:

100

​
max_cycles
integer | null

Maximum billing cycles the discount applies per subscription. Null = applies forever.

Example:

3

Response

Coupon created

​
data
object