Stripe Billing API
Create and manage subscriptions, recurring payments, and recurring revenue.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Accounts Account Billing 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: Billing
paths:
/v1/billing_portal/configurations:
get:
description: <p>Returns a list of configurations that describe the functionality of the customer portal.</p>
operationId: getBillingPortalConfigurations
parameters:
- description: Only return configurations that are active or inactive (e.g., pass `true` to only list active configurations).
in: query
name: active
required: false
schema:
type: boolean
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: Only return the default or non-default configurations (e.g., pass `true` to only list the default configuration).
in: query
name: is_default
required: false
schema:
type: boolean
style: form
- 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/GetBillingPortalConfigurationsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/PortalPublicResourceConfigurationList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Billing Portal Configurations
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Billing
post:
description: <p>Creates a configuration that describes the functionality and behavior of a PortalSession</p>
operationId: postBillingPortalConfigurations
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
business_profile:
explode: true
style: deepObject
default_return_url:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
features:
explode: true
style: deepObject
login_page:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostBillingPortalConfigurationsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/billing_portal.configuration'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Billing Portal Configurations
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Billing
/v1/billing_portal/configurations/{configuration}:
get:
description: <p>Retrieves a configuration that describes the functionality of the customer portal.</p>
operationId: getBillingPortalConfigurationsConfiguration
parameters:
- in: path
name: configuration
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
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetBillingPortalConfigurationsConfigurationRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/billing_portal.configuration'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Billing Portal Configurations Configuration
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Billing
post:
description: <p>Updates a configuration that describes the functionality of the customer portal.</p>
operationId: postBillingPortalConfigurationsConfiguration
parameters:
- in: path
name: configuration
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
business_profile:
explode: true
style: deepObject
default_return_url:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
features:
explode: true
style: deepObject
login_page:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostBillingPortalConfigurationsConfigurationRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/billing_portal.configuration'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Billing Portal Configurations Configuration
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Billing
/v1/billing_portal/sessions:
post:
description: <p>Creates a session of the customer portal.</p>
operationId: postBillingPortalSessions
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
flow_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostBillingPortalSessionsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/billing_portal.session'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Billing Portal Sessions
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Billing
components:
schemas:
PortalPublicResourceConfigurationList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/billing_portal.configuration'
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/billing_portal/configurations
type: string
GetBillingPortalConfigurationsRequest:
type: object
properties: {}
PostBillingPortalSessionsRequest:
type: object
required:
- customer
properties:
configuration:
description: The ID of an existing [configuration](https://stripe.com/docs/api/customer_portal/configuration) to use for this session, describing its functionality and features. If not specified, the session uses the default configuration.
maxLength: 5000
type: string
customer:
description: The ID of an existing customer.
maxLength: 5000
type: string
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
flow_data:
description: Information about a specific flow for the customer to go through. See the [docs](https://stripe.com/docs/customer-management/portal-deep-links) to learn more about using customer portal deep links and flows.
properties:
after_completion:
properties:
hosted_confirmation:
properties:
custom_message:
maxLength: 500
type: string
title: after_completion_hosted_confirmation_param
type: object
redirect:
properties:
return_url:
type: string
required:
- return_url
title: after_completion_redirect_param
type: object
type:
enum:
- hosted_confirmation
- portal_homepage
- redirect
type: string
required:
- type
title: flow_data_after_completion_param
type: object
subscription_cancel:
properties:
retention:
properties:
coupon_offer:
properties:
coupon:
maxLength: 5000
type: string
required:
- coupon
title: coupon_offer_param
type: object
type:
enum:
- coupon_offer
type: string
required:
- coupon_offer
- type
title: retention_param
type: object
subscription:
maxLength: 5000
type: string
required:
- subscription
title: flow_data_subscription_cancel_param
type: object
subscription_update:
properties:
subscription:
maxLength: 5000
type: string
required:
- subscription
title: flow_data_subscription_update_param
type: object
subscription_update_confirm:
properties:
discounts:
items:
properties:
coupon:
maxLength: 5000
type: string
promotion_code:
maxLength: 5000
type: string
title: subscription_update_confirm_discount_params
type: object
type: array
items:
items:
properties:
id:
maxLength: 5000
type: string
price:
maxLength: 5000
type: string
quantity:
type: integer
required:
- id
title: subscription_update_confirm_item_params
type: object
type: array
subscription:
maxLength: 5000
type: string
required:
- items
- subscription
title: flow_data_subscription_update_confirm_param
type: object
type:
enum:
- payment_method_update
- subscription_cancel
- subscription_update
- subscription_update_confirm
type: string
required:
- type
title: flow_data_param
type: object
locale:
description: The IETF language tag of the locale customer portal is displayed in. If blank or auto, the customer’s `preferred_locales` or browser’s locale is used.
enum:
- auto
- bg
- cs
- da
- de
- el
- en
- en-AU
- en-CA
- en-GB
- en-IE
- en-IN
- en-NZ
- en-SG
- es
- es-419
- et
- fi
- fil
- fr
- fr-CA
- hr
- hu
- id
- it
- ja
- ko
- lt
- lv
- ms
- mt
- nb
- nl
- pl
- pt
- pt-BR
- ro
- ru
- sk
- sl
- sv
- th
- tr
- vi
- zh
- zh-HK
- zh-TW
type: string
on_behalf_of:
description: The `on_behalf_of` account to use for this session. When specified, only subscriptions and invoices with this `on_behalf_of` account appear in the portal. For more information, see the [docs](https://stripe.com/docs/connect/separate-charges-and-transfers#on-behalf-of). Use the [Accounts API](https://stripe.com/docs/api/accounts/object#account_object-settings-branding) to modify the `on_behalf_of` account's branding settings, which the portal displays.
type: string
return_url:
description: The default URL to redirect customers to when they click on the portal's link to return to your website.
type: string
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
billing_portal.session:
description: 'The Billing customer portal is a Stripe-hosted UI for subscription and
billing management.
A portal configuration describes the functionality and features that you
want to provide to your customers through the portal.
A portal session describes the instantiation of the customer portal for
a particular customer. By visiting the session''s URL, the customer
can manage their subscriptions and billing details. For security reasons,
sessions are short-lived and will expire if the customer does not visit the URL.
Create sessions on-demand when customers intend to manage their subscriptions
and billing details.
Learn more in the [integration guide](https://stripe.com/docs/billing/subscriptions/integrating-customer-portal).'
properties:
configuration:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/billing_portal.configuration'
description: The configuration used by this session, describing the features available.
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/billing_portal.configuration'
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
customer:
description: The ID of the customer for this session.
maxLength: 5000
type: string
flow:
anyOf:
- $ref: '#/components/schemas/portal_flows_flow'
description: Information about a specific flow for the customer to go through. See the [docs](https://stripe.com/docs/customer-management/portal-deep-links) to learn more about using customer portal deep links and flows.
nullable: true
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
locale:
description: The IETF language tag of the locale Customer Portal is displayed in. If blank or auto, the customer’s `preferred_locales` or browser’s locale is used.
enum:
- auto
- bg
- cs
- da
- de
- el
- en
- en-AU
- en-CA
- en-GB
- en-IE
- en-IN
- en-NZ
- en-SG
- es
- es-419
- et
- fi
- fil
- fr
- fr-CA
- hr
- hu
- id
- it
- ja
- ko
- lt
- lv
- ms
- mt
- nb
- nl
- pl
- pt
- pt-BR
- ro
- ru
- sk
- sl
- sv
- th
- tr
- vi
- zh
- zh-HK
- zh-TW
nullable: true
type: string
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- billing_portal.session
type: string
on_behalf_of:
description: The account for which the session was created on behalf of. When specified, only subscriptions and invoices with this `on_behalf_of` account appear in the portal. For more information, see the [docs](https://stripe.com/docs/connect/separate-charges-and-transfers#on-behalf-of). Use the [Accounts API](https://stripe.com/docs/api/accounts/object#account_object-settings-branding) to modify the `on_behalf_of` account's branding settings, which the portal displays.
maxLength: 5000
nullable: true
type: string
return_url:
description: The URL to redirect customers to when they click on the portal's link to return to your website.
maxLength: 5000
nullable: true
type: string
url:
description: The short-lived URL of the session that gives customers access to the customer portal.
maxLength: 5000
type: string
required:
- configuration
- created
- customer
- id
- livemode
- object
- url
title: PortalSession
type: object
x-expandableFields:
- configuration
- flow
x-resourceId: billing_portal.session
PostBillingPortalConfigurationsRequest:
type: object
required:
- business_profile
- features
properties:
business_profile:
description: The business information shown to customers in the portal.
properties:
headline:
anyOf:
- maxLength: 60
type: string
- enum:
- ''
type: string
privacy_policy_url:
type: string
terms_of_service_url:
type: string
title: business_profile_create_param
type: object
default_return_url:
anyOf:
- type: string
- enum:
- ''
type: string
description: The default URL to redirect customers to when they click on the portal's link to return to your website. This can be [overriden](https://stripe.com/docs/api/customer_portal/sessions/create#create_portal_session-return_url) when creating the session.
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
features:
description: Information about the features available in the portal.
properties:
customer_update:
properties:
allowed_updates:
anyOf:
- items:
enum:
- address
- email
- name
- phone
- shipping
- tax_id
type: string
type: array
- enum:
- ''
type: string
enabled:
type: boolean
required:
- enabled
title: customer_update_creation_param
type: object
invoice_history:
properties:
enabled:
type: boolean
required:
- enabled
title: invoice_list_param
type: object
payment_method_update:
properties:
enabled:
type: boolean
required:
- enabled
title: payment_method_update_param
type: object
subscription_cancel:
properties:
cancellation_reason:
properties:
enabled:
type: boolean
options:
anyOf:
- items:
enum:
- customer_service
- low_quality
- missing_features
- other
- switched_service
- too_complex
- too_expensive
- unused
type: string
type: array
- enum:
- ''
type: string
required:
- enabled
- options
title: subscription_cancellation_reason_creation_param
type: object
enabled:
type: boolean
mode:
enum:
- at_period_end
- immediately
type: string
proration_behavior:
enum:
- always_invoice
- create_prorations
- none
type: string
required:
- enabled
title: subscription_cancel_creation_param
type: object
subscription_pause:
properties:
enabled:
type: boolean
title: subscription_pause_param
type: object
subscription_update:
properties:
default_allowed_updates:
anyOf:
- items:
enum:
- price
- promotion_code
- quantity
type: string
type: array
- enum:
- ''
type: string
enabled:
type: boolean
products:
anyOf:
- items:
properties:
prices:
items:
maxLength: 5000
type: string
type: array
product:
maxLength: 5000
type: string
required:
- prices
- product
title: subscription_update_product_param
type: object
type: array
- enum:
- ''
type: string
proration_behavior:
enum:
- always_invoice
- create_prorations
- none
type: string
required:
- default_allowed_updates
- enabled
- products
title: subscription_update_creation_param
type: object
title: features_creation_param
type: object
login_page:
description: The hosted login page for this configuration. Learn more about the portal login page in our [integration docs](https://stripe.com/docs/billing/subscriptions/integrating-customer-portal#share).
properties:
enabled:
type: boolean
required:
- enabled
title: login_page_create_param
type: object
metadata:
additionalProperties:
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`.
type: object
PostBillingPortalConfigurationsConfigurationRequest:
type: object
properties:
active:
description: Whether the configuration is active and can be used to create portal sessions.
type: boolean
business_profile:
description: The business information shown to customers in the portal.
properties:
headline:
anyOf:
- maxLength: 60
type: string
- enum:
- ''
type: string
privacy_policy_url:
anyOf:
- type: string
- enum:
- ''
type: string
terms_of_service_url:
anyOf:
- type: string
- enum:
- ''
type: string
title: business_profile_update_param
type: object
default_return_url:
anyOf:
- type: string
- enum:
- ''
type: string
description: The default URL to redirect customers to when they click on the portal's link to return to your website. This can be [overriden](https://stripe.com/docs/api/customer_portal/sessions/create#create_portal_session-return_url) when creating the session.
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
features:
description: Information about the features available in the portal.
properties:
customer_update:
properties:
allowed_updates:
anyOf:
- items:
enum:
- address
- email
- name
- phone
- shipping
- tax_id
type: string
type: array
- enum:
- ''
type: string
enabled:
type: boolean
title: customer_update_updating_param
type: object
invoice_history:
properties:
enabled:
type: boolean
required:
- enabled
title: invoice_list_param
type: object
payment_method_update:
properties:
enabled:
type: boolean
required:
- enabled
title: payment_method_update_param
type: object
subscription_cancel:
properties:
cancellation_reason:
properties:
enabled:
type: boolean
options:
anyOf:
- items:
enum:
- customer_service
- low_quality
- missing_features
- other
- switched_service
- too_complex
- too_expensive
- unused
type: string
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-billing-api-openapi.yml