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.
- product.
namestringRequired The product’s name, meant to be displayable to the customer.
- product.
activeboolean Whether the product is currently available for purchase. Defaults to
true
. - product.
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
. - product.
statement_ descriptorstring An arbitrary string to be displayed on your customer’s credit card or bank statement. While most banks display this information consistently, some may display it incorrectly or not at all.
This may be up to 22 characters. The statement description may not include
<
,>
,\
,"
,'
characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. - product.
tax_ codestringRecommended if calculating taxes A tax code ID.
- product.
unit_ labelstring A label that represents units of this product. When set, this will be included in customers’ receipts, invoices, Checkout, and the customer portal.
- 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
- amount_
decimalstring Same as
amount
, but accepts a decimal value with at most 12 decimal places. Only one ofamount
andamount_
can be set.decimal - billing_
schemeenum Describes how to compute the price per period. Either
per_
orunit tiered
.per_
indicates that the fixed amount (specified inunit amount
) will be charged per unit inquantity
(for plans withusage_
), or per unit of total usage (for plans withtype=licensed usage_
).type=metered tiered
indicates that the unit pricing will be computed using a tiering strategy as defined using thetiers
andtiers_
attributes.mode Possible enum valuesper_
unit tiered
- idstring
An identifier randomly generated by Stripe. Used to identify this plan when subscribing a customer. You can optionally override this ID, but the ID must be unique across all plans in your Stripe account. You can, however, use the same plan ID in both live and test modes.
- interval_
countinteger The number of intervals between subscription billings. For example,
interval=month
andinterval_
bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks).count=3 - meterstring
The meter tracking the usage of a metered price
- tiersarray of objectsRequired if billing_scheme=tiered
Each element represents a pricing tier. This parameter requires
billing_
to be set toscheme tiered
. See also the documentation forbilling_
.scheme - tiers.
up_ tostring | integerRequired Specifies the upper bound of this tier. The lower bound of a tier is the upper bound of the previous tier adding one. Use
inf
to define a fallback tier. - tiers.
flat_ amountinteger The flat billing amount for an entire tier, regardless of the number of units in the tier.
- tiers.
flat_ amount_ decimalstring Same as
flat_
, but accepts a decimal value representing an integer in the minor units of the currency. Only one ofamount flat_
andamount flat_
can be set.amount_ decimal - tiers.
unit_ amountinteger The per unit billing amount for each individual unit for which this tier applies.
- tiers.
unit_ amount_ decimalstring Same as
unit_
, but accepts a decimal value in cents with at most 12 decimal places. Only one ofamount unit_
andamount unit_
can be set.amount_ decimal
- tiers_
modeenumRequired if billing_scheme=tiered Defines if the tiering price should be
graduated
orvolume
based. Involume
-based tiering, the maximum quantity within a period determines the per unit price, ingraduated
tiering pricing can successively change as the quantity grows. - transform_
usageobject Apply a transformation to the reported usage or set quantity before computing the billed price. Cannot be combined with
tiers
.- transform_usage.
divide_ byintegerRequired Divide usage by this number.
- transform_usage.
roundenumRequired After division, either round the result
up
ordown
.
- trial_
period_ daysinteger Default number of trial days when subscribing a customer to this plan using
trial_
.from_ plan=true - usage_
typeenum Configures how the quantity per period should be determined. Can be either
metered
orlicensed
.licensed
automatically bills thequantity
set when adding it to a subscription.metered
aggregates the total usage based on usage records. Defaults tolicensed
.Possible enum valueslicensed
metered
Returns
Returns 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"}