The Plan object
Attributes
- idstring
Unique identifier for the object.
- activeboolean
Whether the plan can be used for new purchases.
- amountnullable integer
The unit amount in cents to be charged, represented as a whole integer if possible. Only set if
billing_
.scheme=per_ unit - currencyenum
Three-letter ISO currency code, in lowercase. Must be a supported currency.
- intervalenum
The frequency at which a subscription is billed. One of
day
,week
,month
oryear
. - metadatanullable object
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.
- nicknamenullable string
A brief description of the plan, hidden from customers.
- productnullable stringExpandable
The product whose pricing this plan determines.
More attributes
- objectstring
- aggregate_
usagenullable enum - amount_
decimalnullable decimal string - billing_
schemeenum - createdtimestamp
- interval_
countinteger - livemodeboolean
- meternullable string
- tiersnullable array of objectsExpandable
- tiers_
modenullable enum - transform_
usagenullable object - trial_
period_ daysnullable integer - usage_
typeenum
{
"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"
}
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
,month
oryear
.Possible enum valuesday
month
week
year
- productobjectRequired
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.
- metadataobject
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 - meterstring
- tiersarray of objectsRequired if billing_scheme=tiered
- tiers_
modeenumRequired if billing_scheme=tiered - transform_
usageobject - 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.
- metadataobject
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
false
to list all inactive plans). - productstring
Only return plans for the given product.
More parameters
- createdobject
- ending_
beforestring - limitinteger
- starting_
afterstring
Returns
A dictionary with a data
property that contains an array of up to limit
plans, starting after plan starting_
. 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"
}
{...}
{...}
],
}