Skip to main content
POST
/
v1
/
subscriptions
/
coupons
JavaScript
import Hercules from '@usehercules/sdk';

const client = new Hercules({
  apiVersion: '2025-12-09',
  apiKey: process.env['HERCULES_API_KEY'], // This is the default and can be omitted
});

const coupon = await client.beta.subscriptions.coupons.create({ code: 'code' });

console.log(coupon.id);
{
  "id": "<string>",
  "created": "2023-11-07T05:31:56Z",
  "code": "<string>",
  "duration": "once",
  "times_redeemed": 0,
  "active": true,
  "name": "<string>",
  "percent_off": 123,
  "amount_off": 0,
  "currency": "<string>",
  "duration_in_months": 0,
  "max_redemptions": 0,
  "redeem_by": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

API key authentication. Include your API key in the Authorization header as: Bearer

Body

application/json

Request to create a discount coupon. Specify either percent_off or amount_off, not both.

​
code
string
required

The promo code customers will enter to apply the discount

​
name
string

Display name for the coupon (shown to customers)

​
percent_off
number

Percentage discount (1-100). Mutually exclusive with amount_off.

Required range: 1 <= x <= 100
​
amount_off
integer

Fixed discount in the smallest currency unit (e.g., cents). Mutually exclusive with percent_off.

Required range: -9007199254740991 <= x <= 9007199254740991
​
currency
string
default:usd

Three-letter ISO currency code for amount_off discounts

​
duration
enum<string>
default:once

How long the discount applies: once (first payment only), repeating (for duration_in_months), or forever

Available options:
once,
repeating,
forever
​
duration_in_months
integer

Number of months the discount applies when duration is 'repeating'

Required range: 0 <= x <= 9007199254740991
​
max_redemptions
integer

Maximum number of times this coupon can be redeemed

Required range: 0 <= x <= 9007199254740991
​
redeem_by
string<date-time>

Expiration date after which the coupon can no longer be redeemed

Response

201 - application/json

The created coupon object

A discount coupon that customers can apply during checkout using a promo code

​
id
string
required

Unique identifier for the entitlement

​
created
string<date-time>
required

Timestamp when the coupon was created

​
code
string
required

The promo code customers enter to apply the discount

​
duration
enum<string>
required

How long the discount applies: once (first payment only), repeating (for duration_in_months), or forever

Available options:
once,
repeating,
forever
​
times_redeemed
integer
required

Number of times this coupon has been successfully redeemed

Required range: -9007199254740991 <= x <= 9007199254740991
​
active
boolean
required

Whether the coupon is currently active and can be redeemed

​
name
string | null

Display name for the coupon (shown to customers)

​
percent_off
number | null

Percentage discount (1-100). Mutually exclusive with amount_off.

​
amount_off
integer | null

Fixed discount amount in the smallest currency unit (e.g., cents). Mutually exclusive with percent_off.

Required range: -9007199254740991 <= x <= 9007199254740991
​
currency
string | null

Three-letter ISO currency code for amount_off discounts

​
duration_in_months
integer | null

Number of months the discount applies when duration is 'repeating'

Required range: -9007199254740991 <= x <= 9007199254740991
​
max_redemptions
integer | null

Maximum number of times this coupon can be redeemed across all customers

Required range: -9007199254740991 <= x <= 9007199254740991
​
redeem_by
string<date-time> | null

Expiration date after which the coupon can no longer be redeemed