Skip to main content
POST
/
v1
/
subscriptions
/
plans
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 plan = await client.beta.subscriptions.plans.create({ name: 'name', unit_amount: -9007199254740991 });

console.log(plan.id);
{
  "id": "<string>",
  "created": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "active": true,
  "stripe_product_id": "<string>",
  "description": "<string>",
  "default_price": {
    "id": "<string>",
    "currency": "<string>",
    "unit_amount": 0,
    "interval": "day",
    "interval_count": 0
  },
  "default_proration_behavior": "create_prorations",
  "upgrade_timing": "immediate",
  "downgrade_timing": "immediate",
  "billing_cycle_anchor": "now"
}

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 new subscription plan. After creating a plan, attach entitlements to define which features customers on this plan can access.

​
name
string
required

Display name for the plan (e.g., Pro, Business, Teams)

​
unit_amount
integer
required

Price amount in the smallest currency unit (e.g., cents). Use 0 for free plans.

Required range: -9007199254740991 <= x <= 9007199254740991
​
description
string

Detailed description of what the plan includes

​
currency
string
default:usd

Three-letter ISO currency code

​
interval
enum<string>
default:month

Billing frequency: day, week, month, or year

Available options:
day,
week,
month,
year
​
interval_count
integer
default:1

Number of intervals between billings

Required range: -9007199254740991 <= x <= 9007199254740991
​
default_proration_behavior
enum<string>

Default proration behavior when customers switch to this plan. Defaults to 'create_prorations'.

Available options:
create_prorations,
none,
always_invoice
​
upgrade_timing
enum<string>

When upgrades to this plan take effect. Defaults to 'immediate'.

Available options:
immediate,
at_billing_period_end
​
downgrade_timing
enum<string>

When downgrades to this plan take effect. Defaults to 'at_billing_period_end'.

Available options:
immediate,
at_billing_period_end
​
billing_cycle_anchor
enum<string>

How billing cycle is handled when switching to this plan. Defaults to 'now' for upgrades.

Available options:
now,
unchanged

Response

201 - application/json

The created plan object

A subscription plan that customers can subscribe to. Plans define pricing and billing intervals. Attach entitlements to a plan to grant features to all subscribed customers.

​
id
string
required

Unique identifier for the entitlement

​
created
string<date-time>
required

Timestamp when the plan was created

​
name
string
required

Display name for the plan (e.g., Pro, Business, Teams)

​
active
boolean
required

Whether the plan is available for new subscriptions

​
stripe_product_id
string
required

Internal payment provider reference

​
description
string | null

Detailed description of what the plan includes

​
default_price
object

The default recurring price for this plan

​
default_proration_behavior
enum<string> | null

Default proration behavior when customers switch to this plan

Available options:
create_prorations,
none,
always_invoice
​
upgrade_timing
enum<string> | null

When upgrades to this plan take effect. Defaults to 'immediate'.

Available options:
immediate,
at_billing_period_end
​
downgrade_timing
enum<string> | null

When downgrades to this plan take effect. Defaults to 'at_billing_period_end'.

Available options:
immediate,
at_billing_period_end
​
billing_cycle_anchor
enum<string> | null

How billing cycle is handled when switching to this plan

Available options:
now,
unchanged