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,monthoryear. - 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,monthoryear. Possible enum valuesdaymonthweekyear - 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"}
Update a plan
POST / v1 / plans /:id
Updates the specified plan by setting the values of the parameters passed. Any parameters not provided are left unchanged. By design, you cannot change a plan’s ID, amount, currency, or billing cycle.
Parameters
- active boolean Whether the plan is currently available for new subscriptions.
- 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
- product string
- trial _ period _ days integer
Returns
The updated plan object is returned upon success. Otherwise, this call raises an error.
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": { "order_id": "6735" }, "nickname": null, "product": "prod_NjpI7DbZx6AlWQ", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed"}