Skip to main content
PATCH
/
v1
/
subscriptions
/
plans
/
{plan_id}
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.update('plan_id');

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

Path Parameters

​
plan_id
string
required

The unique identifier of the plan

Body

application/json

Request to update a plan. Pricing cannot be changed after creation—create a new plan instead.

​
name
string

Display name for the plan

​
description
string

Detailed description of what the plan includes

​
active
boolean

Whether the plan is available for new subscriptions

​
default_proration_behavior
enum<string>

Default proration behavior when customers switch to this plan

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

When upgrades to this plan take effect

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

When downgrades to this plan take effect

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

How billing cycle is handled when switching to this plan

Available options:
now,
unchanged

Response

200 - application/json

The updated 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