Stripe Plans API
You can now model subscriptions more flexibly using the Prices API. It replaces the Plans API and is backwards compatible to simplify your migration.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Plans API
description: >-
You can now model subscriptions more flexibly using the Prices API. It
replaces the Plans API and is backwards compatible to simplify your
migration.
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/plans:
get:
description: <p>Returns a list of your plans.</p>
operationId: getPlans
parameters:
- description: >-
Only return plans that are active or inactive (e.g., pass `false` to
list all inactive plans).
in: query
name: active
required: false
schema:
type: boolean
style: form
- description: >-
A filter on the list, based on the object `created` field. The value
can be a string with an integer Unix timestamp, or it can be a
dictionary with a number of different query options.
explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: Only return plans for the given product.
in: query
name: product
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetPlansRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/PlanList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Plans
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Plans
post:
description: >-
<p>You can now model subscriptions more flexibly using the <a
href="#prices">Prices API</a>. It replaces the Plans API and is
backwards compatible to simplify your migration.</p>
operationId: postPlans
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
product:
explode: true
style: deepObject
tiers:
explode: true
style: deepObject
transform_usage:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostPlansRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/plan'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Plans
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Plans
- Post
/v1/plans/{plan}:
delete:
description: >-
<p>Deleting plans means new subscribers can’t be added. Existing
subscribers aren’t affected.</p>
operationId: deletePlansPlan
parameters:
- in: path
name: plan
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/DeletePlansPlanRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/deleted_plan'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Delete Plans
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Delete
- Plans
get:
description: <p>Retrieves the plan with the given ID.</p>
operationId: getPlansPlan
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: plan
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetPlansPlanRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/plan'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Plans
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Plans
post:
description: >-
<p>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.</p>
operationId: postPlansPlan
parameters:
- in: path
name: plan
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostPlansPlanRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/plan'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Plans
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Plans
- Post
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
plan:
description: >-
You can now model subscriptions more flexibly using the [Prices
API](https://stripe.com/docs/api#prices). 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](https://stripe.com/docs/api#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](https://stripe.com/docs/billing/subscriptions/set-up-subscription)
and more about [products and
prices](https://stripe.com/docs/products-prices/overview).
properties:
active:
description: Whether the plan can be used for new purchases.
type: boolean
aggregate_usage:
description: >-
Specifies a usage aggregation strategy for plans of
`usage_type=metered`. Allowed values are `sum` for summing up all
usage during a period, `last_during_period` for using the last usage
record reported within a period, `last_ever` for using the last
usage record ever (across period bounds) or `max` which uses the
usage record with the maximum reported usage during a period.
Defaults to `sum`.
enum:
- last_during_period
- last_ever
- max
- sum
nullable: true
type: string
amount:
description: >-
The unit amount in cents (or local equivalent) to be charged,
represented as a whole integer if possible. Only set if
`billing_scheme=per_unit`.
nullable: true
type: integer
amount_decimal:
description: >-
The unit amount in cents (or local equivalent) to be charged,
represented as a decimal string with at most 12 decimal places. Only
set if `billing_scheme=per_unit`.
format: decimal
nullable: true
type: string
billing_scheme:
description: >-
Describes how to compute the price per period. Either `per_unit` or
`tiered`. `per_unit` indicates that the fixed amount (specified in
`amount`) will be charged per unit in `quantity` (for plans with
`usage_type=licensed`), or per unit of total usage (for plans with
`usage_type=metered`). `tiered` indicates that the unit pricing will
be computed using a tiering strategy as defined using the `tiers`
and `tiers_mode` attributes.
enum:
- per_unit
- tiered
type: string
created:
description: >-
Time at which the object was created. Measured in seconds since the
Unix epoch.
format: unix-time
type: integer
currency:
description: >-
Three-letter [ISO currency
code](https://www.iso.org/iso-4217-currency-codes.html), in
lowercase. Must be a [supported
currency](https://stripe.com/docs/currencies).
type: string
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
interval:
description: >-
The frequency at which a subscription is billed. One of `day`,
`week`, `month` or `year`.
enum:
- day
- month
- week
- year
type: string
interval_count:
description: >-
The number of intervals (specified in the `interval` attribute)
between subscription billings. For example, `interval=month` and
`interval_count=3` bills every 3 months.
type: integer
livemode:
description: >-
Has the value `true` if the object exists in live mode or the value
`false` if the object exists in test mode.
type: boolean
metadata:
additionalProperties:
maxLength: 500
type: string
description: >-
Set of [key-value pairs](https://stripe.com/docs/api/metadata) that
you can attach to an object. This can be useful for storing
additional information about the object in a structured format.
nullable: true
type: object
nickname:
description: A brief description of the plan, hidden from customers.
maxLength: 5000
nullable: true
type: string
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- plan
type: string
product:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/product'
- $ref: '#/components/schemas/deleted_product'
description: The product whose pricing this plan determines.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/product'
- $ref: '#/components/schemas/deleted_product'
tiers:
description: >-
Each element represents a pricing tier. This parameter requires
`billing_scheme` to be set to `tiered`. See also the documentation
for `billing_scheme`.
items:
$ref: '#/components/schemas/plan_tier'
type: array
tiers_mode:
description: >-
Defines if the tiering price should be `graduated` or `volume`
based. In `volume`-based tiering, the maximum quantity within a
period determines the per unit price. In `graduated` tiering,
pricing can change as the quantity grows.
enum:
- graduated
- volume
nullable: true
type: string
transform_usage:
anyOf:
- $ref: '#/components/schemas/transform_usage'
description: >-
Apply a transformation to the reported usage or set quantity before
computing the amount billed. Cannot be combined with `tiers`.
nullable: true
trial_period_days:
description: >-
Default number of trial days when subscribing a customer to this
plan using
[`trial_from_plan=true`](https://stripe.com/docs/api#create_subscription-trial_from_plan).
nullable: true
type: integer
usage_type:
description: >-
Configures how the quantity per period should be determined. Can be
either `metered` or `licensed`. `licensed` automatically bills the
`quantity` set when adding it to a subscription. `metered`
aggregates the total usage based on usage records. Defaults to
`licensed`.
enum:
- licensed
- metered
type: string
required:
- active
- billing_scheme
- created
- currency
- id
- interval
- interval_count
- livemode
- object
- usage_type
title: Plan
type: object
x-expandableFields:
- product
- tiers
- transform_usage
x-resourceId: plan
deleted_plan:
description: ''
properties:
deleted:
description: Always true for a deleted object
enum:
- true
type: boolean
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- plan
type: string
required:
- deleted
- id
- object
title: DeletedPlan
type: object
x-expandableFields: []
x-resourceId: deleted_plan
GetPlansRequest:
type: object
properties: {}
PlanList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/plan'
type: array
has_more:
description: >-
True if this list has another page of items after this one that can
be fetched.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same type
share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/plans
type: string
PostPlansRequest:
type: object
required:
- currency
- interval
properties:
active:
description: >-
Whether the plan is currently available for new subscriptions.
Defaults to `true`.
type: boolean
aggregate_usage:
description: >-
Specifies a usage aggregation strategy for plans of
`usage_type=metered`. Allowed values are `sum` for summing up all
usage during a period, `last_during_period` for using the last usage
record reported within a period, `last_ever` for using the last
usage record ever (across period bounds) or `max` which uses the
usage record with the maximum reported usage during a period.
Defaults to `sum`.
enum:
- last_during_period
- last_ever
- max
- sum
type: string
amount:
description: >-
A positive integer in cents (or local equivalent) (or 0 for a free
plan) representing how much to charge on a recurring basis.
type: integer
amount_decimal:
description: >-
Same as `amount`, but accepts a decimal value with at most 12
decimal places. Only one of `amount` and `amount_decimal` can be
set.
format: decimal
type: string
billing_scheme:
description: >-
Describes how to compute the price per period. Either `per_unit` or
`tiered`. `per_unit` indicates that the fixed amount (specified in
`amount`) will be charged per unit in `quantity` (for plans with
`usage_type=licensed`), or per unit of total usage (for plans with
`usage_type=metered`). `tiered` indicates that the unit pricing will
be computed using a tiering strategy as defined using the `tiers`
and `tiers_mode` attributes.
enum:
- per_unit
- tiered
type: string
currency:
description: >-
Three-letter [ISO currency
code](https://www.iso.org/iso-4217-currency-codes.html), in
lowercase. Must be a [supported
currency](https://stripe.com/docs/currencies).
type: string
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
id:
description: >-
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.
maxLength: 5000
type: string
interval:
description: >-
Specifies billing frequency. Either `day`, `week`, `month` or
`year`.
enum:
- day
- month
- week
- year
type: string
interval_count:
description: >-
The number of intervals between subscription billings. For example,
`interval=month` and `interval_count=3` bills every 3 months.
Maximum of one year interval allowed (1 year, 12 months, or 52
weeks).
type: integer
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- enum:
- ''
type: string
description: >-
Set of [key-value pairs](https://stripe.com/docs/api/metadata) 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:
description: A brief description of the plan, hidden from customers.
maxLength: 5000
type: string
product:
anyOf:
- description: >-
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](https://stripe.com/docs/api#product_object-type).
properties:
active:
type: boolean
id:
maxLength: 5000
type: string
metadata:
additionalProperties:
type: string
type: object
name:
maxLength: 5000
type: string
statement_descriptor:
maxLength: 22
type: string
tax_code:
maxLength: 5000
type: string
unit_label:
maxLength: 12
type: string
required:
- name
title: inline_product_params
type: object
- description: >-
The ID of the product whose pricing the created plan will
represent.
maxLength: 5000
type: string
tiers:
description: >-
Each element represents a pricing tier. This parameter requires
`billing_scheme` to be set to `tiered`. See also the documentation
for `billing_scheme`.
items:
properties:
flat_amount:
type: integer
flat_amount_decimal:
format: decimal
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
up_to:
anyOf:
- enum:
- inf
maxLength: 5000
type: string
- type: integer
required:
- up_to
title: tier
type: object
type: array
tiers_mode:
description: >-
Defines if the tiering price should be `graduated` or `volume`
based. In `volume`-based tiering, the maximum quantity within a
period determines the per unit price, in `graduated` tiering pricing
can successively change as the quantity grows.
enum:
- graduated
- volume
type: string
transform_usage:
description: >-
Apply a transformation to the reported usage or set quantity before
computing the billed price. Cannot be combined with `tiers`.
properties:
divide_by:
type: integer
round:
enum:
- down
- up
type: string
required:
- divide_by
- round
title: transform_usage_param
type: object
trial_period_days:
description: >-
Default number of trial days when subscribing a customer to this
plan using
[`trial_from_plan=true`](https://stripe.com/docs/api#create_subscription-trial_from_plan).
type: integer
usage_type:
description: >-
Configures how the quantity per period should be determined. Can be
either `metered` or `licensed`. `licensed` automatically bills the
`quantity` set when adding it to a subscription. `metered`
aggregates the total usage based on usage records. Defaults to
`licensed`.
enum:
- licensed
- metered
type: string
DeletePlansPlanRequest:
type: object
properties: {}
GetPlansPlanRequest:
type: object
properties: {}
PostPlansPlanRequest:
type: object
properties:
active:
description: Whether the plan is currently available for new subscriptions.
type: boolean
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- enum:
- ''
type: string
description: >-
Set of [key-value pairs](https://stripe.com/docs/api/metadata) 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:
description: A brief description of the plan, hidden from customers.
maxLength: 5000
type: string
product:
description: >-
The product the plan belongs to. This cannot be changed once it has
been used in a subscription or subscription schedule.
maxLength: 5000
type: string
trial_period_days:
description: >-
Default number of trial days when subscribing a customer to this
plan using
[`trial_from_plan=true`](https://stripe.com/docs/api#create_subscription-trial_from_plan).
type: integer
securitySchemes:
basicAuth:
description: >-
Basic HTTP authentication. Allowed headers-- Authorization: Basic
<api_key> | Authorization: Basic <base64 hash of `api_key:`>
scheme: basic
type: http
bearerAuth:
bearerFormat: auth-scheme
description: >-
Bearer HTTP authentication. Allowed headers-- Authorization: Bearer
<api_key>
scheme: bearer
type: http
tags:
- name: Delete
- name: Get
- name: Plans
- name: Post