openapi: 3.0.0
info:
title: Stripe Accounts Account Subscriptions API
description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
contact:
email: dev-platform@stripe.com
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Subscriptions
paths:
/v1/customers/{customer}/subscriptions:
get:
description: <p>You can see a list of the customer’s active subscriptions. Note that the 10 most recent active subscriptions are always available by default on the customer object. If you need more than those 10, you can use the limit and starting_after parameters to page through additional subscriptions.</p>
operationId: getCustomersCustomerSubscriptions
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- 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
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersCustomerSubscriptionsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/SubscriptionList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer Subscriptions
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Subscriptions
post:
description: <p>Creates a new subscription on an existing customer.</p>
operationId: postCustomersCustomerSubscriptions
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
add_invoice_items:
explode: true
style: deepObject
automatic_tax:
explode: true
style: deepObject
billing_thresholds:
explode: true
style: deepObject
default_tax_rates:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
items:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
payment_settings:
explode: true
style: deepObject
pending_invoice_item_interval:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
trial_end:
explode: true
style: deepObject
trial_settings:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCustomersCustomerSubscriptionsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Customers Customer Subscriptions
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Subscriptions
/v1/customers/{customer}/subscriptions/{subscription_exposed_id}:
delete:
description: '<p>Cancels a customer’s subscription. If you set the <code>at_period_end</code> parameter to <code>true</code>, the subscription will remain active until the end of the period, at which point it will be canceled and not renewed. Otherwise, with the default <code>false</code> value, the subscription is terminated immediately. In either case, the customer will not be charged again for the subscription.</p>
<p>Note, however, that any pending invoice items that you’ve created will still be charged for at the end of the period, unless manually <a href="#delete_invoiceitem">deleted</a>. If you’ve set the subscription to cancel at the end of the period, any pending prorations will also be left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations will be removed.</p>
<p>By default, upon subscription cancellation, Stripe will stop automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.</p>'
operationId: deleteCustomersCustomerSubscriptionsSubscriptionExposedId
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- in: path
name: subscription_exposed_id
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/DeleteCustomersCustomerSubscriptionsSubscriptionExposedIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Delete Customers Customer Subscriptions Subscription Exposed Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Subscriptions
get:
description: <p>Retrieves the subscription with the given ID.</p>
operationId: getCustomersCustomerSubscriptionsSubscriptionExposedId
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- 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: subscription_exposed_id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersCustomerSubscriptionsSubscriptionExposedIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer Subscriptions Subscription Exposed Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Subscriptions
post:
description: <p>Updates an existing subscription on a customer to match the specified parameters. When changing plans or quantities, we will optionally prorate the price we charge next month to make up for any price changes. To preview how the proration will be calculated, use the <a href="#upcoming_invoice">upcoming invoice</a> endpoint.</p>
operationId: postCustomersCustomerSubscriptionsSubscriptionExposedId
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- in: path
name: subscription_exposed_id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
add_invoice_items:
explode: true
style: deepObject
automatic_tax:
explode: true
style: deepObject
billing_thresholds:
explode: true
style: deepObject
cancel_at:
explode: true
style: deepObject
cancellation_details:
explode: true
style: deepObject
default_source:
explode: true
style: deepObject
default_tax_rates:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
items:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
pause_collection:
explode: true
style: deepObject
payment_settings:
explode: true
style: deepObject
pending_invoice_item_interval:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
trial_end:
explode: true
style: deepObject
trial_settings:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCustomersCustomerSubscriptionsSubscriptionExposedIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Customers Customer Subscriptions Subscription Exposed Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Subscriptions
/v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount:
delete:
description: <p>Removes the currently applied discount on a customer.</p>
operationId: deleteCustomersCustomerSubscriptionsSubscriptionExposedIdDiscount
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- in: path
name: subscription_exposed_id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/DeleteCustomersCustomerSubscriptionsSubscriptionExposedIdDiscountRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/deleted_discount'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Delete Customers Customer Subscriptions Subscription Exposed Id Discount
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Subscriptions
get:
description: ''
operationId: getCustomersCustomerSubscriptionsSubscriptionExposedIdDiscount
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- 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: subscription_exposed_id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersCustomerSubscriptionsSubscriptionExposedIdDiscountRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/discount'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer Subscriptions Subscription Exposed Id Discount
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Subscriptions
/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 the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
- description: The status of the subscriptions to retrieve. Passing in a value of `canceled` will return all canceled subscriptions, including those belonging to deleted customers. Pass `ended` to find subscriptions that are canceled and subscriptions that are expired due to [incomplete payment](https://stripe.com/docs/billing/subscriptions/overview#subscription-statuses). Passing in a value of `all` will return subscriptions of all statuses. If no value is supplied, all subscriptions that have not been canceled are returned.
in: query
name: status
required: false
schema:
enum:
- active
- all
- canceled
- ended
- incomplete
- incomplete_expired
- past_due
- paused
- trialing
- unpaid
type: string
style: form
- description: Filter for subscriptions that are associated with the specified test clock. The response will not include subscriptions with test clocks if this and the customer parameter is not set.
in: query
name: test_clock
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetSubscriptionsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/SubscriptionsSubscriptionList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscriptions
post:
description: '<p>Creates a new subscription on an existing customer. Each customer can have up to 500 active or scheduled subscriptions.</p>
<p>When you create a subscription with <code>collection_method=charge_automatically</code>, the first invoice is finalized as part of the request.
The <code>payment_behavior</code> parameter determines the exact behavior of the initial payment.</p>
<p>To start subscriptions where the first invoice always begins in a <code>draft</code> status, use <a href="/docs/billing/subscriptions/subscription-schedules#managing">subscription schedules</a> instead.
Schedules provide the flexibility to model more complex billing configurations that change over time.</p>'
operationId: PostSubscriptions
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
add_invoice_items:
explode: true
style: deepObject
automatic_tax:
explode: true
style: deepObject
billing_thresholds:
explode: true
style: deepObject
default_tax_rates:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
items:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
on_behalf_of:
explode: true
style: deepObject
payment_settings:
explode: true
style: deepObject
pending_invoice_item_interval:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
trial_end:
explode: true
style: deepObject
trial_settings:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostSubscriptionsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscriptions
/v1/subscriptions/search:
get:
description: '<p>Search for subscriptions you’ve previously created using Stripe’s <a href="/docs/search#search-query-language">Search Query Language</a>.
Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating
conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up
to an hour behind during outages. Search functionality is not available to merchants in India.</p>'
operationId: GetSubscriptionsSearch
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
- 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 pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
in: query
name: page
required: false
schema:
maxLength: 5000
type: string
style: form
- description: The search query string. See [search query language](https://stripe.com/docs/search#search-query-language) and the list of supported [query fields for subscriptions](https://stripe.com/docs/search#query-fields-for-subscriptions).
in: query
name: query
required: true
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetSubscriptionsSearchRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/SearchResult'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscriptions
/v1/subscriptions/{subscription_exposed_id}:
delete:
description: '<p>Cancels a customer’s subscription immediately. The customer will not be charged again for the subscription.</p>
<p>Note, however, that any pending invoice items that you’ve created will still be charged for at the end of the period, unless manually <a href="#delete_invoiceitem">deleted</a>. If you’ve set the subscription to cancel at the end of the period, any pending prorations will also be left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations will be removed.</p>
<p>By default, upon subscription cancellation, Stripe will stop automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.</p>'
operationId: DeleteSubscriptionsSubscriptionExposedId
parameters:
- in: path
name: subscription_exposed_id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
cancellation_details:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/DeleteSubscriptionsSubscriptionExposedIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscriptions
get:
description: <p>Retrieves the subscription with the given ID.</p>
operationId: GetSubscriptionsSubscriptionExposedId
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: subscription_exposed_id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetSubscriptionsSubscriptionExposedIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Subscriptions
post:
description: '<p>Updates an existing subscription to match the specifi
# --- truncated at 32 KB (211 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-subscriptions-api-openapi.yml