Plans

You can now model subscriptions more flexibly using the Prices API. It replaces the Plans API and is backwards compatible to simplify your migration.

Plans define the base price, currency, and billing cycle for recurring purchases of products. Products help you track inventory or provisioning, and plans help you track pricing. Different physical goods or levels of service should be represented by products, and pricing options should be represented by plans. This approach lets you change prices without having to change your provisioning scheme.

For example, you might have a single “gold” product that has plans for $10/month, $100/year, €9/month, and €90/year.

Related guides: Set up a subscription and more about products and prices.

Was this section helpful? Yes No

Create a plan

POST / v1 / plans

Update a plan

POST / v1 / plans /:id

Retrieve a plan

GET / v1 / plans /:id

List all plans

GET / v1 / plans

Delete a plan

DELETE / v1 / plans /:id

The Plan object

Attributes

id string Unique identifier for the object.
active boolean Whether the plan can be used for new purchases.
amount nullable integer The unit amount in the smallest currency unit to be charged, represented as a whole integer if possible. Only set if billing_scheme=per_unit.
currency enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
interval enum The frequency at which a subscription is billed. One of day, week, month or year.
metadata nullable map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
nickname nullable string A brief description of the plan, hidden from customers.
product nullable string Expandable The product whose pricing this plan determines.

More attributes

object string, value is "plan"
amount _ decimal nullable decimal string
billing _ scheme enum
created timestamp
interval _ count integer
livemode boolean
meter nullable string
tiers nullable array of objects Includable
tiers _ mode nullable enum
transform _ usage nullable object
trial _ period _ days nullable integer
usage _ type enum

The Plan object

{ "id": "plan_NjpIbv3g3ZibnD", "object": "plan", "active": true, "amount": 1200, "amount_decimal": "1200", "billing_scheme": "per_unit", "created": 1681851647, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": {}, "nickname": null, "product": "prod_NjpI7DbZx6AlWQ", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed"}

Create a plan

POST / v1 / plans

You can now model subscriptions more flexibly using the Prices API. It replaces the Plans API and is backwards compatible to simplify your migration.

Parameters

currency enum Required Three-letter ISO currency code, in lowercase. Must be a supported currency.
interval enum Required Specifies billing frequency. Either day, week, month or year. Possible enum values day month week year
product object Required The product whose pricing the created plan will represent. This can either be the ID of an existing product, or a dictionary containing fields used to create a service product.
active boolean Whether the plan is currently available for new subscriptions. Defaults to true.
amount integer Required unless billing_scheme=tiered A positive integer in the smallest currency unit (or 0 for a free plan) representing how much to charge on a recurring basis.
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
nickname string A brief description of the plan, hidden from customers.

More parameters

amount _ decimal string
billing _ scheme enum
id string
interval _ count integer
meter string
tiers array of objects Required if billing_scheme=tiered
tiers _ mode enum Required if billing_scheme=tiered
transform _ usage object
trial _ period _ days integer
usage _ type enum

Returns

Returns the plan object.

Response

{ "id": "plan_NjpIbv3g3ZibnD", "object": "plan", "active": true, "amount": 1200, "amount_decimal": "1200", "billing_scheme": "per_unit", "created": 1681851647, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": {}, "nickname": null, "product": "prod_NjpI7DbZx6AlWQ", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed"}