List 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
});

// Automatically fetches more pages as needed.
for await (const coupon of client.beta.subscriptions.coupons.list()) {
  console.log(coupon.id);
}

{
  "data": [
    {
      "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"
    }
  ],
  "has_more": true
}

GET

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
});

// Automatically fetches more pages as needed.
for await (const coupon of client.beta.subscriptions.coupons.list()) {
  console.log(coupon.id);
}

{
  "data": [
    {
      "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"
    }
  ],
  "has_more": true
}

Authorizations

Authorization

string

header

required

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

Query Parameters

limit

integer

default:100

Maximum number of coupons to return (1-100)

Required range: 1 <= x <= 100

starting_after

string

Cursor for forward pagination

ending_before

string

Cursor for backward pagination

active

boolean

Filter by active status

Response

200 - application/json

A paginated list of coupon objects

Paginated list of coupons

data

object[]

required

Array of coupon objects

Show child attributes

data.id

string

required

Unique identifier for the entitlement

data.created

string<date-time>

required

Timestamp when the coupon was created

data.code

string

required

The promo code customers enter to apply the discount

data.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

data.times_redeemed

integer

required

Number of times this coupon has been successfully redeemed

Required range: -9007199254740991 <= x <= 9007199254740991

data.active

boolean

required

Whether the coupon is currently active and can be redeemed

data.name

string | null

Display name for the coupon (shown to customers)

data.percent_off

number | null

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

data.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

data.currency

string | null

Three-letter ISO currency code for amount_off discounts

data.duration_in_months

integer | null

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

Required range: -9007199254740991 <= x <= 9007199254740991

data.max_redemptions

integer | null

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

Required range: -9007199254740991 <= x <= 9007199254740991

data.redeem_by

string<date-time> | null

Expiration date after which the coupon can no longer be redeemed

has_more

boolean

required

Whether there are more coupons available after this page

Check Entitlement Create Coupon

⌘I

Subscriptions

Coupons

Customers

Entitlements

Plans

Plan Entitlements

List Coupons

Authorizations

Query Parameters

Response