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: 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.
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: Creates a new subscription on an existing customer.
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: 'Cancels a customer’s subscription. If you set the at_period_end parameter to true, 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 false value, the subscription is terminated immediately. In either case, the customer will not be charged again for the subscription.
Note, however, that any pending invoice items that you’ve created will still be charged for at the end of the period, unless manually deleted. 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.
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.
'
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: Retrieves the subscription with the given ID.
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: 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 upcoming invoice endpoint.
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: Removes the currently applied discount on a customer.
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: By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify status=canceled.
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: 'Creates a new subscription on an existing customer. Each customer can have up to 500 active or scheduled subscriptions.
When you create a subscription with collection_method=charge_automatically, the first invoice is finalized as part of the request.
The payment_behavior parameter determines the exact behavior of the initial payment.
To start subscriptions where the first invoice always begins in a draft status, use subscription schedules instead.
Schedules provide the flexibility to model more complex billing configurations that change over time.
'
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: 'Search for subscriptions you’ve previously created using Stripe’s Search Query Language.
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.
'
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: 'Cancels a customer’s subscription immediately. The customer will not be charged again for the subscription.
Note, however, that any pending invoice items that you’ve created will still be charged for at the end of the period, unless manually deleted. 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.
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.
'
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: Retrieves the subscription with the given ID.
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: 'Updates an existing subscription to match the specified parameters.
When changing prices or quantities, we optionally prorate the price we charge next month to make up for any price changes.
To preview how the proration is calculated, use the upcoming invoice endpoint.
By default, we prorate subscription changes. For example, if a customer signs up on May 1 for a 100 price, they’ll be billed 100 immediately. If on May 15 they switch to a 200 price, then on June 1 they’ll be billed 250 (200 for a renewal of her subscription, plus a 50 prorating adjustment for half of the previous month’s 100 difference). Similarly, a downgrade generates a credit that is applied to the next invoice. We also prorate when you make quantity changes.
Switching prices does not normally change the billing date or generate an immediate charge unless:
- The billing interval is changed (for example, from monthly to yearly).
- The subscription moves from free to paid, or paid to free.
- A trial starts or ends.
In these cases, we apply a credit for the unused time on the previous price, immediately charge the customer using the new price, and reset the billing date.
If you want to charge for an upgrade immediately, pass proration_behavior as always_invoice to create prorations, automatically invoice the customer for those proration adjustments, and attempt to collect payment. If you pass create_prorations, the prorations are created but not automatically invoiced. If you want to bill the customer for the prorations before the subscription’s renewal date, you need to manually invoice the customer.
If you don’t want to prorate, set the proration_behavior option to none. With this option, the customer is billed 100 on May 1 and 200 on June 1. Similarly, if you set proration_behavior to none when switching between different billing intervals (for example, from monthly to yearly), we don’t generate any credits for the old subscription’s unused time. We still reset the billing date and bill immediately for the new subscription.
Updating the quantity on a subscription many times in an hour may result in rate limiting. If you need to bill for a frequently changing quantity, consider integrating usage-based billing instead.
'
operationId: PostSubscriptionsSubscriptionExposedId
parameters:
- 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
description:
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
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/PostSubscriptionsSubscriptionExposedIdRequest'
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
/v1/subscriptions/{subscription_exposed_id}/discount:
delete:
description: Removes the currently applied discount on a subscription.
operationId: DeleteSubscriptionsSubscriptionExposedIdDiscount
parameters:
- 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/DeleteSubscriptionsSubscriptionExposedIdDiscountRequest'
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.
tags:
- Subscriptions
/v1/subscriptions/{subscription}/resume:
post:
description: Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. If a resumption invoice is generated, it must be paid or marked uncollectible before the subscription will be unpaused. If payment succeeds the subscription will become active, and if payment fails the subscription will be past_due. The resumption invoice will void automatically if not paid by the expiration date.
operationId: PostSubscriptionsSubscriptionResume
parameters:
- in: path
name: subscription
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/PostSubscriptionsSubscriptionResumeRequest'
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
components:
schemas:
DeleteCustomersCustomerSubscriptionsSubscriptionExposedIdDiscountRequest:
type: object
properties: {}
GetCustomersCustomerSubscriptionsSubscriptionExposedIdRequest:
type: object
properties: {}
DeleteCustomersCustomerSubscriptionsSubscriptionExposedIdRequest:
type: object
properties:
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
invoice_now:
description: Can be set to `true` if `at_period_end` is not set to `true`. Will generate a final invoice that invoices for any un-invoiced metered usage and new/pending proration invoice items.
type: boolean
prorate:
description: Can be set to `true` if `at_period_end` is not set to `true`. Will generate a proration invoice item that credits remaining unused time until the subscription period end.
type: boolean
PostSubscriptionsRequest:
type: object
required:
- customer
properties:
add_invoice_items:
description: A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items.
items:
properties:
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
- product
title: one_time_price_data_with_negative_amounts
type: object
quantity:
type: integer
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
title: add_invoice_item_entry
type: object
type: array
application_fee_percent:
description: A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees [documentation](https://stripe.com/docs/connect/subscriptions#collecting-fees-on-subscriptions).
type: number
automatic_tax:
description: Automatic tax settings for this subscription. We recommend you only include this parameter when the existing value is being changed.
properties:
enabled:
type: boolean
required:
- enabled
title: automatic_tax_config
type: object
backdate_start_date:
description: For new subscriptions, a past timestamp to backdate the subscription's start date to. If set, the first invoice will contain a proration for the timespan between the start date and the current time. Can be combined with trials and the billing cycle anchor.
format: unix-time
type: integer
billing_cycle_anchor:
description: A future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. The timestamp is in UTC format.
format: unix-time
type: integer
x-stripeBypassValidation: true
billing_thresholds:
anyOf:
- properties:
amount_gte:
type: integer
reset_billing_cycle_anchor:
type: boolean
title: billing_thresholds_param
type: object
- enum:
- ''
type: string
description: Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
cancel_at:
description: A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period.
format: unix-time
type: integer
cancel_at_period_end:
description: Boolean indicating whether this subscription should cancel at the end of the current period.
type: boolean
collection_method:
description: Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically`.
enum:
- charge_automatically
- send_invoice
type: string
coupon:
description: The ID of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription.
maxLength: 5000
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
customer:
description: The identifier of the customer to subscribe.
maxLength: 5000
type: string
days_until_due:
description: Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where `collection_method` is set to `send_invoice`.
type: integer
default_payment_method:
description: ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over `default_source`. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
maxLength: 5000
type: string
default_source:
description: ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If `default_payment_method` is also set, `default_payment_method` will take precedence. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
maxLength: 5000
type: string
default_tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
description: The tax rates that will apply to any subscription item that does not have `tax_rates` set. Invoices created will have their `default_tax_rates` populated from the subscription.
description:
description: The subscription's description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs.
maxLength: 500
type: string
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
items:
description: A list of up to 20 subscription items, each with an attached price.
items:
properties:
billing_thresholds:
anyOf:
- properties:
usage_gte:
type: integer
required:
- usage_gte
title: item_billing_thresholds_param
type: object
- enum:
- ''
type: string
metadata:
additionalProperties:
type: string
type: object
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
recurring:
properties:
interval:
enum:
- day
- month
- week
- year
type: string
interval_count:
type: integer
required:
- interval
title: recurring_adhoc
type: object
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
- product
- recurring
title: recurring_price_data
type: object
quantity:
type: integer
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
title: subscription_item_create_params
type: object
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`.
off_session:
description: Indicates if a customer is on or off-session while an invoice payment is attempted.
type: boolean
on_behalf_of:
anyOf:
- type: string
- enum:
- ''
type: string
description: The account on behalf of which to charge, for each of the subscription's invoices.
payment_behavior:
description: 'Only applies to subscriptions with `collection_method=charge_automatically`.
Use `allow_incomplete` to create subscriptions with `status=incomplete` if the first invoice cannot be paid. Creating subscriptions with this status allows you to manage scenarios where additional user actions are needed to pay a subscription''s invoice. For example, SCA regulation may require 3DS authentication to complete payment. See the [SCA Migration Guide](https://stripe.com/docs/billing/migration/strong-customer-authentication) for Billing to learn more. This is the default behavior.
Use `default_incomplete` to create Subscriptions with `status=incomplete` when the first invoice requires payment, otherwise start as active. Subscriptions transition to `status=active` when successfully confirming the payment intent on the first invoice. This allows simpler management of scenarios where additional user actions are needed to pay a subscription’s invoice. Such as failed payments, [SCA regulation](https://stripe.com/docs/billing/migration/strong-customer-authentication), or collecting a mandate for a bank debit payment method. If the payment intent is not confirmed within 23 hours subscriptions transition to `status=incomplete_expired`, which is a terminal state.
Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription''s first invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not create a subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.
`pending_if_incomplete` is only used with updates and cannot be passed when creating a subscription.
Subscriptions with `collection_method=send_invoice` are automatically activated regardless of the first invoice status.'
enum:
- allow_incomplete
- default_incomplete
- error_if_incomplete
- pending_if_incomplete
type: string
payment_settings:
description: Payment settings to pass to invoices created by the subscription.
properties:
payment_method_options:
properties:
acss_debit:
anyOf:
- properties:
mandate_options:
properties:
transaction_type:
enum:
- business
- personal
type: string
title: mandate_options_param
type: object
verification_method:
enum:
- automatic
- instant
- microdeposits
type: string
x-stripeBypassValidation: true
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
bancontact:
anyOf:
- properties:
preferred_language:
enum:
- de
- en
- fr
- nl
type: string
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
card:
anyOf:
- properties:
mandate_options:
properties:
amount:
type: integer
amount_type:
enum:
- fixed
- maximum
type: string
description:
maxLength: 200
type: string
title: mandate_options_param
type: object
network:
enum:
- amex
- cartes_bancaires
- diners
- discover
- eftpos_au
- interac
- jcb
- mastercard
- unionpay
- unknown
- visa
maxLength: 5000
type: string
x-stripeBypassValidation: true
request_three_d_secure:
enum:
- any
- automatic
type: string
title: subscription_payment_method_options_param
type: object
- enum:
- ''
type: string
customer_balance:
anyOf:
- properties:
bank_transfer:
properties:
eu_bank_transfer:
properties:
country:
maxLength: 5000
type: string
required:
- country
title: eu_bank_transfer_param
type: object
type:
type: string
title: bank_transfer_param
type: object
funding_type:
type: string
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
konbini:
anyOf:
- properties: {}
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
us_bank_account:
anyOf:
- properties:
financial_connections:
properties:
permissions:
items:
enum:
- balances
- ownership
- payment_method
- transactions
maxLength: 5000
type: string
x-stripeBypassValidation: true
type: array
prefetch:
items:
enum:
- balances
- transactions
type: string
x-stripeBypassValidation: true
type: array
title: invoice_linked_account_options_param
type: object
verification_method:
enum:
- automatic
- instant
- microdeposits
type: string
x-stripeBypassValidation: true
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
title: payment_method_options
type: object
payment_method_types:
anyOf:
- items:
enum:
- ach_credit_transfer
- ach_debit
- acss_debit
- au_becs_debit
- bacs_debit
- bancontact
- boleto
- card
- cashapp
- customer_balance
- fpx
- giropay
- grabpay
- ideal
- konbini
- link
- paynow
- paypal
- promptpay
- sepa_debit
- sofort
- us_bank_account
- wechat_pay
type: string
x-stripeBypassValidation: true
type: array
- enum:
- ''
type: string
save_default_payment_method:
enum:
- 'off'
- on_subscription
type: string
title: payment_settings
type: object
pending_invoice_item_interval:
anyOf:
- properties:
interval:
enum:
- day
- month
- week
- year
type: string
interval_count:
type: integer
required:
- interval
title: pending_invoice_item_interval_params
type: object
- enum:
- ''
type: string
description: Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](https://stripe.com/docs/api#create_invoice) for the given subscription at the specified interval.
promotion_code:
description: The API ID of a promotion code to apply to this subscription. A promotion code applied to a subscription will only affect invoices created for that particular subscription.
maxLength: 5000
type: string
proration_behavior:
description: Determines how to handle [prorations](https://stripe.com/docs/subscriptions/billing-cycle#prorations) resulting from the `billing_cycle_anchor`. If no value is passed, the default is `create_prorations`.
enum:
- always_invoice
- create_prorations
- none
type: string
transfer_data:
description: If specified, the funds from the subscription's invoices will be transferred to the destination and the ID of the resulting transfers will be found on the resulting charges.
properties:
amount_percent:
type: number
destination:
type: string
required:
- destination
title: transfer_data_specs
type: object
trial_end:
anyOf:
- enum:
- now
maxLength: 5000
type: string
- format: unix-time
type: integer
description: Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value `now` can be provided to end the customer's trial immediately. Can be at most two years from `billing_cycle_anchor`. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more.
trial_from_plan:
description: Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more.
type: boolean
trial_period_days:
description: Integer representing the number of trial period days before the customer is charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more.
type: integer
trial_settings:
description: Settings related to subscription trials.
properties:
end_behavior:
properties:
missing_payment_method:
enum:
- cancel
- create_invoice
- pause
type: string
required:
- missing_payment_method
title: end_behavior
type: object
required:
- end_behavior
title: trial_settings_config
type: object
DeleteSubscriptionsSubscriptionExposedIdDiscountRequest:
type: object
properties: {}
subscription_item:
description: 'Subscription items allow you to create customer subscriptions with more than
one plan, making it easy to represent complex billing relationships.'
properties:
billing_thresholds:
anyOf:
- $ref: '#/components/schemas/subscription_item_billing_thresholds'
description: Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period
nullable: true
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
type: integer
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
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.
type: object
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- subscription_item
type: string
price:
$ref: '#/components/schemas/price'
quantity:
description: The [quantity](https://stripe.com/docs/subscriptions/quantities) of the plan to which the customer should be subscribed.
type: integer
subscription:
description: The `subscription` this `subscription_item` belongs to.
maxLength: 5000
type: string
tax_rates:
description: The tax rates which apply to this `subscription_item`. When set, the `default_tax_rates` on the subscription do not apply to this `subscription_item`.
items:
$ref: '#/components/schemas/tax_rate'
nullable: true
type: array
required:
- created
- id
- metadata
- object
- price
- subscription
title: SubscriptionItem
type: object
x-expandableFields:
- billing_thresholds
- price
- tax_rates
x-resourceId: subscription_item
GetSubscriptionsSubscriptionExposedIdRequest:
type: object
properties: {}
SubscriptionList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/subscription'
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
type: string
SearchResult:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/subscription'
type: array
has_more:
type: boolean
next_page:
maxLength: 5000
nullable: true
type: string
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- search_result
type: string
total_count:
description: The total number of objects that match the query, only accurate up to 10,000.
type: integer
url:
maxLength: 5000
type: string
deleted_customer:
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:
- customer
type: string
required:
- deleted
- id
- object
title: DeletedCustomer
type: object
x-expandableFields: []
x-resourceId: deleted_customer
SubscriptionsSubscriptionList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/subscription'
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/subscriptions
type: string
GetSubscriptionsSearchRequest:
type: object
properties: {}
customer:
description: 'This object represents a customer of your business. Use it to create recurring charges and track payments that belong to the same customer.
Related guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment)'
properties:
address:
anyOf:
- $ref: '#/components/schemas/address'
description: The customer's address.
nullable: true
balance:
description: The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.
type: integer
cash_balance:
anyOf:
- $ref: '#/components/schemas/cash_balance'
description: The current funds being held by Stripe on behalf of the customer. You can apply these funds towards payment intents when the source is "cash_balance". The `settings[reconciliation_mode]` field describes if these funds apply to these payment intents manually or automatically.
nullable: true
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 code for the currency](https://stripe.com/docs/currencies) the customer can be charged in for recurring billing purposes.
maxLength: 5000
nullable: true
type: string
default_source:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/bank_account'
- $ref: '#/components/schemas/card'
- $ref: '#/components/schemas/source'
description: 'ID of the default payment source for the customer.
If you use payment methods created through the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.'
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/bank_account'
- $ref: '#/components/schemas/card'
- $ref: '#/components/schemas/source'
x-stripeBypassValidation: true
delinquent:
description: 'Tracks the most recent state change on any invoice belonging to the customer. Paying an invoice or marking it uncollectible via the API will set this field to false. An automatic payment failure or passing the `invoice.due_date` will set this field to `true`.
If an invoice becomes uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn''t reset to `false`.
If you care whether the customer has paid their most recent subscription invoice, use `subscription.status` instead. Paying or marking uncollectible any customer invoice regardless of whether it is the latest invoice for a subscription will always set this field to `false`.'
nullable: true
type: boolean
description:
description: An arbitrary string attached to the object. Often useful for displaying to users.
maxLength: 5000
nullable: true
type: string
discount:
anyOf:
- $ref: '#/components/schemas/discount'
description: Describes the current discount active on the customer, if there is one.
nullable: true
email:
description: The customer's email address.
maxLength: 5000
nullable: true
type: string
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
invoice_credit_balance:
additionalProperties:
type: integer
description: The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.
type: object
invoice_prefix:
description: The prefix for the customer used to generate unique invoice numbers.
maxLength: 5000
nullable: true
type: string
invoice_settings:
$ref: '#/components/schemas/invoice_setting_customer_setting'
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.
type: object
name:
description: The customer's full name or business name.
maxLength: 5000
nullable: true
type: string
next_invoice_sequence:
description: The suffix of the customer's next invoice number (for example, 0001).
type: integer
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- customer
type: string
phone:
description: The customer's phone number.
maxLength: 5000
nullable: true
type: string
preferred_locales:
description: The customer's preferred locales (languages), ordered by preference.
items:
maxLength: 5000
type: string
nullable: true
type: array
shipping:
anyOf:
- $ref: '#/components/schemas/shipping'
description: Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
nullable: true
sources:
description: The customer's payment sources, if any.
properties:
data:
description: Details about each object.
items:
anyOf:
- $ref: '#/components/schemas/bank_account'
- $ref: '#/components/schemas/card'
- $ref: '#/components/schemas/source'
title: Polymorphic
x-stripeBypassValidation: true
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
type: string
required:
- data
- has_more
- object
- url
title: ApmsSourcesSourceList
type: object
x-expandableFields:
- data
subscriptions:
description: The customer's current subscriptions, if any.
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/subscription'
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
type: string
required:
- data
- has_more
- object
- url
title: SubscriptionList
type: object
x-expandableFields:
- data
tax:
$ref: '#/components/schemas/customer_tax'
tax_exempt:
description: 'Describes the customer''s tax exemption status, which is `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the following text: **"Reverse charge"**.'
enum:
- exempt
- none
- reverse
nullable: true
type: string
tax_ids:
description: The customer's tax IDs.
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/tax_id'
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
type: string
required:
- data
- has_more
- object
- url
title: TaxIDsList
type: object
x-expandableFields:
- data
test_clock:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/test_helpers.test_clock'
description: ID of the test clock that this customer belongs to.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/test_helpers.test_clock'
required:
- created
- id
- livemode
- object
title: Customer
type: object
x-expandableFields:
- address
- cash_balance
- default_source
- discount
- invoice_settings
- shipping
- sources
- subscriptions
- tax
- tax_ids
- test_clock
x-resourceId: customer
subscription_schedule:
description: 'A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes.
Related guide: [Subscription schedules](https://stripe.com/docs/billing/subscriptions/subscription-schedules)'
properties:
application:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/application'
- $ref: '#/components/schemas/deleted_application'
description: ID of the Connect Application that created the schedule.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/application'
- $ref: '#/components/schemas/deleted_application'
canceled_at:
description: Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch.
format: unix-time
nullable: true
type: integer
completed_at:
description: Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch.
format: unix-time
nullable: true
type: integer
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
current_phase:
anyOf:
- $ref: '#/components/schemas/subscription_schedule_current_phase'
description: Object representing the start and end dates for the current phase of the subscription schedule, if it is `active`.
nullable: true
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
description: ID of the customer who owns the subscription schedule.
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
default_settings:
$ref: '#/components/schemas/subscription_schedules_resource_default_settings'
end_behavior:
description: Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` or `cancel` with the default being `release`. `release` will end the subscription schedule and keep the underlying subscription running.`cancel` will end the subscription schedule and cancel the underlying subscription.
enum:
- cancel
- none
- release
- renew
type: string
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
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
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- subscription_schedule
type: string
phases:
description: Configuration for the subscription schedule's phases.
items:
$ref: '#/components/schemas/subscription_schedule_phase_configuration'
type: array
released_at:
description: Time at which the subscription schedule was released. Measured in seconds since the Unix epoch.
format: unix-time
nullable: true
type: integer
released_subscription:
description: ID of the subscription once managed by the subscription schedule (if it is released).
maxLength: 5000
nullable: true
type: string
status:
description: The present status of the subscription schedule. Possible values are `not_started`, `active`, `completed`, `released`, and `canceled`. You can read more about the different states in our [behavior guide](https://stripe.com/docs/billing/subscriptions/subscription-schedules).
enum:
- active
- canceled
- completed
- not_started
- released
type: string
subscription:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/subscription'
description: ID of the subscription managed by the subscription schedule.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/subscription'
test_clock:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/test_helpers.test_clock'
description: ID of the test clock this subscription schedule belongs to.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/test_helpers.test_clock'
required:
- created
- customer
- default_settings
- end_behavior
- id
- livemode
- object
- phases
- status
title: SubscriptionSchedule
type: object
x-expandableFields:
- application
- current_phase
- customer
- default_settings
- phases
- subscription
- test_clock
x-resourceId: subscription_schedule
deleted_discount:
description: ''
properties:
checkout_session:
description: The Checkout session that this coupon is applied to, if it is applied to a particular session in payment mode. Will not be present for subscription mode.
maxLength: 5000
nullable: true
type: string
coupon:
$ref: '#/components/schemas/coupon'
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
description: The ID of the customer associated with this discount.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
deleted:
description: Always true for a deleted object
enum:
- true
type: boolean
id:
description: The ID of the discount object. Discounts cannot be fetched by ID. Use `expand[]=discounts` in API calls to expand discount IDs in an array.
maxLength: 5000
type: string
invoice:
description: The invoice that the discount's coupon was applied to, if it was applied directly to a particular invoice.
maxLength: 5000
nullable: true
type: string
invoice_item:
description: The invoice item `id` (or invoice line item `id` for invoice line items of type='subscription') that the discount's coupon was applied to, if it was applied directly to a particular invoice item or invoice line item.
maxLength: 5000
nullable: true
type: string
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- discount
type: string
promotion_code:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/promotion_code'
description: The promotion code applied to create this discount.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/promotion_code'
start:
description: Date that the coupon was applied.
format: unix-time
type: integer
subscription:
description: The subscription that this coupon is applied to, if it is applied to a particular subscription.
maxLength: 5000
nullable: true
type: string
required:
- coupon
- deleted
- id
- object
- start
title: DeletedDiscount
type: object
x-expandableFields:
- coupon
- customer
- promotion_code
x-resourceId: deleted_discount
GetCustomersCustomerSubscriptionsSubscriptionExposedIdDiscountRequest:
type: object
properties: {}
card:
description: 'You can store multiple cards on a customer in order to charge the customer
later. You can also store multiple debit cards on a recipient in order to
transfer to those cards later.
Related guide: [Card payments with Sources](https://stripe.com/docs/sources/cards)'
properties:
account:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/account'
description: The account this card belongs to. This attribute will not be in the card object if the card belongs to a customer or recipient instead.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/account'
address_city:
description: City/District/Suburb/Town/Village.
maxLength: 5000
nullable: true
type: string
address_country:
description: Billing address country, if provided when creating card.
maxLength: 5000
nullable: true
type: string
address_line1:
description: Address line 1 (Street address/PO Box/Company name).
maxLength: 5000
nullable: true
type: string
address_line1_check:
description: 'If `address_line1` was provided, results of the check: `pass`, `fail`, `unavailable`, or `unchecked`.'
maxLength: 5000
nullable: true
type: string
address_line2:
description: Address line 2 (Apartment/Suite/Unit/Building).
maxLength: 5000
nullable: true
type: string
address_state:
description: State/County/Province/Region.
maxLength: 5000
nullable: true
type: string
address_zip:
description: ZIP or postal code.
maxLength: 5000
nullable: true
type: string
address_zip_check:
description: 'If `address_zip` was provided, results of the check: `pass`, `fail`, `unavailable`, or `unchecked`.'
maxLength: 5000
nullable: true
type: string
available_payout_methods:
description: A set of available payout methods for this card. Only values from this set should be passed as the `method` when creating a payout.
items:
enum:
- instant
- standard
type: string
nullable: true
type: array
brand:
description: Card brand. Can be `American Express`, `Diners Club`, `Discover`, `Eftpos Australia`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`.
maxLength: 5000
type: string
country:
description: Two-letter ISO code representing the country of the card. You could use this attribute to get a sense of the international breakdown of cards you've collected.
maxLength: 5000
nullable: true
type: string
currency:
description: Three-letter [ISO code for currency](https://stripe.com/docs/payouts). Only applicable on accounts (not customers or recipients). The card can be used as a transfer destination for funds in this currency.
nullable: true
type: string
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
description: The customer that this card belongs to. This attribute will not be in the card object if the card belongs to an account or recipient instead.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
cvc_check:
description: 'If a CVC was provided, results of the check: `pass`, `fail`, `unavailable`, or `unchecked`. A result of unchecked indicates that CVC was provided but hasn''t been checked yet. Checks are typically performed when attaching a card to a Customer object, or when creating a charge. For more details, see [Check if a card is valid without a charge](https://support.stripe.com/questions/check-if-a-card-is-valid-without-a-charge).'
maxLength: 5000
nullable: true
type: string
default_for_currency:
description: Whether this card is the default external account for its currency.
nullable: true
type: boolean
dynamic_last4:
description: (For tokenized numbers only.) The last four digits of the device account number.
maxLength: 5000
nullable: true
type: string
exp_month:
description: Two-digit number representing the card's expiration month.
type: integer
exp_year:
description: Four-digit number representing the card's expiration year.
type: integer
fingerprint:
description: 'Uniquely identifies this particular card number. You can use this attribute to check whether two customers who’ve signed up with you are using the same card number, for example. For payment methods that tokenize card information (Apple Pay, Google Pay), the tokenized number might be provided instead of the underlying card number.
*As of May 1, 2021, card fingerprint in India for Connect changed to allow two fingerprints for the same cardone for India and one for the rest of the world.*'
maxLength: 5000
nullable: true
type: string
funding:
description: Card funding type. Can be `credit`, `debit`, `prepaid`, or `unknown`.
maxLength: 5000
type: string
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
last4:
description: The last four digits of the card.
maxLength: 5000
type: string
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
name:
description: Cardholder name.
maxLength: 5000
nullable: true
type: string
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- card
type: string
status:
description: For external accounts that are cards, possible values are `new` and `errored`. If a payout fails, the status is set to `errored` and [scheduled payouts](https://stripe.com/docs/payouts#payout-schedule) are stopped until account details are updated.
maxLength: 5000
nullable: true
type: string
tokenization_method:
description: If the card number is tokenized, this is the method that was used. Can be `android_pay` (includes Google Pay), `apple_pay`, `masterpass`, `visa_checkout`, or null.
maxLength: 5000
nullable: true
type: string
required:
- brand
- exp_month
- exp_year
- funding
- id
- last4
- object
title: Card
type: object
x-expandableFields:
- account
- customer
x-resourceId: card
DeleteSubscriptionsSubscriptionExposedIdRequest:
type: object
properties:
cancellation_details:
description: Details about why this subscription was cancelled
properties:
comment:
anyOf:
- maxLength: 5000
type: string
- enum:
- ''
type: string
feedback:
enum:
- ''
- customer_service
- low_quality
- missing_features
- other
- switched_service
- too_complex
- too_expensive
- unused
type: string
title: cancellation_details_param
type: object
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
invoice_now:
description: Will generate a final invoice that invoices for any un-invoiced metered usage and new/pending proration invoice items.
type: boolean
prorate:
description: Will generate a proration invoice item that credits remaining unused time until the subscription period end.
type: boolean
PostCustomersCustomerSubscriptionsRequest:
type: object
properties:
add_invoice_items:
description: A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items.
items:
properties:
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
- product
title: one_time_price_data_with_negative_amounts
type: object
quantity:
type: integer
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
title: add_invoice_item_entry
type: object
type: array
application_fee_percent:
description: A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees [documentation](https://stripe.com/docs/connect/subscriptions#collecting-fees-on-subscriptions).
type: number
automatic_tax:
description: Automatic tax settings for this subscription. We recommend you only include this parameter when the existing value is being changed.
properties:
enabled:
type: boolean
required:
- enabled
title: automatic_tax_config
type: object
backdate_start_date:
description: For new subscriptions, a past timestamp to backdate the subscription's start date to. If set, the first invoice will contain a proration for the timespan between the start date and the current time. Can be combined with trials and the billing cycle anchor.
format: unix-time
type: integer
billing_cycle_anchor:
description: A future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. The timestamp is in UTC format.
format: unix-time
type: integer
x-stripeBypassValidation: true
billing_thresholds:
anyOf:
- properties:
amount_gte:
type: integer
reset_billing_cycle_anchor:
type: boolean
title: billing_thresholds_param
type: object
- enum:
- ''
type: string
description: Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
cancel_at:
description: A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period.
format: unix-time
type: integer
cancel_at_period_end:
description: Boolean indicating whether this subscription should cancel at the end of the current period.
type: boolean
collection_method:
description: Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically`.
enum:
- charge_automatically
- send_invoice
type: string
coupon:
description: The ID of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription.
maxLength: 5000
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
days_until_due:
description: Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where `collection_method` is set to `send_invoice`.
type: integer
default_payment_method:
description: ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over `default_source`. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
maxLength: 5000
type: string
default_source:
description: ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If `default_payment_method` is also set, `default_payment_method` will take precedence. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
maxLength: 5000
type: string
default_tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
description: The tax rates that will apply to any subscription item that does not have `tax_rates` set. Invoices created will have their `default_tax_rates` populated from the subscription.
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
items:
description: A list of up to 20 subscription items, each with an attached price.
items:
properties:
billing_thresholds:
anyOf:
- properties:
usage_gte:
type: integer
required:
- usage_gte
title: item_billing_thresholds_param
type: object
- enum:
- ''
type: string
metadata:
additionalProperties:
type: string
type: object
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
recurring:
properties:
interval:
enum:
- day
- month
- week
- year
type: string
interval_count:
type: integer
required:
- interval
title: recurring_adhoc
type: object
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
- product
- recurring
title: recurring_price_data
type: object
quantity:
type: integer
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
title: subscription_item_create_params
type: object
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`.
off_session:
description: Indicates if a customer is on or off-session while an invoice payment is attempted.
type: boolean
payment_behavior:
description: 'Only applies to subscriptions with `collection_method=charge_automatically`.
Use `allow_incomplete` to create subscriptions with `status=incomplete` if the first invoice cannot be paid. Creating subscriptions with this status allows you to manage scenarios where additional user actions are needed to pay a subscription''s invoice. For example, SCA regulation may require 3DS authentication to complete payment. See the [SCA Migration Guide](https://stripe.com/docs/billing/migration/strong-customer-authentication) for Billing to learn more. This is the default behavior.
Use `default_incomplete` to create Subscriptions with `status=incomplete` when the first invoice requires payment, otherwise start as active. Subscriptions transition to `status=active` when successfully confirming the payment intent on the first invoice. This allows simpler management of scenarios where additional user actions are needed to pay a subscription’s invoice. Such as failed payments, [SCA regulation](https://stripe.com/docs/billing/migration/strong-customer-authentication), or collecting a mandate for a bank debit payment method. If the payment intent is not confirmed within 23 hours subscriptions transition to `status=incomplete_expired`, which is a terminal state.
Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription''s first invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not create a subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.
`pending_if_incomplete` is only used with updates and cannot be passed when creating a subscription.
Subscriptions with `collection_method=send_invoice` are automatically activated regardless of the first invoice status.'
enum:
- allow_incomplete
- default_incomplete
- error_if_incomplete
- pending_if_incomplete
type: string
payment_settings:
description: Payment settings to pass to invoices created by the subscription.
properties:
payment_method_options:
properties:
acss_debit:
anyOf:
- properties:
mandate_options:
properties:
transaction_type:
enum:
- business
- personal
type: string
title: mandate_options_param
type: object
verification_method:
enum:
- automatic
- instant
- microdeposits
type: string
x-stripeBypassValidation: true
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
bancontact:
anyOf:
- properties:
preferred_language:
enum:
- de
- en
- fr
- nl
type: string
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
card:
anyOf:
- properties:
mandate_options:
properties:
amount:
type: integer
amount_type:
enum:
- fixed
- maximum
type: string
description:
maxLength: 200
type: string
title: mandate_options_param
type: object
network:
enum:
- amex
- cartes_bancaires
- diners
- discover
- eftpos_au
- interac
- jcb
- mastercard
- unionpay
- unknown
- visa
maxLength: 5000
type: string
x-stripeBypassValidation: true
request_three_d_secure:
enum:
- any
- automatic
type: string
title: subscription_payment_method_options_param
type: object
- enum:
- ''
type: string
customer_balance:
anyOf:
- properties:
bank_transfer:
properties:
eu_bank_transfer:
properties:
country:
maxLength: 5000
type: string
required:
- country
title: eu_bank_transfer_param
type: object
type:
type: string
title: bank_transfer_param
type: object
funding_type:
type: string
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
konbini:
anyOf:
- properties: {}
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
us_bank_account:
anyOf:
- properties:
financial_connections:
properties:
permissions:
items:
enum:
- balances
- ownership
- payment_method
- transactions
maxLength: 5000
type: string
x-stripeBypassValidation: true
type: array
prefetch:
items:
enum:
- balances
- transactions
type: string
x-stripeBypassValidation: true
type: array
title: invoice_linked_account_options_param
type: object
verification_method:
enum:
- automatic
- instant
- microdeposits
type: string
x-stripeBypassValidation: true
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
title: payment_method_options
type: object
payment_method_types:
anyOf:
- items:
enum:
- ach_credit_transfer
- ach_debit
- acss_debit
- au_becs_debit
- bacs_debit
- bancontact
- boleto
- card
- cashapp
- customer_balance
- fpx
- giropay
- grabpay
- ideal
- konbini
- link
- paynow
- paypal
- promptpay
- sepa_debit
- sofort
- us_bank_account
- wechat_pay
type: string
x-stripeBypassValidation: true
type: array
- enum:
- ''
type: string
save_default_payment_method:
enum:
- 'off'
- on_subscription
type: string
title: payment_settings
type: object
pending_invoice_item_interval:
anyOf:
- properties:
interval:
enum:
- day
- month
- week
- year
type: string
interval_count:
type: integer
required:
- interval
title: pending_invoice_item_interval_params
type: object
- enum:
- ''
type: string
description: Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](https://stripe.com/docs/api#create_invoice) for the given subscription at the specified interval.
promotion_code:
description: The API ID of a promotion code to apply to this subscription. A promotion code applied to a subscription will only affect invoices created for that particular subscription.
maxLength: 5000
type: string
proration_behavior:
description: Determines how to handle [prorations](https://stripe.com/docs/subscriptions/billing-cycle#prorations) resulting from the `billing_cycle_anchor`. If no value is passed, the default is `create_prorations`.
enum:
- always_invoice
- create_prorations
- none
type: string
transfer_data:
description: If specified, the funds from the subscription's invoices will be transferred to the destination and the ID of the resulting transfers will be found on the resulting charges.
properties:
amount_percent:
type: number
destination:
type: string
required:
- destination
title: transfer_data_specs
type: object
trial_end:
anyOf:
- enum:
- now
maxLength: 5000
type: string
- format: unix-time
type: integer
description: Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value `now` can be provided to end the customer's trial immediately. Can be at most two years from `billing_cycle_anchor`. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more.
trial_from_plan:
description: Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more.
type: boolean
trial_period_days:
description: Integer representing the number of trial period days before the customer is charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more.
type: integer
trial_settings:
description: Settings related to subscription trials.
properties:
end_behavior:
properties:
missing_payment_method:
enum:
- cancel
- create_invoice
- pause
type: string
required:
- missing_payment_method
title: end_behavior
type: object
required:
- end_behavior
title: trial_settings_config
type: object
cash_balance:
description: A customer's `Cash balance` represents real funds. Customers can add funds to their cash balance by sending a bank transfer. These funds can be used for payment and can eventually be paid out to your bank account.
properties:
available:
additionalProperties:
type: integer
description: A hash of all cash balances available to this customer. You cannot delete a customer with any cash balances, even if the balance is 0. Amounts are represented in the [smallest currency unit](https://stripe.com/docs/currencies#zero-decimal).
nullable: true
type: object
customer:
description: The ID of the customer whose cash balance this object represents.
maxLength: 5000
type: string
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
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- cash_balance
type: string
settings:
$ref: '#/components/schemas/customer_balance_customer_balance_settings'
required:
- customer
- livemode
- object
- settings
title: cash_balance
type: object
x-expandableFields:
- settings
x-resourceId: cash_balance
GetSubscriptionsRequest:
type: object
properties: {}
GetCustomersCustomerSubscriptionsRequest:
type: object
properties: {}
subscription:
description: 'Subscriptions allow you to charge a customer on a recurring basis.
Related guide: [Creating subscriptions](https://stripe.com/docs/billing/subscriptions/creating)'
properties:
application:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/application'
- $ref: '#/components/schemas/deleted_application'
description: ID of the Connect Application that created the subscription.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/application'
- $ref: '#/components/schemas/deleted_application'
application_fee_percent:
description: A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account.
nullable: true
type: number
automatic_tax:
$ref: '#/components/schemas/subscription_automatic_tax'
billing_cycle_anchor:
description: Determines the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. The timestamp is in UTC format.
format: unix-time
type: integer
billing_thresholds:
anyOf:
- $ref: '#/components/schemas/subscription_billing_thresholds'
description: Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period
nullable: true
cancel_at:
description: A date in the future at which the subscription will automatically get canceled
format: unix-time
nullable: true
type: integer
cancel_at_period_end:
description: If the subscription has been canceled with the `at_period_end` flag set to `true`, `cancel_at_period_end` on the subscription will be true. You can use this attribute to determine whether a subscription that has a status of active is scheduled to be canceled at the end of the current period.
type: boolean
canceled_at:
description: If the subscription has been canceled, the date of that cancellation. If the subscription was canceled with `cancel_at_period_end`, `canceled_at` will reflect the time of the most recent update request, not the end of the subscription period when the subscription is automatically moved to a canceled state.
format: unix-time
nullable: true
type: integer
cancellation_details:
anyOf:
- $ref: '#/components/schemas/cancellation_details'
description: Details about why this subscription was cancelled
nullable: true
collection_method:
description: Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`.
enum:
- charge_automatically
- send_invoice
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
current_period_end:
description: End of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.
format: unix-time
type: integer
current_period_start:
description: Start of the current period that the subscription has been invoiced for.
format: unix-time
type: integer
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
description: ID of the customer who owns the subscription.
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
days_until_due:
description: Number of days a customer has to pay invoices generated by this subscription. This value will be `null` for subscriptions where `collection_method=charge_automatically`.
nullable: true
type: integer
default_payment_method:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/payment_method'
description: ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over `default_source`. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/payment_method'
default_source:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/bank_account'
- $ref: '#/components/schemas/card'
- $ref: '#/components/schemas/source'
description: ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If `default_payment_method` is also set, `default_payment_method` will take precedence. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/bank_account'
- $ref: '#/components/schemas/card'
- $ref: '#/components/schemas/source'
x-stripeBypassValidation: true
default_tax_rates:
description: The tax rates that will apply to any subscription item that does not have `tax_rates` set. Invoices created will have their `default_tax_rates` populated from the subscription.
items:
$ref: '#/components/schemas/tax_rate'
nullable: true
type: array
description:
description: The subscription's description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs.
maxLength: 500
nullable: true
type: string
discount:
anyOf:
- $ref: '#/components/schemas/discount'
description: Describes the current discount applied to this subscription, if there is one. When billing, a discount applied to a subscription overrides a discount applied on a customer-wide basis.
nullable: true
ended_at:
description: If the subscription has ended, the date the subscription ended.
format: unix-time
nullable: true
type: integer
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
items:
description: List of subscription items, each with an attached price.
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/subscription_item'
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
type: string
required:
- data
- has_more
- object
- url
title: SubscriptionItemList
type: object
x-expandableFields:
- data
latest_invoice:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/invoice'
description: The most recent invoice this subscription has generated.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/invoice'
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.
type: object
next_pending_invoice_item_invoice:
description: Specifies the approximate timestamp on which any pending invoice items will be billed according to the schedule provided at `pending_invoice_item_interval`.
format: unix-time
nullable: true
type: integer
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- subscription
type: string
on_behalf_of:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/account'
description: The account (if any) the charge was made on behalf of for charges associated with this subscription. See the Connect documentation for details.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/account'
pause_collection:
anyOf:
- $ref: '#/components/schemas/subscriptions_resource_pause_collection'
description: If specified, payment collection for this subscription will be paused.
nullable: true
payment_settings:
anyOf:
- $ref: '#/components/schemas/subscriptions_resource_payment_settings'
description: Payment settings passed on to invoices created by the subscription.
nullable: true
pending_invoice_item_interval:
anyOf:
- $ref: '#/components/schemas/subscription_pending_invoice_item_interval'
description: Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](https://stripe.com/docs/api#create_invoice) for the given subscription at the specified interval.
nullable: true
pending_setup_intent:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/setup_intent'
description: You can use this [SetupIntent](https://stripe.com/docs/api/setup_intents) to collect user authentication when creating a subscription without immediate payment or updating a subscription's payment method, allowing you to optimize for off-session payments. Learn more in the [SCA Migration Guide](https://stripe.com/docs/billing/migration/strong-customer-authentication#scenario-2).
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/setup_intent'
pending_update:
anyOf:
- $ref: '#/components/schemas/subscriptions_resource_pending_update'
description: If specified, [pending updates](https://stripe.com/docs/billing/subscriptions/pending-updates) that will be applied to the subscription once the `latest_invoice` has been paid.
nullable: true
schedule:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/subscription_schedule'
description: The schedule attached to the subscription
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/subscription_schedule'
start_date:
description: Date when the subscription was first created. The date might differ from the `created` date due to backdating.
format: unix-time
type: integer
status:
description: "Possible values are `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `canceled`, or `unpaid`. \n\nFor `collection_method=charge_automatically` a subscription moves into `incomplete` if the initial payment attempt fails. A subscription in this state can only have metadata and default_source updated. Once the first invoice is paid, the subscription moves into an `active` state. If the first invoice is not paid within 23 hours, the subscription transitions to `incomplete_expired`. This is a terminal state, the open invoice will be voided and no further invoices will be generated. \n\nA subscription that is currently in a trial period is `trialing` and moves to `active` when the trial period is over. \n\nIf subscription `collection_method=charge_automatically`, it becomes `past_due` when payment is required but cannot be paid (due to failed payment or awaiting additional user actions). Once Stripe has exhausted all payment retry attempts, the subscription will become `canceled` or `unpaid` (depending on your subscriptions settings). \n\nIf subscription `collection_method=send_invoice` it becomes `past_due` when its invoice is not paid by the due date, and `canceled` or `unpaid` if it is still not paid by an additional deadline after that. Note that when a subscription has a status of `unpaid`, no subsequent invoices will be attempted (invoices will be created, but then immediately automatically closed). After receiving updated payment information from a customer, you may choose to reopen and pay their closed invoices."
enum:
- active
- canceled
- incomplete
- incomplete_expired
- past_due
- paused
- trialing
- unpaid
type: string
test_clock:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/test_helpers.test_clock'
description: ID of the test clock this subscription belongs to.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/test_helpers.test_clock'
transfer_data:
anyOf:
- $ref: '#/components/schemas/subscription_transfer_data'
description: The account (if any) the subscription's payments will be attributed to for tax reporting, and where funds from each payment will be transferred to for each of the subscription's invoices.
nullable: true
trial_end:
description: If the subscription has a trial, the end of that trial.
format: unix-time
nullable: true
type: integer
trial_settings:
anyOf:
- $ref: '#/components/schemas/subscriptions_trials_resource_trial_settings'
description: Settings related to subscription trials.
nullable: true
trial_start:
description: If the subscription has a trial, the beginning of that trial.
format: unix-time
nullable: true
type: integer
required:
- automatic_tax
- billing_cycle_anchor
- cancel_at_period_end
- collection_method
- created
- currency
- current_period_end
- current_period_start
- customer
- id
- items
- livemode
- metadata
- object
- start_date
- status
title: Subscription
type: object
x-expandableFields:
- application
- automatic_tax
- billing_thresholds
- cancellation_details
- customer
- default_payment_method
- default_source
- default_tax_rates
- discount
- items
- latest_invoice
- on_behalf_of
- pause_collection
- payment_settings
- pending_invoice_item_interval
- pending_setup_intent
- pending_update
- schedule
- test_clock
- transfer_data
- trial_settings
x-resourceId: subscription
bank_account:
description: 'These bank accounts are payment methods on `Customer` objects.
On the other hand [External Accounts](https://stripe.com/docs/api#external_accounts) are transfer
destinations on `Account` objects for [Custom accounts](https://stripe.com/docs/connect/custom-accounts).
They can be bank accounts or debit cards as well, and are documented in the links above.
Related guide: [Bank debits and transfers](https://stripe.com/docs/payments/bank-debits-transfers)'
properties:
account:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/account'
description: The ID of the account that the bank account is associated with.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/account'
account_holder_name:
description: The name of the person or business that owns the bank account.
maxLength: 5000
nullable: true
type: string
account_holder_type:
description: The type of entity that holds the account. This can be either `individual` or `company`.
maxLength: 5000
nullable: true
type: string
account_type:
description: The bank account type. This can only be `checking` or `savings` in most countries. In Japan, this can only be `futsu` or `toza`.
maxLength: 5000
nullable: true
type: string
available_payout_methods:
description: A set of available payout methods for this bank account. Only values from this set should be passed as the `method` when creating a payout.
items:
enum:
- instant
- standard
type: string
nullable: true
type: array
bank_name:
description: Name of the bank associated with the routing number (e.g., `WELLS FARGO`).
maxLength: 5000
nullable: true
type: string
country:
description: Two-letter ISO code representing the country the bank account is located in.
maxLength: 5000
type: string
currency:
description: Three-letter [ISO code for the currency](https://stripe.com/docs/payouts) paid out to the bank account.
type: string
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
description: The ID of the customer that the bank account is associated with.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
default_for_currency:
description: Whether this bank account is the default external account for its currency.
nullable: true
type: boolean
fingerprint:
description: Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.
maxLength: 5000
nullable: true
type: string
future_requirements:
anyOf:
- $ref: '#/components/schemas/external_account_requirements'
description: Information about the [upcoming new requirements for the bank account](https://stripe.com/docs/connect/custom-accounts/future-requirements), including what information needs to be collected, and by when.
nullable: true
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
last4:
description: The last four digits of the bank account number.
maxLength: 5000
type: string
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
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- bank_account
type: string
requirements:
anyOf:
- $ref: '#/components/schemas/external_account_requirements'
description: Information about the requirements for the bank account, including what information needs to be collected.
nullable: true
routing_number:
description: The routing transit number for the bank account.
maxLength: 5000
nullable: true
type: string
status:
description: 'For bank accounts, possible values are `new`, `validated`, `verified`, `verification_failed`, or `errored`. A bank account that hasn''t had any activity or validation performed is `new`. If Stripe can determine that the bank account exists, its status will be `validated`. Note that there often isn’t enough information to know (e.g., for smaller credit unions), and the validation is not always run. If customer bank account verification has succeeded, the bank account status will be `verified`. If the verification failed for any reason, such as microdeposit failure, the status will be `verification_failed`. If a payout sent to this bank account fails, we''ll set the status to `errored` and will not continue to send [scheduled payouts](https://stripe.com/docs/payouts#payout-schedule) until the bank details are updated.
For external accounts, possible values are `new`, `errored` and `verification_failed`. If a payouts fails, the status is set to `errored` and scheduled payouts are stopped until account details are updated. In India, if we can''t [verify the owner of the bank account](https://support.stripe.com/questions/bank-account-ownership-verification), we''ll set the status to `verification_failed`. Other validations aren''t run against external accounts because they''re only used for payouts. This means the other statuses don''t apply.'
maxLength: 5000
type: string
required:
- country
- currency
- id
- last4
- object
- status
title: BankAccount
type: object
x-expandableFields:
- account
- customer
- future_requirements
- requirements
x-resourceId: bank_account
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
PostSubscriptionsSubscriptionExposedIdRequest:
type: object
properties:
add_invoice_items:
description: A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items.
items:
properties:
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
- product
title: one_time_price_data_with_negative_amounts
type: object
quantity:
type: integer
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
title: add_invoice_item_entry
type: object
type: array
application_fee_percent:
description: A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees [documentation](https://stripe.com/docs/connect/subscriptions#collecting-fees-on-subscriptions).
type: number
automatic_tax:
description: Automatic tax settings for this subscription. We recommend you only include this parameter when the existing value is being changed.
properties:
enabled:
type: boolean
required:
- enabled
title: automatic_tax_config
type: object
billing_cycle_anchor:
description: Either `now` or `unchanged`. Setting the value to `now` resets the subscription's billing cycle anchor to the current time (in UTC). For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle).
enum:
- now
- unchanged
maxLength: 5000
type: string
x-stripeBypassValidation: true
billing_thresholds:
anyOf:
- properties:
amount_gte:
type: integer
reset_billing_cycle_anchor:
type: boolean
title: billing_thresholds_param
type: object
- enum:
- ''
type: string
description: Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
cancel_at:
anyOf:
- format: unix-time
type: integer
- enum:
- ''
type: string
description: A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period.
cancel_at_period_end:
description: Boolean indicating whether this subscription should cancel at the end of the current period.
type: boolean
cancellation_details:
description: Details about why this subscription was cancelled
properties:
comment:
anyOf:
- maxLength: 5000
type: string
- enum:
- ''
type: string
feedback:
enum:
- ''
- customer_service
- low_quality
- missing_features
- other
- switched_service
- too_complex
- too_expensive
- unused
type: string
title: cancellation_details_param
type: object
collection_method:
description: Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically`.
enum:
- charge_automatically
- send_invoice
type: string
coupon:
description: The ID of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription.
maxLength: 5000
type: string
days_until_due:
description: Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where `collection_method` is set to `send_invoice`.
type: integer
default_payment_method:
description: ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over `default_source`. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
maxLength: 5000
type: string
default_source:
anyOf:
- maxLength: 5000
type: string
- enum:
- ''
type: string
description: ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If `default_payment_method` is also set, `default_payment_method` will take precedence. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
default_tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
description: The tax rates that will apply to any subscription item that does not have `tax_rates` set. Invoices created will have their `default_tax_rates` populated from the subscription. Pass an empty string to remove previously-defined tax rates.
description:
anyOf:
- maxLength: 500
type: string
- enum:
- ''
type: string
description: The subscription's description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs.
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
items:
description: A list of up to 20 subscription items, each with an attached price.
items:
properties:
billing_thresholds:
anyOf:
- properties:
usage_gte:
type: integer
required:
- usage_gte
title: item_billing_thresholds_param
type: object
- enum:
- ''
type: string
clear_usage:
type: boolean
deleted:
type: boolean
id:
maxLength: 5000
type: string
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- enum:
- ''
type: string
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
recurring:
properties:
interval:
enum:
- day
- month
- week
- year
type: string
interval_count:
type: integer
required:
- interval
title: recurring_adhoc
type: object
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
- product
- recurring
title: recurring_price_data
type: object
quantity:
type: integer
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
title: subscription_item_update_params
type: object
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`.
off_session:
description: Indicates if a customer is on or off-session while an invoice payment is attempted.
type: boolean
on_behalf_of:
anyOf:
- type: string
- enum:
- ''
type: string
description: The account on behalf of which to charge, for each of the subscription's invoices.
pause_collection:
anyOf:
- properties:
behavior:
enum:
- keep_as_draft
- mark_uncollectible
- void
type: string
resumes_at:
format: unix-time
type: integer
required:
- behavior
title: pause_collection_param
type: object
- enum:
- ''
type: string
description: If specified, payment collection for this subscription will be paused.
payment_behavior:
description: 'Use `allow_incomplete` to transition the subscription to `status=past_due` if a payment is required but cannot be paid. This allows you to manage scenarios where additional user actions are needed to pay a subscription''s invoice. For example, SCA regulation may require 3DS authentication to complete payment. See the [SCA Migration Guide](https://stripe.com/docs/billing/migration/strong-customer-authentication) for Billing to learn more. This is the default behavior.
Use `default_incomplete` to transition the subscription to `status=past_due` when payment is required and await explicit confirmation of the invoice''s payment intent. This allows simpler management of scenarios where additional user actions are needed to pay a subscription’s invoice. Such as failed payments, [SCA regulation](https://stripe.com/docs/billing/migration/strong-customer-authentication), or collecting a mandate for a bank debit payment method.
Use `pending_if_incomplete` to update the subscription using [pending updates](https://stripe.com/docs/billing/subscriptions/pending-updates). When you use `pending_if_incomplete` you can only pass the parameters [supported by pending updates](https://stripe.com/docs/billing/pending-updates-reference#supported-attributes).
Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription''s invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not update the subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.'
enum:
- allow_incomplete
- default_incomplete
- error_if_incomplete
- pending_if_incomplete
type: string
payment_settings:
description: Payment settings to pass to invoices created by the subscription.
properties:
payment_method_options:
properties:
acss_debit:
anyOf:
- properties:
mandate_options:
properties:
transaction_type:
enum:
- business
- personal
type: string
title: mandate_options_param
type: object
verification_method:
enum:
- automatic
- instant
- microdeposits
type: string
x-stripeBypassValidation: true
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
bancontact:
anyOf:
- properties:
preferred_language:
enum:
- de
- en
- fr
- nl
type: string
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
card:
anyOf:
- properties:
mandate_options:
properties:
amount:
type: integer
amount_type:
enum:
- fixed
- maximum
type: string
description:
maxLength: 200
type: string
title: mandate_options_param
type: object
network:
enum:
- amex
- cartes_bancaires
- diners
- discover
- eftpos_au
- interac
- jcb
- mastercard
- unionpay
- unknown
- visa
maxLength: 5000
type: string
x-stripeBypassValidation: true
request_three_d_secure:
enum:
- any
- automatic
type: string
title: subscription_payment_method_options_param
type: object
- enum:
- ''
type: string
customer_balance:
anyOf:
- properties:
bank_transfer:
properties:
eu_bank_transfer:
properties:
country:
maxLength: 5000
type: string
required:
- country
title: eu_bank_transfer_param
type: object
type:
type: string
title: bank_transfer_param
type: object
funding_type:
type: string
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
konbini:
anyOf:
- properties: {}
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
us_bank_account:
anyOf:
- properties:
financial_connections:
properties:
permissions:
items:
enum:
- balances
- ownership
- payment_method
- transactions
maxLength: 5000
type: string
x-stripeBypassValidation: true
type: array
prefetch:
items:
enum:
- balances
- transactions
type: string
x-stripeBypassValidation: true
type: array
title: invoice_linked_account_options_param
type: object
verification_method:
enum:
- automatic
- instant
- microdeposits
type: string
x-stripeBypassValidation: true
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
title: payment_method_options
type: object
payment_method_types:
anyOf:
- items:
enum:
- ach_credit_transfer
- ach_debit
- acss_debit
- au_becs_debit
- bacs_debit
- bancontact
- boleto
- card
- cashapp
- customer_balance
- fpx
- giropay
- grabpay
- ideal
- konbini
- link
- paynow
- paypal
- promptpay
- sepa_debit
- sofort
- us_bank_account
- wechat_pay
type: string
x-stripeBypassValidation: true
type: array
- enum:
- ''
type: string
save_default_payment_method:
enum:
- 'off'
- on_subscription
type: string
title: payment_settings
type: object
pending_invoice_item_interval:
anyOf:
- properties:
interval:
enum:
- day
- month
- week
- year
type: string
interval_count:
type: integer
required:
- interval
title: pending_invoice_item_interval_params
type: object
- enum:
- ''
type: string
description: Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](https://stripe.com/docs/api#create_invoice) for the given subscription at the specified interval.
promotion_code:
description: The promotion code to apply to this subscription. A promotion code applied to a subscription will only affect invoices created for that particular subscription.
maxLength: 5000
type: string
proration_behavior:
description: Determines how to handle [prorations](https://stripe.com/docs/subscriptions/billing-cycle#prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`.
enum:
- always_invoice
- create_prorations
- none
type: string
proration_date:
description: If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply exactly the same proration that was previewed with [upcoming invoice](https://stripe.com/docs/api#upcoming_invoice) endpoint. It can also be used to implement custom proration logic, such as prorating by day instead of by second, by providing the time that you wish to use for proration calculations.
format: unix-time
type: integer
transfer_data:
anyOf:
- properties:
amount_percent:
type: number
destination:
type: string
required:
- destination
title: transfer_data_specs
type: object
- enum:
- ''
type: string
description: If specified, the funds from the subscription's invoices will be transferred to the destination and the ID of the resulting transfers will be found on the resulting charges. This will be unset if you POST an empty value.
trial_end:
anyOf:
- enum:
- now
maxLength: 5000
type: string
- format: unix-time
type: integer
description: Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value `now` can be provided to end the customer's trial immediately. Can be at most two years from `billing_cycle_anchor`.
trial_from_plan:
description: Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more.
type: boolean
trial_settings:
description: Settings related to subscription trials.
properties:
end_behavior:
properties:
missing_payment_method:
enum:
- cancel
- create_invoice
- pause
type: string
required:
- missing_payment_method
title: end_behavior
type: object
required:
- end_behavior
title: trial_settings_config
type: object
discount:
description: 'A discount represents the actual application of a [coupon](https://stripe.com/docs/api#coupons) or [promotion code](https://stripe.com/docs/api#promotion_codes).
It contains information about when the discount began, when it will end, and what it is applied to.
Related guide: [Applying discounts to subscriptions](https://stripe.com/docs/billing/subscriptions/discounts)'
properties:
checkout_session:
description: The Checkout session that this coupon is applied to, if it is applied to a particular session in payment mode. Will not be present for subscription mode.
maxLength: 5000
nullable: true
type: string
coupon:
$ref: '#/components/schemas/coupon'
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
description: The ID of the customer associated with this discount.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
end:
description: If the coupon has a duration of `repeating`, the date that this discount will end. If the coupon has a duration of `once` or `forever`, this attribute will be null.
format: unix-time
nullable: true
type: integer
id:
description: The ID of the discount object. Discounts cannot be fetched by ID. Use `expand[]=discounts` in API calls to expand discount IDs in an array.
maxLength: 5000
type: string
invoice:
description: The invoice that the discount's coupon was applied to, if it was applied directly to a particular invoice.
maxLength: 5000
nullable: true
type: string
invoice_item:
description: The invoice item `id` (or invoice line item `id` for invoice line items of type='subscription') that the discount's coupon was applied to, if it was applied directly to a particular invoice item or invoice line item.
maxLength: 5000
nullable: true
type: string
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- discount
type: string
promotion_code:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/promotion_code'
description: The promotion code applied to create this discount.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/promotion_code'
start:
description: Date that the coupon was applied.
format: unix-time
type: integer
subscription:
description: The subscription that this coupon is applied to, if it is applied to a particular subscription.
maxLength: 5000
nullable: true
type: string
required:
- coupon
- id
- object
- start
title: Discount
type: object
x-expandableFields:
- coupon
- customer
- promotion_code
x-resourceId: discount
tax_id:
description: 'You can add one or multiple tax IDs to a [customer](https://stripe.com/docs/api/customers) or account.
Customer and account tax IDs get displayed on related invoices and credit notes.
Related guides: [Customer tax identification numbers](https://stripe.com/docs/billing/taxes/tax-ids), [Account tax IDs](https://stripe.com/docs/invoicing/connect#account-tax-ids)'
properties:
country:
description: Two-letter ISO code representing the country of the tax ID.
maxLength: 5000
nullable: true
type: string
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
description: ID of the customer.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
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
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- tax_id
type: string
type:
description: Type of the tax ID, one of `ad_nrt`, `ae_trn`, `ar_cuit`, `au_abn`, `au_arn`, `bg_uic`, `bo_tin`, `br_cnpj`, `br_cpf`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `ch_vat`, `cl_tin`, `cn_tin`, `co_nit`, `cr_tin`, `do_rcn`, `ec_ruc`, `eg_tin`, `es_cif`, `eu_oss_vat`, `eu_vat`, `gb_vat`, `ge_vat`, `hk_br`, `hu_tin`, `id_npwp`, `il_vat`, `in_gst`, `is_vat`, `jp_cn`, `jp_rn`, `jp_trn`, `ke_pin`, `kr_brn`, `li_uid`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `no_vat`, `nz_gst`, `pe_ruc`, `ph_tin`, `ro_tin`, `rs_pib`, `ru_inn`, `ru_kpp`, `sa_vat`, `sg_gst`, `sg_uen`, `si_tin`, `sv_nit`, `th_vat`, `tr_tin`, `tw_vat`, `ua_vat`, `us_ein`, `uy_ruc`, `ve_rif`, `vn_tin`, or `za_vat`. Note that some legacy tax IDs have type `unknown`
enum:
- ad_nrt
- ae_trn
- ar_cuit
- au_abn
- au_arn
- bg_uic
- bo_tin
- br_cnpj
- br_cpf
- ca_bn
- ca_gst_hst
- ca_pst_bc
- ca_pst_mb
- ca_pst_sk
- ca_qst
- ch_vat
- cl_tin
- cn_tin
- co_nit
- cr_tin
- do_rcn
- ec_ruc
- eg_tin
- es_cif
- eu_oss_vat
- eu_vat
- gb_vat
- ge_vat
- hk_br
- hu_tin
- id_npwp
- il_vat
- in_gst
- is_vat
- jp_cn
- jp_rn
- jp_trn
- ke_pin
- kr_brn
- li_uid
- mx_rfc
- my_frp
- my_itn
- my_sst
- no_vat
- nz_gst
- pe_ruc
- ph_tin
- ro_tin
- rs_pib
- ru_inn
- ru_kpp
- sa_vat
- sg_gst
- sg_uen
- si_tin
- sv_nit
- th_vat
- tr_tin
- tw_vat
- ua_vat
- unknown
- us_ein
- uy_ruc
- ve_rif
- vn_tin
- za_vat
type: string
value:
description: Value of the tax ID.
maxLength: 5000
type: string
verification:
anyOf:
- $ref: '#/components/schemas/tax_id_verification'
description: Tax ID verification information.
nullable: true
required:
- created
- id
- livemode
- object
- type
- value
title: tax_id
type: object
x-expandableFields:
- customer
- verification
x-resourceId: tax_id
PostCustomersCustomerSubscriptionsSubscriptionExposedIdRequest:
type: object
properties:
add_invoice_items:
description: A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items.
items:
properties:
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
- product
title: one_time_price_data_with_negative_amounts
type: object
quantity:
type: integer
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
title: add_invoice_item_entry
type: object
type: array
application_fee_percent:
description: A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees [documentation](https://stripe.com/docs/connect/subscriptions#collecting-fees-on-subscriptions).
type: number
automatic_tax:
description: Automatic tax settings for this subscription. We recommend you only include this parameter when the existing value is being changed.
properties:
enabled:
type: boolean
required:
- enabled
title: automatic_tax_config
type: object
billing_cycle_anchor:
description: Either `now` or `unchanged`. Setting the value to `now` resets the subscription's billing cycle anchor to the current time. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle).
enum:
- now
- unchanged
maxLength: 5000
type: string
x-stripeBypassValidation: true
billing_thresholds:
anyOf:
- properties:
amount_gte:
type: integer
reset_billing_cycle_anchor:
type: boolean
title: billing_thresholds_param
type: object
- enum:
- ''
type: string
description: Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
cancel_at:
anyOf:
- format: unix-time
type: integer
- enum:
- ''
type: string
description: A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period.
cancel_at_period_end:
description: Boolean indicating whether this subscription should cancel at the end of the current period.
type: boolean
cancellation_details:
description: Details about why this subscription was cancelled
properties:
comment:
anyOf:
- maxLength: 5000
type: string
- enum:
- ''
type: string
feedback:
enum:
- ''
- customer_service
- low_quality
- missing_features
- other
- switched_service
- too_complex
- too_expensive
- unused
type: string
title: cancellation_details_param
type: object
collection_method:
description: Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically`.
enum:
- charge_automatically
- send_invoice
type: string
coupon:
description: The ID of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription.
maxLength: 5000
type: string
days_until_due:
description: Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where `collection_method` is set to `send_invoice`.
type: integer
default_payment_method:
description: ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over `default_source`. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
maxLength: 5000
type: string
default_source:
anyOf:
- maxLength: 5000
type: string
- enum:
- ''
type: string
description: ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If `default_payment_method` is also set, `default_payment_method` will take precedence. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
default_tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
description: The tax rates that will apply to any subscription item that does not have `tax_rates` set. Invoices created will have their `default_tax_rates` populated from the subscription. Pass an empty string to remove previously-defined tax rates.
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
items:
description: A list of up to 20 subscription items, each with an attached price.
items:
properties:
billing_thresholds:
anyOf:
- properties:
usage_gte:
type: integer
required:
- usage_gte
title: item_billing_thresholds_param
type: object
- enum:
- ''
type: string
clear_usage:
type: boolean
deleted:
type: boolean
id:
maxLength: 5000
type: string
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- enum:
- ''
type: string
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
recurring:
properties:
interval:
enum:
- day
- month
- week
- year
type: string
interval_count:
type: integer
required:
- interval
title: recurring_adhoc
type: object
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
- product
- recurring
title: recurring_price_data
type: object
quantity:
type: integer
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
title: subscription_item_update_params
type: object
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`.
off_session:
description: Indicates if a customer is on or off-session while an invoice payment is attempted.
type: boolean
pause_collection:
anyOf:
- properties:
behavior:
enum:
- keep_as_draft
- mark_uncollectible
- void
type: string
resumes_at:
format: unix-time
type: integer
required:
- behavior
title: pause_collection_param
type: object
- enum:
- ''
type: string
description: If specified, payment collection for this subscription will be paused.
payment_behavior:
description: 'Use `allow_incomplete` to transition the subscription to `status=past_due` if a payment is required but cannot be paid. This allows you to manage scenarios where additional user actions are needed to pay a subscription''s invoice. For example, SCA regulation may require 3DS authentication to complete payment. See the [SCA Migration Guide](https://stripe.com/docs/billing/migration/strong-customer-authentication) for Billing to learn more. This is the default behavior.
Use `default_incomplete` to transition the subscription to `status=past_due` when payment is required and await explicit confirmation of the invoice''s payment intent. This allows simpler management of scenarios where additional user actions are needed to pay a subscription’s invoice. Such as failed payments, [SCA regulation](https://stripe.com/docs/billing/migration/strong-customer-authentication), or collecting a mandate for a bank debit payment method.
Use `pending_if_incomplete` to update the subscription using [pending updates](https://stripe.com/docs/billing/subscriptions/pending-updates). When you use `pending_if_incomplete` you can only pass the parameters [supported by pending updates](https://stripe.com/docs/billing/pending-updates-reference#supported-attributes).
Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription''s invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not update the subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.'
enum:
- allow_incomplete
- default_incomplete
- error_if_incomplete
- pending_if_incomplete
type: string
payment_settings:
description: Payment settings to pass to invoices created by the subscription.
properties:
payment_method_options:
properties:
acss_debit:
anyOf:
- properties:
mandate_options:
properties:
transaction_type:
enum:
- business
- personal
type: string
title: mandate_options_param
type: object
verification_method:
enum:
- automatic
- instant
- microdeposits
type: string
x-stripeBypassValidation: true
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
bancontact:
anyOf:
- properties:
preferred_language:
enum:
- de
- en
- fr
- nl
type: string
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
card:
anyOf:
- properties:
mandate_options:
properties:
amount:
type: integer
amount_type:
enum:
- fixed
- maximum
type: string
description:
maxLength: 200
type: string
title: mandate_options_param
type: object
network:
enum:
- amex
- cartes_bancaires
- diners
- discover
- eftpos_au
- interac
- jcb
- mastercard
- unionpay
- unknown
- visa
maxLength: 5000
type: string
x-stripeBypassValidation: true
request_three_d_secure:
enum:
- any
- automatic
type: string
title: subscription_payment_method_options_param
type: object
- enum:
- ''
type: string
customer_balance:
anyOf:
- properties:
bank_transfer:
properties:
eu_bank_transfer:
properties:
country:
maxLength: 5000
type: string
required:
- country
title: eu_bank_transfer_param
type: object
type:
type: string
title: bank_transfer_param
type: object
funding_type:
type: string
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
konbini:
anyOf:
- properties: {}
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
us_bank_account:
anyOf:
- properties:
financial_connections:
properties:
permissions:
items:
enum:
- balances
- ownership
- payment_method
- transactions
maxLength: 5000
type: string
x-stripeBypassValidation: true
type: array
prefetch:
items:
enum:
- balances
- transactions
type: string
x-stripeBypassValidation: true
type: array
title: invoice_linked_account_options_param
type: object
verification_method:
enum:
- automatic
- instant
- microdeposits
type: string
x-stripeBypassValidation: true
title: invoice_payment_method_options_param
type: object
- enum:
- ''
type: string
title: payment_method_options
type: object
payment_method_types:
anyOf:
- items:
enum:
- ach_credit_transfer
- ach_debit
- acss_debit
- au_becs_debit
- bacs_debit
- bancontact
- boleto
- card
- cashapp
- customer_balance
- fpx
- giropay
- grabpay
- ideal
- konbini
- link
- paynow
- paypal
- promptpay
- sepa_debit
- sofort
- us_bank_account
- wechat_pay
type: string
x-stripeBypassValidation: true
type: array
- enum:
- ''
type: string
save_default_payment_method:
enum:
- 'off'
- on_subscription
type: string
title: payment_settings
type: object
pending_invoice_item_interval:
anyOf:
- properties:
interval:
enum:
- day
- month
- week
- year
type: string
interval_count:
type: integer
required:
- interval
title: pending_invoice_item_interval_params
type: object
- enum:
- ''
type: string
description: Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](https://stripe.com/docs/api#create_invoice) for the given subscription at the specified interval.
promotion_code:
description: The promotion code to apply to this subscription. A promotion code applied to a subscription will only affect invoices created for that particular subscription.
maxLength: 5000
type: string
proration_behavior:
description: Determines how to handle [prorations](https://stripe.com/docs/subscriptions/billing-cycle#prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`.
enum:
- always_invoice
- create_prorations
- none
type: string
proration_date:
description: If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply exactly the same proration that was previewed with [upcoming invoice](https://stripe.com/docs/api#upcoming_invoice) endpoint. It can also be used to implement custom proration logic, such as prorating by day instead of by second, by providing the time that you wish to use for proration calculations.
format: unix-time
type: integer
transfer_data:
anyOf:
- properties:
amount_percent:
type: number
destination:
type: string
required:
- destination
title: transfer_data_specs
type: object
- enum:
- ''
type: string
description: If specified, the funds from the subscription's invoices will be transferred to the destination and the ID of the resulting transfers will be found on the resulting charges. This will be unset if you POST an empty value.
trial_end:
anyOf:
- enum:
- now
maxLength: 5000
type: string
- format: unix-time
type: integer
description: Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value `now` can be provided to end the customer's trial immediately. Can be at most two years from `billing_cycle_anchor`.
trial_from_plan:
description: Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more.
type: boolean
trial_settings:
description: Settings related to subscription trials.
properties:
end_behavior:
properties:
missing_payment_method:
enum:
- cancel
- create_invoice
- pause
type: string
required:
- missing_payment_method
title: end_behavior
type: object
required:
- end_behavior
title: trial_settings_config
type: object
payment_method:
description: 'PaymentMethod objects represent your customer''s payment instruments.
You can use them with [PaymentIntents](https://stripe.com/docs/payments/payment-intents) to collect payments or save them to
Customer objects to store instrument details for future payments.
Related guides: [Payment Methods](https://stripe.com/docs/payments/payment-methods) and [More Payment Scenarios](https://stripe.com/docs/payments/more-payment-scenarios).'
properties:
acss_debit:
$ref: '#/components/schemas/payment_method_acss_debit'
affirm:
$ref: '#/components/schemas/payment_method_affirm'
afterpay_clearpay:
$ref: '#/components/schemas/payment_method_afterpay_clearpay'
alipay:
$ref: '#/components/schemas/payment_flows_private_payment_methods_alipay'
au_becs_debit:
$ref: '#/components/schemas/payment_method_au_becs_debit'
bacs_debit:
$ref: '#/components/schemas/payment_method_bacs_debit'
bancontact:
$ref: '#/components/schemas/payment_method_bancontact'
billing_details:
$ref: '#/components/schemas/billing_details'
blik:
$ref: '#/components/schemas/payment_method_blik'
boleto:
$ref: '#/components/schemas/payment_method_boleto'
card:
$ref: '#/components/schemas/payment_method_card'
card_present:
$ref: '#/components/schemas/payment_method_card_present'
cashapp:
$ref: '#/components/schemas/payment_method_cashapp'
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
description: The ID of the Customer to which this PaymentMethod is saved. This will not be set when the PaymentMethod has not been saved to a Customer.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
customer_balance:
$ref: '#/components/schemas/payment_method_customer_balance'
eps:
$ref: '#/components/schemas/payment_method_eps'
fpx:
$ref: '#/components/schemas/payment_method_fpx'
giropay:
$ref: '#/components/schemas/payment_method_giropay'
grabpay:
$ref: '#/components/schemas/payment_method_grabpay'
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
ideal:
$ref: '#/components/schemas/payment_method_ideal'
interac_present:
$ref: '#/components/schemas/payment_method_interac_present'
klarna:
$ref: '#/components/schemas/payment_method_klarna'
konbini:
$ref: '#/components/schemas/payment_method_konbini'
link:
$ref: '#/components/schemas/payment_method_link'
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
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- payment_method
type: string
oxxo:
$ref: '#/components/schemas/payment_method_oxxo'
p24:
$ref: '#/components/schemas/payment_method_p24'
paynow:
$ref: '#/components/schemas/payment_method_paynow'
paypal:
$ref: '#/components/schemas/payment_method_paypal'
pix:
$ref: '#/components/schemas/payment_method_pix'
promptpay:
$ref: '#/components/schemas/payment_method_promptpay'
radar_options:
$ref: '#/components/schemas/radar_radar_options'
revolut_pay:
$ref: '#/components/schemas/payment_method_revolut_pay'
sepa_debit:
$ref: '#/components/schemas/payment_method_sepa_debit'
sofort:
$ref: '#/components/schemas/payment_method_sofort'
type:
description: The type of the PaymentMethod. An additional hash is included on the PaymentMethod with a name matching this value. It contains additional information specific to the PaymentMethod type.
enum:
- acss_debit
- affirm
- afterpay_clearpay
- alipay
- au_becs_debit
- bacs_debit
- bancontact
- blik
- boleto
- card
- card_present
- cashapp
- customer_balance
- eps
- fpx
- giropay
- grabpay
- ideal
- interac_present
- klarna
- konbini
- link
- oxxo
- p24
- paynow
- paypal
- pix
- promptpay
- revolut_pay
- sepa_debit
- sofort
- us_bank_account
- wechat_pay
- zip
type: string
x-stripeBypassValidation: true
us_bank_account:
$ref: '#/components/schemas/payment_method_us_bank_account'
wechat_pay:
$ref: '#/components/schemas/payment_method_wechat_pay'
zip:
$ref: '#/components/schemas/payment_method_zip'
required:
- billing_details
- created
- id
- livemode
- object
- type
title: PaymentMethod
type: object
x-expandableFields:
- acss_debit
- affirm
- afterpay_clearpay
- alipay
- au_becs_debit
- bacs_debit
- bancontact
- billing_details
- blik
- boleto
- card
- card_present
- cashapp
- customer
- customer_balance
- eps
- fpx
- giropay
- grabpay
- ideal
- interac_present
- klarna
- konbini
- link
- oxxo
- p24
- paynow
- paypal
- pix
- promptpay
- radar_options
- revolut_pay
- sepa_debit
- sofort
- us_bank_account
- wechat_pay
- zip
x-resourceId: payment_method
PostSubscriptionsSubscriptionResumeRequest:
type: object
properties:
billing_cycle_anchor:
description: Either `now` or `unchanged`. Setting the value to `now` resets the subscription's billing cycle anchor to the current time (in UTC). Setting the value to `unchanged` advances the subscription's billing cycle anchor to the period that surrounds the current time. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle).
enum:
- now
- unchanged
maxLength: 5000
type: string
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
proration_behavior:
description: Determines how to handle [prorations](https://stripe.com/docs/subscriptions/billing-cycle#prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`.
enum:
- always_invoice
- create_prorations
- none
type: string
proration_date:
description: If set, the proration will be calculated as though the subscription was resumed at the given time. This can be used to apply exactly the same proration that was previewed with [upcoming invoice](https://stripe.com/docs/api#retrieve_customer_invoice) endpoint.
format: unix-time
type: integer