Stripe Subscription API
Subscriptions allow you to charge a customer on a recurring basis.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Subscription API
description: Needs description.
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/subscription_items:
get:
description: >-
<p>Returns a list of your subscription items for a given
subscription.</p>
operationId: GetSubscriptionItems
parameters:
- 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:
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: >-
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:
type: string
style: form
- description: The ID of the subscription whose items will be retrieved.
in: query
name: subscription
required: true
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetSubscriptionItemsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/SubscriptionsItemsSubscriptionItemList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Items
post:
description: >-
<p>Adds a new item to an existing subscription. No existing items will
be changed or replaced.</p>
operationId: PostSubscriptionItems
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
billing_thresholds:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
price_data:
explode: true
style: deepObject
tax_rates:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostSubscriptionItemsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription_item'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Items
/v1/subscription_items/{item}:
delete:
description: >-
<p>Deletes an item from the subscription. Removing a subscription item
from a subscription will not cancel the subscription.</p>
operationId: DeleteSubscriptionItemsItem
parameters:
- in: path
name: item
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/DeleteSubscriptionItemsItemRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/deleted_subscription_item'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Items
get:
description: <p>Retrieves the subscription item with the given ID.</p>
operationId: GetSubscriptionItemsItem
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: item
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetSubscriptionItemsItemRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription_item'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Items
post:
description: >-
<p>Updates the plan or quantity of an item on a current
subscription.</p>
operationId: PostSubscriptionItemsItem
parameters:
- in: path
name: item
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
billing_thresholds:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
price_data:
explode: true
style: deepObject
tax_rates:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostSubscriptionItemsItemRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription_item'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Items
/v1/subscription_items/{subscription_item}/usage_record_summaries:
get:
description: >-
<p>For the specified subscription item, returns a list of summary
objects. Each object in the list provides usage information that’s been
summarized from multiple usage records and over a subscription billing
period (e.g., 15 usage records in the month of September).</p>
<p>The list is sorted in reverse-chronological order (newest first). The
first list item represents the most current usage period that hasn’t
ended yet. Since new usage records can still be added, the returned
summary information for the subscription item’s ID should be seen as
unstable until the subscription billing period ends.</p>
operationId: GetSubscriptionItemsSubscriptionItemUsageRecordSummaries
parameters:
- 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: >-
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
- in: path
name: subscription_item
required: true
schema:
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: >-
#/components/schemas/GetSubscriptionItemsSubscriptionItemUsageRecordSummariesRequest
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/UsageEventsResourceUsageRecordSummaryList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Items
/v1/subscription_items/{subscription_item}/usage_records:
post:
description: >-
<p>Creates a usage record for a specified subscription item and date,
and fills it with a quantity.</p>
<p>Usage records provide <code>quantity</code> information that Stripe
uses to track how much a customer is using your service. With usage
information and the pricing model set up by the <a
href="https://stripe.com/docs/billing/subscriptions/metered-billing">metered
billing</a> plan, Stripe helps you send accurate invoices to your
customers.</p>
<p>The default calculation for usage is to add up all the
<code>quantity</code> values of the usage records within a billing
period. You can change this default behavior with the billing plan’s
<code>aggregate_usage</code> <a
href="/docs/api/plans/create#create_plan-aggregate_usage">parameter</a>.
When there is more than one usage record with the same timestamp, Stripe
adds the <code>quantity</code> values together. In most cases, this is
the desired resolution, however, you can change this behavior with the
<code>action</code> parameter.</p>
<p>The default pricing model for metered billing is <a
href="/docs/api/plans/object#plan_object-billing_scheme">per-unit
pricing</a>. For finer granularity, you can configure metered billing to
have a <a
href="https://stripe.com/docs/billing/subscriptions/tiers">tiered
pricing</a> model.</p>
operationId: PostSubscriptionItemsSubscriptionItemUsageRecords
parameters:
- in: path
name: subscription_item
required: true
schema:
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
timestamp:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/PostSubscriptionItemsSubscriptionItemUsageRecordsRequest
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/usage_record'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Items
/v1/subscription_schedules:
get:
description: <p>Retrieves the list of your subscription schedules.</p>
operationId: GetSubscriptionSchedules
parameters:
- description: >-
Only return subscription schedules that were created canceled the
given date interval.
explode: true
in: query
name: canceled_at
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: >-
Only return subscription schedules that completed during the given
date interval.
explode: true
in: query
name: completed_at
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: >-
Only return subscription schedules that were created during the
given date interval.
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: Only return subscription schedules for the given customer.
in: query
name: customer
required: false
schema:
maxLength: 5000
type: string
style: form
- 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 subscription schedules that were released during the
given date interval.
explode: true
in: query
name: released_at
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: Only return subscription schedules that have not started yet.
in: query
name: scheduled
required: false
schema:
type: boolean
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/GetSubscriptionSchedulesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/SubscriptionSchedulesResourceScheduleList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Schedules
post:
description: >-
<p>Creates a new subscription schedule object. Each customer can have up
to 500 active or scheduled subscriptions.</p>
operationId: PostSubscriptionSchedules
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
default_settings:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
phases:
explode: true
style: deepObject
start_date:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostSubscriptionSchedulesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription_schedule'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Schedules
/v1/subscription_schedules/{schedule}:
get:
description: >-
<p>Retrieves the details of an existing subscription schedule. You only
need to supply the unique subscription schedule identifier that was
returned upon subscription schedule creation.</p>
operationId: GetSubscriptionSchedulesSchedule
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: schedule
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetSubscriptionSchedulesScheduleRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription_schedule'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Schedules
post:
description: <p>Updates an existing subscription schedule.</p>
operationId: PostSubscriptionSchedulesSchedule
parameters:
- in: path
name: schedule
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
default_settings:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
phases:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostSubscriptionSchedulesScheduleRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription_schedule'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Schedules
/v1/subscription_schedules/{schedule}/cancel:
post:
description: >-
<p>Cancels a subscription schedule and its associated subscription
immediately (if the subscription schedule has an active subscription). A
subscription schedule can only be canceled if its status is
<code>not_started</code> or <code>active</code>.</p>
operationId: PostSubscriptionSchedulesScheduleCancel
parameters:
- in: path
name: schedule
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/PostSubscriptionSchedulesScheduleCancelRequest
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription_schedule'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Schedules
/v1/subscription_schedules/{schedule}/release:
post:
description: >-
<p>Releases the subscription schedule immediately, which will stop
scheduling of its phases, but leave any existing subscription in place.
A schedule can only be released if its status is
<code>not_started</code> or <code>active</code>. If the subscription
schedule is currently associated with a subscription, releasing it will
remove its <code>subscription</code> property and set the subscription’s
ID to the <code>released_subscription</code> property.</p>
operationId: PostSubscriptionSchedulesScheduleRelease
parameters:
- in: path
name: schedule
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/PostSubscriptionSchedulesScheduleReleaseRequest
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription_schedule'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscription Schedules
/v1/subscriptions:
get:
description: >-
<p>By default, returns a list of subscriptions that have not been
canceled. In order to list canceled subscriptions, specify
<code>status=canceled</code>.</p>
operationId: GetSubscriptions
parameters:
- description: Filter subscriptions by their automatic tax settings.
explode: true
in: query
name: automatic_tax
required: false
schema:
properties:
enabled:
type: boolean
required:
- enabled
title: automatic_tax_filter_params
type: object
style: deepObject
- description: >-
The collection method of the subscriptions to retrieve. Either
`charge_automatically` or `send_invoice`.
in: query
name: collection_method
required: false
schema:
enum:
- charge_automatically
- send_invoice
type: string
style: form
- 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
- explode: true
in: query
name: current_period_end
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
- explode: true
in: query
name: current_period_start
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: The ID of the customer whose subscriptions will be retrieved.
in: query
name: customer
required: false
schema:
maxLength: 5000
type: string
style: form
- 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: Filter for subscriptions that contain this recurring price ID.
in: query
name: price
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 t
# --- truncated at 32 KB (189 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-subscription-api-openapi.yml