Create a plan
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
- currencyenumRequired
Three-letter ISO currency code, in lowercase. Must be a supported currency.
- intervalenumRequired
Specifies billing frequency. Either
day,week,monthoryear.Possible enum valuesdaymonthweekyear - producthashRequired
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.
- activeboolean
Whether the plan is currently available for new subscriptions. Defaults to
true. - amountintegerRequired unless billing_scheme=tiered
A positive integer in cents (or 0 for a free plan) representing how much to charge on a recurring basis.
- metadatahash
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. - nicknamestring
A brief description of the plan, hidden from customers.
More parameters
- aggregate_
usageenum - amount_
decimalstring - billing_
schemeenum - idstring
- interval_
countinteger - meterstringPreview feature
- tiersarray of hashesRequired if billing_scheme=tiered
- tiers_
modeenumRequired if billing_scheme=tiered - transform_
usagehash - trial_
period_ daysinteger - usage_
typeenum
Returns
Returns the plan object.
{ "id": "plan_NjpIbv3g3ZibnD", "object": "plan", "active": true, "aggregate_usage": null, "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
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
- activeboolean
Whether the plan is currently available for new subscriptions.
- metadatahash
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. - nicknamestring
A brief description of the plan, hidden from customers.
More parameters
- productstring
- trial_
period_ daysinteger
Returns
The updated plan object is returned upon success. Otherwise, this call raises an error.
{ "id": "plan_NjpIbv3g3ZibnD", "object": "plan", "active": true, "aggregate_usage": null, "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"}Retrieve a plan
Retrieves the plan with the given ID.
Parameters
No parameters.
Returns
Returns a plan if a valid plan ID was provided. Raises an error otherwise.
{ "id": "plan_NjpIbv3g3ZibnD", "object": "plan", "active": true, "aggregate_usage": null, "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"}List all plans
Returns a list of your plans.
Parameters
- activeboolean
Only return plans that are active or inactive (e.g., pass
falseto list all inactive plans). - productstring
Only return plans for the given product.
More parameters
- createdhash
- ending_
beforestring - limitinteger
- starting_
afterstring
Returns
A hash with a data property that contains an array of up to limit plans, starting after plan starting_after. Each entry in the array is a separate plan object. If no more plans are available, the resulting array will be empty.
{ "object": "list", "url": "/v1/plans", "has_more": false, "data": [ { "id": "plan_NjpIbv3g3ZibnD", "object": "plan", "active": true, "aggregate_usage": null, "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" } {...} {...} ],}Delete a plan
Deleting plans means new subscribers can’t be added. Existing subscribers aren’t affected.
Parameters
No parameters.
Returns
An object with the deleted plan’s ID and a deleted flag upon success. Otherwise, this call raises an error, such as if the plan has already been deleted.
{ "id": "plan_NjpIbv3g3ZibnD", "object": "plan", "deleted": true}