API reference

Test mode. Use your secret key on your server; live processing is currently disabled.

https://api.knoxapi.com

Send form-encoded requests with Authorization: Bearer sk_test_....

Complete OpenAPI specification · Integration guide

Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.

GET /v1/customers

List all customers

Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.

Request parameters

Parameter	Location	Type	Description
`created`	query	one of multiple schemas	Only return customers that were created during the given date interval.
`email`	query	string	A case-sensitive filter on the list based on the customer's `email` field. The value must be a string.
`ending_before`	query	string	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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	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.
`test_clock`	query	string	Provides a list of customers that are associated with the specified test clock. The response will not include customers with test clocks if this parameter is not set.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of customer
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers

Create a customer

Creates a new customer object.

Request parameters

Field	Type	Description
`address`	one of multiple schemas	The customer's address. Learn about [country-specific requirements for calculating tax](https://docs.stripe.com/invoicing/taxes?dashboard-or-api=dashboard#set-up-customer).
`balance`	integer	An integer amount in cents (or local equivalent) that represents the customer's current balance, which affect the customer's future invoices. A negative amount represents a credit that decreases the amount due on an invoice; a positive amount increases the amount due on an invoice.
`business_name`	one of multiple schemas	The customer's business name. This may be up to 150 characters.
`cash_balance`	object	Balance information and default balance settings for this customer.
`description`	string	An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.
`email`	string	Customer's email address. It's displayed alongside the customer in your dashboard and can be useful for searching and tracking. This may be up to 512 characters.
`expand`	array of string	Specifies which fields in the response should be expanded.
`individual_name`	one of multiple schemas	The customer's full name. This may be up to 150 characters.
`invoice_prefix`	string	The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.
`invoice_settings`	object	Default invoice settings for this customer.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.
`name`	string	The customer's full name or business name.
`next_invoice_sequence`	integer	The sequence to be used on the customer's next invoice. Defaults to 1.
`payment_method`	string
`phone`	string	The customer's phone number.
`preferred_locales`	array of string	Customer's preferred languages, ordered by preference.
`shipping`	one of multiple schemas	The customer's shipping information. Appears on invoices emailed to this customer.
`source`	string
`tax`	object	Tax details about the customer.
`tax_exempt`	string	The customer's tax exemption. One of `none`, `exempt`, or `reverse`.
`tax_id_data`	array of object	The customer's tax IDs.
`test_clock`	string	ID of the test clock to attach to the customer.

Responses

HTTP 200: Successful response.

Field	Type	Description
`address`	one of multiple schemas	The customer's address.
`balance`	integer	The current balance, if any, that's stored on the customer in their default currency. 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. For multi-currency balances, see [invoice_credit_balance](https://docs.stripe.com/api/customers/object#customer_object-invoice_credit_balance).
`business_name`	string	The customer's business name.
`cash_balance`	one of multiple schemas	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.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency`	string	Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) the customer can be charged in for recurring billing purposes.
`customer_account`	string	The ID of an Account representing a customer. You can use this ID with any v1 API that accepts a customer_account parameter.
`default_source`	one of multiple schemas	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.
`delinquent`	boolean	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://docs.stripe.com/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`.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`discount`	one of multiple schemas	Describes the current discount active on the customer, if there is one.
`email`	string	The customer's email address.
`id` required	string	Unique identifier for the object.
`individual_name`	string	The customer's individual name.
`invoice_credit_balance`	object	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.
`invoice_prefix`	string	The prefix for the customer used to generate unique invoice numbers.
`invoice_settings`	invoice_setting_customer_setting
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`name`	string	The customer's full name or business name.
`next_invoice_sequence`	integer	The suffix of the customer's next invoice number (for example, 0001). When the account uses account level sequencing, this parameter is ignored in API requests and the field omitted in API responses.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`phone`	string	The customer's phone number.
`preferred_locales`	array of string	The customer's preferred locales (languages), ordered by preference.
`shipping`	one of multiple schemas	Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
`sources`	object	The customer's payment sources, if any.
`subscriptions`	object	The customer's current subscriptions, if any.
`tax`	customer_tax
`tax_exempt`	string	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".
`tax_ids`	object	The customer's tax IDs.
`test_clock`	one of multiple schemas	ID of the test clock that this customer belongs to.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/search

Search customers

Search for customers 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.

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`page`	query	string	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.
`query`	query	string	The search query string. See [search query language](https://docs.stripe.com/search#search-query-language) and the list of supported [query fields for customers](https://docs.stripe.com/search#query-fields-for-customers).

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of customer
`has_more` required	boolean
`next_page`	string
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`total_count`	integer	The total number of objects that match the query, only accurate up to 10,000.
`url` required	string

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

DELETE /v1/customers/{customer}

Delete a customer

Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`deleted` required	boolean	Always true for a deleted object
`id` required	string	Unique identifier for the object.
`object` required	string	String representing the object's type. Objects of the same type share the same value.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}

Retrieve a customer

Retrieves a Customer object.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

one of multiple schemas. See the OpenAPI specification for the complete schema.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}

Update a customer

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided are left unchanged. For example, if you pass the source parameter, that becomes the customer’s active source (such as a card) to be used for all charges in the future. When you update a customer to a new valid card source by passing the source parameter: for each of the customer’s current subscriptions, if the subscription bills automatically and is in the past_due state, then the latest open invoice for the subscription with automatic collection enabled is retried. This retry doesn’t count as an automatic retry, and doesn’t affect the next regularly scheduled payment for the invoice. Changing the default_source for a customer doesn’t trigger this behavior. This request accepts mostly the same arguments as the customer creation call.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

Field	Type	Description
`address`	one of multiple schemas	The customer's address. Learn about [country-specific requirements for calculating tax](https://docs.stripe.com/invoicing/taxes?dashboard-or-api=dashboard#set-up-customer).
`balance`	integer	An integer amount in cents (or local equivalent) that represents the customer's current balance, which affect the customer's future invoices. A negative amount represents a credit that decreases the amount due on an invoice; a positive amount increases the amount due on an invoice.
`bank_account`	one of multiple schemas	Either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/js), or a dictionary containing a user's bank account details.
`business_name`	one of multiple schemas	The customer's business name. This may be up to 150 characters.
`card`	one of multiple schemas	A token, like the ones returned by [Stripe.js](https://stripe.com/docs/js).
`cash_balance`	object	Balance information and default balance settings for this customer.
`default_alipay_account`	string	ID of Alipay account to make the customer's new default for invoice payments.
`default_bank_account`	string	ID of bank account to make the customer's new default for invoice payments.
`default_card`	string	ID of card to make the customer's new default for invoice payments.
`default_source`	string	If you are using payment methods created via the PaymentMethods API, see the [invoice_settings.default_payment_method](https://docs.stripe.com/api/customers/update#update_customer-invoice_settings-default_payment_method) parameter. Provide the ID of a payment source already attached to this customer to make it this customer's default payment source. If you want to add a new payment source and make it the default, see the [source](https://docs.stripe.com/api/customers/update#update_customer-source) property.
`description`	string	An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.
`email`	string	Customer's email address. It's displayed alongside the customer in your dashboard and can be useful for searching and tracking. This may be up to 512 characters.
`expand`	array of string	Specifies which fields in the response should be expanded.
`individual_name`	one of multiple schemas	The customer's full name. This may be up to 150 characters.
`invoice_prefix`	string	The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.
`invoice_settings`	object	Default invoice settings for this customer.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.
`name`	string	The customer's full name or business name.
`next_invoice_sequence`	integer	The sequence to be used on the customer's next invoice. Defaults to 1.
`phone`	string	The customer's phone number.
`preferred_locales`	array of string	Customer's preferred languages, ordered by preference.
`shipping`	one of multiple schemas	The customer's shipping information. Appears on invoices emailed to this customer.
`source`	string
`tax`	object	Tax details about the customer.
`tax_exempt`	string	The customer's tax exemption. One of `none`, `exempt`, or `reverse`.

Responses

HTTP 200: Successful response.

Field	Type	Description
`address`	one of multiple schemas	The customer's address.
`balance`	integer	The current balance, if any, that's stored on the customer in their default currency. 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. For multi-currency balances, see [invoice_credit_balance](https://docs.stripe.com/api/customers/object#customer_object-invoice_credit_balance).
`business_name`	string	The customer's business name.
`cash_balance`	one of multiple schemas	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.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency`	string	Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) the customer can be charged in for recurring billing purposes.
`customer_account`	string	The ID of an Account representing a customer. You can use this ID with any v1 API that accepts a customer_account parameter.
`default_source`	one of multiple schemas	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.
`delinquent`	boolean	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://docs.stripe.com/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`.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`discount`	one of multiple schemas	Describes the current discount active on the customer, if there is one.
`email`	string	The customer's email address.
`id` required	string	Unique identifier for the object.
`individual_name`	string	The customer's individual name.
`invoice_credit_balance`	object	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.
`invoice_prefix`	string	The prefix for the customer used to generate unique invoice numbers.
`invoice_settings`	invoice_setting_customer_setting
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`name`	string	The customer's full name or business name.
`next_invoice_sequence`	integer	The suffix of the customer's next invoice number (for example, 0001). When the account uses account level sequencing, this parameter is ignored in API requests and the field omitted in API responses.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`phone`	string	The customer's phone number.
`preferred_locales`	array of string	The customer's preferred locales (languages), ordered by preference.
`shipping`	one of multiple schemas	Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
`sources`	object	The customer's payment sources, if any.
`subscriptions`	object	The customer's current subscriptions, if any.
`tax`	customer_tax
`tax_exempt`	string	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".
`tax_ids`	object	The customer's tax IDs.
`test_clock`	one of multiple schemas	ID of the test clock that this customer belongs to.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/balance_transactions

List customer balance transactions

Returns a list of transactions that updated the customer’s balances.

Request parameters

Parameter	Location	Type	Description
`created`	query	one of multiple schemas	Only return customer balance transactions that were created during the given date interval.
`customer`	path	string
`ending_before`	query	string	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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`invoice`	query	string	Only return transactions that are related to the specified invoice.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	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.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of customer_balance_transaction	Details about each object.
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/balance_transactions

Create a customer balance transaction

Creates an immutable transaction that updates the customer’s credit balance.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

Field	Type	Description
`amount` required	integer	The integer amount in cents (or local equivalent) to apply to the customer's credit balance.
`currency` required	string	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). Specifies the [`invoice_credit_balance`](https://docs.stripe.com/api/customers/object#customer_object-invoice_credit_balance) that this transaction will apply to. If the customer's `currency` is not set, it will be updated to this value.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	The amount of the transaction. A negative value is a credit for the customer's balance, and a positive value is a debit to the customer's `balance`.
`checkout_session`	one of multiple schemas	The ID of the checkout session (if any) that created the transaction.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`credit_note`	one of multiple schemas	The ID of the credit note (if any) related to the transaction.
`currency` required	string	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).
`customer` required	one of multiple schemas	The ID of the customer the transaction belongs to.
`customer_account`	string	The ID of an Account representing a customer that the transaction belongs to.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`ending_balance` required	integer	The customer's `balance` after the transaction was applied. A negative value decreases the amount due on the customer's next invoice. A positive value increases the amount due on the customer's next invoice.
`id` required	string	Unique identifier for the object.
`invoice`	one of multiple schemas	The ID of the invoice (if any) related to the transaction.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`type` required	string	Transaction type: `adjustment`, `applied_to_invoice`, `credit_note`, `initial`, `invoice_overpaid`, `invoice_too_large`, `invoice_too_small`, `unspent_receiver_credit`, `unapplied_from_invoice`, `checkout_session_subscription_payment`, or `checkout_session_subscription_payment_canceled`. See the [Customer Balance page](https://docs.stripe.com/billing/customer/balance#types) to learn more about transaction types.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/bank_accounts

List all bank accounts

You can see a list of the bank accounts belonging to a Customer. Note that the 10 most recent sources are always available by default on the Customer. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional bank accounts.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`ending_before`	query	string	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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	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.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of bank_account	Details about each object.
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/bank_accounts

Create a card

When you create a new credit card, you must specify a customer or recipient on which to create it. If the card’s owner has no default card, then the new card will become the default. However, if the owner already has a default, then it will not change. To change the default, you should update the customer to have a new default_source.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

Field	Type	Description
`alipay_account`	string	A token returned by [Stripe.js](https://stripe.com/docs/js) representing the user’s Alipay account details.
`bank_account`	one of multiple schemas	Either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/js), or a dictionary containing a user's bank account details.
`card`	one of multiple schemas	A token, like the ones returned by [Stripe.js](https://stripe.com/docs/js).
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/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`.
`source`	string	Please refer to full [documentation](https://api.stripe.com) instead.

Responses

HTTP 200: Successful response.

one of multiple schemas. See the OpenAPI specification for the complete schema.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/cards

List all cards

You can see a list of the cards belonging to a customer. Note that the 10 most recent sources are always available on the Customer object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional cards.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`ending_before`	query	string	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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	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.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of card
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/cards

Create a card

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

Field	Type	Description
`alipay_account`	string	A token returned by [Stripe.js](https://stripe.com/docs/js) representing the user’s Alipay account details.
`bank_account`	one of multiple schemas	Either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/js), or a dictionary containing a user's bank account details.
`card`	one of multiple schemas	A token, like the ones returned by [Stripe.js](https://stripe.com/docs/js).
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/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`.
`source`	string	Please refer to full [documentation](https://api.stripe.com) instead.

Responses

HTTP 200: Successful response.

one of multiple schemas. See the OpenAPI specification for the complete schema.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/cash_balance

Retrieve a cash balance

Retrieves a customer’s cash balance.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`available`	object	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://docs.stripe.com/currencies#zero-decimal).
`customer` required	string	The ID of the customer whose cash balance this object represents.
`customer_account`	string	The ID of an Account representing a customer whose cash balance this object represents.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`settings` required	customer_balance_customer_balance_settings

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/cash_balance

Update a cash balance's settings

Changes the settings on a customer’s cash balance.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`settings`	object	A hash of settings for this cash balance.

Responses

HTTP 200: Successful response.

Field	Type	Description
`available`	object	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://docs.stripe.com/currencies#zero-decimal).
`customer` required	string	The ID of the customer whose cash balance this object represents.
`customer_account`	string	The ID of an Account representing a customer whose cash balance this object represents.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`settings` required	customer_balance_customer_balance_settings

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/cash_balance_transactions

List cash balance transactions

Returns a list of transactions that modified the customer’s cash balance.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`ending_before`	query	string	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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	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.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of customer_cash_balance_transaction	Details about each object.
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

DELETE /v1/customers/{customer}/discount

Delete a customer discount

Removes the currently applied discount on a customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`checkout_session`	string	The Checkout session that this coupon is applied to, if it is applied to a particular session in payment mode. Not present for subscription mode.
`customer`	one of multiple schemas	The ID of the customer associated with this discount.
`customer_account`	string	The ID of the account representing the customer associated with this discount.
`deleted` required	boolean	Always true for a deleted object
`id` required	string	The ID of the discount object. Discounts can't be fetched by ID. Use `expand[]=discounts` in API calls to expand discount IDs in an array.
`invoice`	string	The invoice that the discount's coupon was applied to, if it was applied directly to a particular invoice.
`invoice_item`	string	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`promotion_code`	one of multiple schemas	The promotion code applied to create this discount.
`source` required	discount_source
`start` required	integer	Date that the coupon was applied.
`subscription`	string	The subscription that this coupon is applied to, if it is applied to a particular subscription.
`subscription_item`	string	The subscription item that this coupon is applied to, if it is applied to a particular subscription item.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/discount

/v1/customers/{customer}/discount

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`checkout_session`	string	The Checkout session that this coupon is applied to, if it is applied to a particular session in payment mode. Not present for subscription mode.
`customer`	one of multiple schemas	The ID of the customer associated with this discount.
`customer_account`	string	The ID of the account representing the customer associated with this discount.
`end`	integer	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.
`id` required	string	The ID of the discount object. Discounts can't be fetched by ID. Use `expand[]=discounts` in API calls to expand discount IDs in an array.
`invoice`	string	The invoice that the discount's coupon was applied to, if it was applied directly to a particular invoice.
`invoice_item`	string	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`promotion_code`	one of multiple schemas	The promotion code applied to create this discount.
`source` required	discount_source
`start` required	integer	Date that the coupon was applied.
`subscription`	string	The subscription that this coupon is applied to, if it is applied to a particular subscription.
`subscription_item`	string	The subscription item that this coupon is applied to, if it is applied to a particular subscription item.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/funding_instructions

Create or retrieve funding instructions for a customer cash balance

Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new funding instructions will be created. If funding instructions have already been created for a given customer, the same funding instructions will be retrieved. In other words, we will return the same funding instructions each time.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

Field	Type	Description
`bank_transfer` required	object	Additional parameters for `bank_transfer` funding types
`currency` required	string	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).
`expand`	array of string	Specifies which fields in the response should be expanded.
`funding_type` required	string	The `funding_type` to get the instructions for.

Responses

HTTP 200: Successful response.

Field	Type	Description
`bank_transfer` required	funding_instructions_bank_transfer
`currency` required	string	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).
`funding_type` required	string	The `funding_type` of the returned instructions
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/payment_methods

List a Customer's PaymentMethods

Returns a list of PaymentMethods for a given Customer

Request parameters

Parameter	Location	Type	Description
`allow_redisplay`	query	string	This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow.
`customer`	path	string
`ending_before`	query	string	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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	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.
`type`	query	string	An optional filter on the list, based on the object `type` field. Without the filter, the list includes all current and future payment method types. If your integration expects only one type of payment method in the response, make sure to provide a type value in the request.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of payment_method
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/sources

/v1/customers/{customer}/sources

List sources for a specified customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`ending_before`	query	string	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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`object`	query	string	Filter sources according to a particular object type.
`starting_after`	query	string	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.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of one of multiple schemas	Details about each object.
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/sources

Create a card

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

Field	Type	Description
`alipay_account`	string	A token returned by [Stripe.js](https://stripe.com/docs/js) representing the user’s Alipay account details.
`bank_account`	one of multiple schemas	Either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/js), or a dictionary containing a user's bank account details.
`card`	one of multiple schemas	A token, like the ones returned by [Stripe.js](https://stripe.com/docs/js).
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/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`.
`source`	string	Please refer to full [documentation](https://api.stripe.com) instead.

Responses

HTTP 200: Successful response.

one of multiple schemas. See the OpenAPI specification for the complete schema.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/subscriptions

List active subscriptions

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.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`ending_before`	query	string	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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	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.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of subscription	Details about each object.
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/subscriptions

Create a subscription

Creates a new subscription on an existing customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

Field	Type	Description
`add_invoice_items`	array of object	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.
`application_fee_percent`	one of multiple schemas	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).
`automatic_tax`	object	Automatic tax settings for this subscription.
`backdate_start_date`	integer	A past timestamp to backdate the subscription's start date to. If set, the first invoice will contain line items for the timespan between the start date and the current time. Can be combined with trials and the billing cycle anchor.
`billing_cycle_anchor`	integer	A future timestamp in UTC format to anchor the subscription's [billing cycle](https://docs.stripe.com/subscriptions/billing-cycle). The anchor is the reference point that aligns future billing cycle dates. It sets the day of week for `week` intervals, the day of month for `month` and `year` intervals, and the month of year for `year` intervals.
`billing_thresholds`	one of multiple schemas	Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds.
`cancel_at`	one of multiple schemas	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`	boolean	Indicate whether this subscription should cancel at the end of the current period (`current_period_end`). Defaults to `false`.
`collection_method`	string	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`.
`currency`	string	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).
`days_until_due`	integer	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`.
`default_payment_method`	string	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_source`	string	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_tax_rates`	one of multiple schemas	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.
`discounts`	one of multiple schemas	The coupons to redeem into discounts for the subscription. If not specified or empty, inherits the discount from the subscription's customer.
`expand`	array of string	Specifies which fields in the response should be expanded.
`invoice_settings`	object	All invoices will be billed using the specified settings.
`items`	array of object	A list of up to 20 subscription items, each with an attached price.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`	boolean	Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `false` (on-session).
`payment_behavior`	string	Controls how Stripe handles the first invoice when payment is required and `collection_method=charge_automatically`. Subscriptions with `collection_method=send_invoice` are automatically activated regardless of the first Invoice status.
`payment_settings`	object	Payment settings to pass to invoices created by the subscription.
`pending_invoice_item_interval`	one of multiple schemas	Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](/api/invoices/create) for the given subscription at the specified interval.
`proration_behavior`	string	Determines how to handle [prorations](https://docs.stripe.com/billing/subscriptions/prorations) resulting from the `billing_cycle_anchor`. If no value is passed, the default is `create_prorations`.
`transfer_data`	object	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.
`trial_end`	one of multiple schemas	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://docs.stripe.com/billing/subscriptions/trials) to learn more.
`trial_from_plan`	boolean	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://docs.stripe.com/billing/subscriptions/trials) to learn more.
`trial_period_days`	integer	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://docs.stripe.com/billing/subscriptions/trials) to learn more.
`trial_settings`	object	Settings related to subscription trials.

Responses

HTTP 200: Successful response.

Field	Type	Description
`application`	one of multiple schemas	ID of the Connect Application that created the subscription.
`application_fee_percent`	number	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.
`automatic_tax` required	subscription_automatic_tax
`billing_cycle_anchor` required	integer	The reference point that aligns future [billing cycle](https://docs.stripe.com/subscriptions/billing-cycle) dates. It sets the day of week for `week` intervals, the day of month for `month` and `year` intervals, and the month of year for `year` intervals. The timestamp is in UTC format.
`billing_cycle_anchor_config`	one of multiple schemas	The fixed values used to calculate the `billing_cycle_anchor`.
`billing_mode` required	subscriptions_resource_billing_mode
`billing_schedules` required	array of subscriptions_resource_billing_schedules	Billing schedules for this subscription.
`billing_thresholds`	one of multiple schemas	Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period
`cancel_at`	integer	A date in the future at which the subscription will automatically get canceled
`cancel_at_period_end` required	boolean	Whether this subscription will (if `status=active`) or did (if `status=canceled`) cancel at the end of the current billing period.
`canceled_at`	integer	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.
`cancellation_details`	one of multiple schemas	Details about why this subscription was cancelled
`collection_method` required	string	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`.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	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).
`customer` required	one of multiple schemas	ID of the customer who owns the subscription.
`customer_account`	string	ID of the account representing the customer who owns the subscription.
`days_until_due`	integer	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`.
`default_payment_method`	one of multiple schemas	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_source`	one of multiple schemas	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_tax_rates`	array of tax_rate	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`	string	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.
`discounts` required	array of one of multiple schemas	The discounts applied to the subscription. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount.
`ended_at`	integer	If the subscription has ended, the date the subscription ended.
`id` required	string	Unique identifier for the object.
`invoice_settings` required	subscriptions_resource_subscription_invoice_settings
`items` required	object	List of subscription items, each with an attached price.
`latest_invoice`	one of multiple schemas	The most recent invoice this subscription has generated over its lifecycle (for example, when it cycles or is updated).
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`managed_payments`	one of multiple schemas	Settings for Managed Payments for this Subscription and resulting [Invoices](/api/invoices/object) and [PaymentIntents](/api/payment_intents/object).
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_pending_invoice_item_invoice`	integer	Specifies the approximate timestamp on which any pending invoice items will be billed according to the schedule provided at `pending_invoice_item_interval`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) the charge was made on behalf of for charges associated with this subscription. See the [Connect documentation](https://docs.stripe.com/connect/subscriptions#on-behalf-of) for details.
`pause_collection`	one of multiple schemas	If specified, payment collection for this subscription will be paused. Note that the subscription status will be unchanged and will not be updated to `paused`. Learn more about [pausing collection](https://docs.stripe.com/billing/subscriptions/pause-payment).
`payment_settings`	one of multiple schemas	Payment settings passed on to invoices created by the subscription.
`pending_invoice_item_interval`	one of multiple schemas	Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](/api/invoices/create) for the given subscription at the specified interval.
`pending_setup_intent`	one of multiple schemas	You can use this [SetupIntent](https://docs.stripe.com/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://docs.stripe.com/billing/migration/strong-customer-authentication#scenario-2).
`pending_update`	one of multiple schemas	If specified, [pending updates](https://docs.stripe.com/billing/subscriptions/pending-updates) that will be applied to the subscription once the `latest_invoice` has been paid.
`presentment_details`	subscriptions_resource_subscription_presentment_details
`schedule`	one of multiple schemas	The schedule attached to the subscription
`start_date` required	integer	Date when the subscription was first created. The date might differ from the `created` date due to backdating.
`status` required	string	Possible values are `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `canceled`, `unpaid`, or `paused`. For `collection_method=charge_automatically` a subscription moves into `incomplete` if the initial payment attempt fails. A subscription in this status can only have metadata and default_source updated. Once the first invoice is paid, the subscription moves into an `active` status. If the first invoice is not paid within 23 hours, the subscription transitions to `incomplete_expired`. This is a terminal status, the open invoice will be voided and no further invoices will be generated. A subscription that is currently in a trial period is `trialing` and moves to `active` when the trial period is over. A subscription can only enter a `paused` status [when a trial ends without a payment method](https://docs.stripe.com/billing/subscriptions/trials#create-free-trials-without-payment). A `paused` subscription doesn't generate invoices and can be resumed after your customer adds their payment method. The `paused` status is different from [pausing collection](https://docs.stripe.com/billing/subscriptions/pause-payment), which still generates invoices and leaves the subscription's status unchanged. If 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). If 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.
`test_clock`	one of multiple schemas	ID of the test clock this subscription belongs to.
`transfer_data`	one of multiple schemas	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.
`trial_end`	integer	If the subscription has a trial, the end of that trial.
`trial_settings`	one of multiple schemas	Settings related to subscription trials.
`trial_start`	integer	If the subscription has a trial, the beginning of that trial.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/tax_ids

List all Customer tax IDs

Returns a list of tax IDs for a customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`ending_before`	query	string	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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	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.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of tax_id	Details about each object.
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/tax_ids

Create a Customer tax ID

Creates a new tax_id object for a customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`type` required	string	Type of the tax ID, one of `ad_nrt`, `ae_trn`, `al_tin`, `am_tin`, `ao_tin`, `ar_cuit`, `au_abn`, `au_arn`, `aw_tin`, `az_tin`, `ba_tin`, `bb_tin`, `bd_bin`, `bf_ifu`, `bg_uic`, `bh_vat`, `bj_ifu`, `bo_tin`, `br_cnpj`, `br_cpf`, `bs_tin`, `by_tin`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `cd_nif`, `ch_uid`, `ch_vat`, `cl_tin`, `cm_niu`, `cn_tin`, `co_nit`, `cr_tin`, `cv_nif`, `de_stn`, `do_rcn`, `ec_ruc`, `eg_tin`, `es_cif`, `et_tin`, `eu_oss_vat`, `eu_vat`, `fo_vat`, `gb_vat`, `ge_vat`, `gi_tin`, `gn_nif`, `hk_br`, `hr_oib`, `hu_tin`, `ic_nif`, `id_npwp`, `il_vat`, `in_gst`, `is_vat`, `it_cf`, `jp_cn`, `jp_rn`, `jp_trn`, `ke_pin`, `kg_tin`, `kh_tin`, `kr_brn`, `kz_bin`, `la_tin`, `li_uid`, `li_vat`, `lk_vat`, `ma_vat`, `md_vat`, `me_pib`, `mk_vat`, `mr_nif`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `ng_tin`, `no_vat`, `no_voec`, `np_pan`, `nz_gst`, `om_vat`, `pe_ruc`, `ph_tin`, `pl_nip`, `py_ruc`, `ro_tin`, `rs_pib`, `ru_inn`, `ru_kpp`, `sa_vat`, `sg_gst`, `sg_uen`, `si_tin`, `sn_ninea`, `sr_fin`, `sv_nit`, `th_vat`, `tj_tin`, `tr_tin`, `tw_vat`, `tz_vat`, `ua_vat`, `ug_tin`, `us_ein`, `uy_ruc`, `uz_tin`, `uz_vat`, `ve_rif`, `vn_tin`, `za_vat`, `zm_tin`, or `zw_tin`
`value` required	string	Value of the tax ID.

Responses

HTTP 200: Successful response.

Field	Type	Description
`country`	string	Two-letter ISO code representing the country of the tax ID.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer`	one of multiple schemas	ID of the customer.
`customer_account`	string	ID of the Account representing the customer.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`owner`	one of multiple schemas	The account or customer the tax ID belongs to.
`type` required	string	Type of the tax ID, one of `ad_nrt`, `ae_trn`, `al_tin`, `am_tin`, `ao_tin`, `ar_cuit`, `au_abn`, `au_arn`, `aw_tin`, `az_tin`, `ba_tin`, `bb_tin`, `bd_bin`, `bf_ifu`, `bg_uic`, `bh_vat`, `bj_ifu`, `bo_tin`, `br_cnpj`, `br_cpf`, `bs_tin`, `by_tin`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `cd_nif`, `ch_uid`, `ch_vat`, `cl_tin`, `cm_niu`, `cn_tin`, `co_nit`, `cr_tin`, `cv_nif`, `de_stn`, `do_rcn`, `ec_ruc`, `eg_tin`, `es_cif`, `et_tin`, `eu_oss_vat`, `eu_vat`, `fo_vat`, `gb_vat`, `ge_vat`, `gi_tin`, `gn_nif`, `hk_br`, `hr_oib`, `hu_tin`, `ic_nif`, `id_npwp`, `il_vat`, `in_gst`, `is_vat`, `it_cf`, `jp_cn`, `jp_rn`, `jp_trn`, `ke_pin`, `kg_tin`, `kh_tin`, `kr_brn`, `kz_bin`, `la_tin`, `li_uid`, `li_vat`, `lk_vat`, `ma_vat`, `md_vat`, `me_pib`, `mk_vat`, `mr_nif`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `ng_tin`, `no_vat`, `no_voec`, `np_pan`, `nz_gst`, `om_vat`, `pe_ruc`, `ph_tin`, `pl_nip`, `py_ruc`, `ro_tin`, `rs_pib`, `ru_inn`, `ru_kpp`, `sa_vat`, `sg_gst`, `sg_uen`, `si_tin`, `sn_ninea`, `sr_fin`, `sv_nit`, `th_vat`, `tj_tin`, `tr_tin`, `tw_vat`, `tz_vat`, `ua_vat`, `ug_tin`, `us_ein`, `uy_ruc`, `uz_tin`, `uz_vat`, `ve_rif`, `vn_tin`, `za_vat`, `zm_tin`, or `zw_tin`. Note that some legacy tax IDs have type `unknown`
`value` required	string	Value of the tax ID.
`verification`	one of multiple schemas	Tax ID verification information.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/balance_transactions/{transaction}

Retrieve a customer balance transaction

Retrieves a specific customer balance transaction that updated the customer’s balances.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`transaction`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	The amount of the transaction. A negative value is a credit for the customer's balance, and a positive value is a debit to the customer's `balance`.
`checkout_session`	one of multiple schemas	The ID of the checkout session (if any) that created the transaction.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`credit_note`	one of multiple schemas	The ID of the credit note (if any) related to the transaction.
`currency` required	string	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).
`customer` required	one of multiple schemas	The ID of the customer the transaction belongs to.
`customer_account`	string	The ID of an Account representing a customer that the transaction belongs to.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`ending_balance` required	integer	The customer's `balance` after the transaction was applied. A negative value decreases the amount due on the customer's next invoice. A positive value increases the amount due on the customer's next invoice.
`id` required	string	Unique identifier for the object.
`invoice`	one of multiple schemas	The ID of the invoice (if any) related to the transaction.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`type` required	string	Transaction type: `adjustment`, `applied_to_invoice`, `credit_note`, `initial`, `invoice_overpaid`, `invoice_too_large`, `invoice_too_small`, `unspent_receiver_credit`, `unapplied_from_invoice`, `checkout_session_subscription_payment`, or `checkout_session_subscription_payment_canceled`. See the [Customer Balance page](https://docs.stripe.com/billing/customer/balance#types) to learn more about transaction types.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/balance_transactions/{transaction}

Update a customer credit balance transaction

Most credit balance transaction fields are immutable, but you may update its description and metadata.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`transaction`	path	string

Field	Type	Description
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	The amount of the transaction. A negative value is a credit for the customer's balance, and a positive value is a debit to the customer's `balance`.
`checkout_session`	one of multiple schemas	The ID of the checkout session (if any) that created the transaction.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`credit_note`	one of multiple schemas	The ID of the credit note (if any) related to the transaction.
`currency` required	string	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).
`customer` required	one of multiple schemas	The ID of the customer the transaction belongs to.
`customer_account`	string	The ID of an Account representing a customer that the transaction belongs to.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`ending_balance` required	integer	The customer's `balance` after the transaction was applied. A negative value decreases the amount due on the customer's next invoice. A positive value increases the amount due on the customer's next invoice.
`id` required	string	Unique identifier for the object.
`invoice`	one of multiple schemas	The ID of the invoice (if any) related to the transaction.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`type` required	string	Transaction type: `adjustment`, `applied_to_invoice`, `credit_note`, `initial`, `invoice_overpaid`, `invoice_too_large`, `invoice_too_small`, `unspent_receiver_credit`, `unapplied_from_invoice`, `checkout_session_subscription_payment`, or `checkout_session_subscription_payment_canceled`. See the [Customer Balance page](https://docs.stripe.com/billing/customer/balance#types) to learn more about transaction types.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

DELETE /v1/customers/{customer}/bank_accounts/{id}

Delete a customer source

Delete a specified source for a given customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`id`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

one of multiple schemas. See the OpenAPI specification for the complete schema.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/bank_accounts/{id}

Retrieve a bank account

By default, you can see the 10 most recent sources stored on a Customer directly on the object, but you can also retrieve details about a specific bank account stored on the Stripe account.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`id`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account`	one of multiple schemas	The account this bank account belongs to. Only applicable on Accounts (not customers or recipients) This property is only available when returned as an [External Account](/api/external_account_bank_accounts/object) where [controller.is_controller](/api/accounts/object#account_object-controller-is_controller) is `true`.
`account_holder_name`	string	The name of the person or business that owns the bank account.
`account_holder_type`	string	The type of entity that holds the account. This can be either `individual` or `company`.
`account_type`	string	The bank account type. This can only be `checking` or `savings` in most countries. In Japan, this can only be `futsu` or `toza`.
`available_payout_methods`	array of string	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.
`bank_name`	string	Name of the bank associated with the routing number (e.g., `WELLS FARGO`).
`country` required	string	Two-letter ISO code representing the country the bank account is located in.
`currency` required	string	Three-letter [ISO code for the currency](https://stripe.com/docs/payouts) paid out to the bank account.
`customer`	one of multiple schemas	The ID of the customer that the bank account is associated with.
`default_for_currency`	boolean	Whether this bank account is the default external account for its currency.
`fingerprint`	string	Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.
`future_requirements`	one of multiple schemas	Information about the [upcoming new requirements for the bank account](https://docs.stripe.com/connect/custom-accounts/future-requirements), including what information needs to be collected, and by when.
`id` required	string	Unique identifier for the object.
`last4` required	string	The last four digits of the bank account number.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`requirements`	one of multiple schemas	Information about the requirements for the bank account, including what information needs to be collected.
`routing_number`	string	The routing transit number for the bank account.
`status` required	string	For bank accounts, possible values are `new`, `validated`, `verified`, `verification_failed`, `tokenized_account_number_deactivated` 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 the status is `tokenized_account_number_deactivated`, the account utilizes a tokenized account number which has been deactivated due to expiration or revocation. This account will need to be reverified to continue using it for money movement. 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`, `verification_failed`, and `tokenized_account_number_deactivated`. If a payout fails, the status is set to `errored` and scheduled payouts are stopped until account details are updated. In the US and 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.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/bank_accounts/{id}

Update a card

Update a specified source for a given customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`id`	path	string

Field	Type	Description
`account_holder_name`	string	The name of the person or business that owns the bank account.
`account_holder_type`	string	The type of entity that holds the account. This can be either `individual` or `company`.
`address_city`	string	City/District/Suburb/Town/Village.
`address_country`	string	Billing address country, if provided when creating card.
`address_line1`	string	Address line 1 (Street address/PO Box/Company name).
`address_line2`	string	Address line 2 (Apartment/Suite/Unit/Building).
`address_state`	string	State/County/Province/Region.
`address_zip`	string	ZIP or postal code.
`exp_month`	string	Two digit number representing the card’s expiration month.
`exp_year`	string	Four digit number representing the card’s expiration year.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.
`name`	string	Cardholder name.
`owner`	object

Responses

HTTP 200: Successful response.

one of multiple schemas. See the OpenAPI specification for the complete schema.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/bank_accounts/{id}/verify

Verify a bank account

Verify a specified bank account for a given customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`id`	path	string

Field	Type	Description
`amounts`	array of integer	Two positive integers, in cents, equal to the values of the microdeposits sent to the bank account.
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account`	one of multiple schemas	The account this bank account belongs to. Only applicable on Accounts (not customers or recipients) This property is only available when returned as an [External Account](/api/external_account_bank_accounts/object) where [controller.is_controller](/api/accounts/object#account_object-controller-is_controller) is `true`.
`account_holder_name`	string	The name of the person or business that owns the bank account.
`account_holder_type`	string	The type of entity that holds the account. This can be either `individual` or `company`.
`account_type`	string	The bank account type. This can only be `checking` or `savings` in most countries. In Japan, this can only be `futsu` or `toza`.
`available_payout_methods`	array of string	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.
`bank_name`	string	Name of the bank associated with the routing number (e.g., `WELLS FARGO`).
`country` required	string	Two-letter ISO code representing the country the bank account is located in.
`currency` required	string	Three-letter [ISO code for the currency](https://stripe.com/docs/payouts) paid out to the bank account.
`customer`	one of multiple schemas	The ID of the customer that the bank account is associated with.
`default_for_currency`	boolean	Whether this bank account is the default external account for its currency.
`fingerprint`	string	Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.
`future_requirements`	one of multiple schemas	Information about the [upcoming new requirements for the bank account](https://docs.stripe.com/connect/custom-accounts/future-requirements), including what information needs to be collected, and by when.
`id` required	string	Unique identifier for the object.
`last4` required	string	The last four digits of the bank account number.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`requirements`	one of multiple schemas	Information about the requirements for the bank account, including what information needs to be collected.
`routing_number`	string	The routing transit number for the bank account.
`status` required	string	For bank accounts, possible values are `new`, `validated`, `verified`, `verification_failed`, `tokenized_account_number_deactivated` 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 the status is `tokenized_account_number_deactivated`, the account utilizes a tokenized account number which has been deactivated due to expiration or revocation. This account will need to be reverified to continue using it for money movement. 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`, `verification_failed`, and `tokenized_account_number_deactivated`. If a payout fails, the status is set to `errored` and scheduled payouts are stopped until account details are updated. In the US and 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.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

DELETE /v1/customers/{customer}/cards/{id}

Delete a customer source

Delete a specified source for a given customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`id`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

one of multiple schemas. See the OpenAPI specification for the complete schema.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/cards/{id}

Retrieve a card

You can always see the 10 most recent cards directly on a customer; this method lets you retrieve details about a specific card stored on the customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`id`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account`	one of multiple schemas
`address_city`	string	City/District/Suburb/Town/Village.
`address_country`	string	Billing address country, if provided when creating card.
`address_line1`	string	Address line 1 (Street address/PO Box/Company name).
`address_line1_check`	string	If `address_line1` was provided, results of the check: `pass`, `fail`, `unavailable`, or `unchecked`.
`address_line2`	string	Address line 2 (Apartment/Suite/Unit/Building).
`address_state`	string	State/County/Province/Region.
`address_zip`	string	ZIP or postal code.
`address_zip_check`	string	If `address_zip` was provided, results of the check: `pass`, `fail`, `unavailable`, or `unchecked`.
`allow_redisplay`	string	This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to “unspecified”.
`available_payout_methods`	array of string	A set of available payout methods for this card. Only values from this set should be passed as the `method` when creating a payout.
`brand` required	string	Card brand. Can be `American Express`, `Cartes Bancaires`, `Diners Club`, `Discover`, `Eftpos Australia`, `Girocard`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`.
`country`	string	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.
`currency`	string	Three-letter [ISO code for currency](https://www.iso.org/iso-4217-currency-codes.html) in lowercase. Must be a [supported currency](https://docs.stripe.com/currencies). Only applicable on accounts (not customers or recipients). The card can be used as a transfer destination for funds in this currency. This property is only available when returned as an [External Account](/api/external_account_cards/object) where [controller.is_controller](/api/accounts/object#account_object-controller-is_controller) is `true`.
`customer`	one of multiple schemas	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.
`cvc_check`	string	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).
`default_for_currency`	boolean	Whether this card is the default external account for its currency. This property is only available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts.
`dynamic_last4`	string	(For tokenized numbers only.) The last four digits of the device account number.
`exp_month` required	integer	Two-digit number representing the card's expiration month.
`exp_year` required	integer	Four-digit number representing the card's expiration year.
`fingerprint`	string	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 card---one for India and one for the rest of the world.
`funding` required	string	Card funding type. Can be `credit`, `debit`, `prepaid`, or `unknown`.
`id` required	string	Unique identifier for the object.
`last4` required	string	The last four digits of the card.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`name`	string	Cardholder name.
`networks`	token_card_networks
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`regulated_status`	string	Status of a card based on the card issuer.
`status`	string	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.
`tokenization_method`	string	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.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/cards/{id}

Update a card

Update a specified source for a given customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`id`	path	string

Field	Type	Description
`account_holder_name`	string	The name of the person or business that owns the bank account.
`account_holder_type`	string	The type of entity that holds the account. This can be either `individual` or `company`.
`address_city`	string	City/District/Suburb/Town/Village.
`address_country`	string	Billing address country, if provided when creating card.
`address_line1`	string	Address line 1 (Street address/PO Box/Company name).
`address_line2`	string	Address line 2 (Apartment/Suite/Unit/Building).
`address_state`	string	State/County/Province/Region.
`address_zip`	string	ZIP or postal code.
`exp_month`	string	Two digit number representing the card’s expiration month.
`exp_year`	string	Four digit number representing the card’s expiration year.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.
`name`	string	Cardholder name.
`owner`	object

Responses

HTTP 200: Successful response.

one of multiple schemas. See the OpenAPI specification for the complete schema.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/cash_balance_transactions/{transaction}

Retrieve a cash balance transaction

Retrieves a specific cash balance transaction, which updated the customer’s cash balance.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`transaction`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`adjusted_for_overdraft`	customer_balance_resource_cash_balance_transaction_resource_adjusted_for_overdraft
`applied_to_payment`	customer_balance_resource_cash_balance_transaction_resource_applied_to_payment_transaction
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	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).
`customer` required	one of multiple schemas	The customer whose available cash balance changed as a result of this transaction.
`customer_account`	string	The ID of an Account representing a customer whose available cash balance changed as a result of this transaction.
`ending_balance` required	integer	The total available cash balance for the specified currency after this transaction was applied. Represented in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal).
`funded`	customer_balance_resource_cash_balance_transaction_resource_funded_transaction
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`net_amount` required	integer	The amount by which the cash balance changed, represented in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal). A positive value represents funds being added to the cash balance, a negative value represents funds being removed from the cash balance.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`refunded_from_payment`	customer_balance_resource_cash_balance_transaction_resource_refunded_from_payment_transaction
`transferred_to_balance`	customer_balance_resource_cash_balance_transaction_resource_transferred_to_balance
`type` required	string	The type of the cash balance transaction. New types may be added in future. See [Customer Balance](https://docs.stripe.com/payments/customer-balance#types) to learn more about these types.
`unapplied_from_payment`	customer_balance_resource_cash_balance_transaction_resource_unapplied_from_payment_transaction

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/payment_methods/{payment_method}

Retrieve a Customer's PaymentMethod

Retrieves a PaymentMethod object for a given Customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`payment_method`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`acss_debit`	payment_method_acss_debit
`affirm`	payment_method_affirm
`afterpay_clearpay`	payment_method_afterpay_clearpay
`alipay`	payment_flows_private_payment_methods_alipay
`allow_redisplay`	string	This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to “unspecified”.
`alma`	payment_method_alma
`amazon_pay`	payment_method_amazon_pay
`au_becs_debit`	payment_method_au_becs_debit
`bacs_debit`	payment_method_bacs_debit
`bancontact`	payment_method_bancontact
`billie`	payment_method_billie
`billing_details` required	billing_details
`bizum`	payment_method_bizum
`blik`	payment_method_blik
`boleto`	payment_method_boleto
`card`	payment_method_card
`card_present`	payment_method_card_present
`cashapp`	payment_method_cashapp
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`crypto`	payment_method_crypto
`custom`	payment_method_custom
`customer`	one of multiple schemas	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.
`customer_account`	string
`customer_balance`	payment_method_customer_balance
`eps`	payment_method_eps
`fpx`	payment_method_fpx
`giropay`	payment_method_giropay
`grabpay`	payment_method_grabpay
`id` required	string	Unique identifier for the object.
`ideal`	payment_method_ideal
`interac_present`	payment_method_interac_present
`kakao_pay`	payment_method_kakao_pay
`klarna`	payment_method_klarna
`konbini`	payment_method_konbini
`kr_card`	payment_method_kr_card
`link`	payment_method_link
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`mb_way`	payment_method_mb_way
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`mobilepay`	payment_method_mobilepay
`multibanco`	payment_method_multibanco
`naver_pay`	payment_method_naver_pay
`nz_bank_account`	payment_method_nz_bank_account
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`oxxo`	payment_method_oxxo
`p24`	payment_method_p24
`pay_by_bank`	payment_method_pay_by_bank
`payco`	payment_method_payco
`paynow`	payment_method_paynow
`paypal`	payment_method_paypal
`payto`	payment_method_payto
`pix`	payment_method_pix
`promptpay`	payment_method_promptpay
`radar_options`	radar_radar_options
`revolut_pay`	payment_method_revolut_pay
`samsung_pay`	payment_method_samsung_pay
`satispay`	payment_method_satispay
`scalapay`	payment_method_scalapay
`sepa_debit`	payment_method_sepa_debit
`sofort`	payment_method_sofort
`sunbit`	payment_method_sunbit
`swish`	payment_method_swish
`twint`	payment_method_twint
`type` required	string	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.
`upi`	payment_method_upi
`us_bank_account`	payment_method_us_bank_account
`wechat_pay`	payment_method_wechat_pay
`zip`	payment_method_zip

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

DELETE /v1/customers/{customer}/sources/{id}

Delete a customer source

Delete a specified source for a given customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`id`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

one of multiple schemas. See the OpenAPI specification for the complete schema.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/sources/{id}

/v1/customers/{customer}/sources/{id}

Retrieve a specified source for a given customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`id`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

one of multiple schemas. See the OpenAPI specification for the complete schema.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/sources/{id}

Update a card

Update a specified source for a given customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`id`	path	string

Field	Type	Description
`account_holder_name`	string	The name of the person or business that owns the bank account.
`account_holder_type`	string	The type of entity that holds the account. This can be either `individual` or `company`.
`address_city`	string	City/District/Suburb/Town/Village.
`address_country`	string	Billing address country, if provided when creating card.
`address_line1`	string	Address line 1 (Street address/PO Box/Company name).
`address_line2`	string	Address line 2 (Apartment/Suite/Unit/Building).
`address_state`	string	State/County/Province/Region.
`address_zip`	string	ZIP or postal code.
`exp_month`	string	Two digit number representing the card’s expiration month.
`exp_year`	string	Four digit number representing the card’s expiration year.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.
`name`	string	Cardholder name.
`owner`	object

Responses

HTTP 200: Successful response.

one of multiple schemas. See the OpenAPI specification for the complete schema.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/sources/{id}/verify

Verify a bank account

Verify a specified bank account for a given customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`id`	path	string

Field	Type	Description
`amounts`	array of integer	Two positive integers, in cents, equal to the values of the microdeposits sent to the bank account.
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account`	one of multiple schemas	The account this bank account belongs to. Only applicable on Accounts (not customers or recipients) This property is only available when returned as an [External Account](/api/external_account_bank_accounts/object) where [controller.is_controller](/api/accounts/object#account_object-controller-is_controller) is `true`.
`account_holder_name`	string	The name of the person or business that owns the bank account.
`account_holder_type`	string	The type of entity that holds the account. This can be either `individual` or `company`.
`account_type`	string	The bank account type. This can only be `checking` or `savings` in most countries. In Japan, this can only be `futsu` or `toza`.
`available_payout_methods`	array of string	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.
`bank_name`	string	Name of the bank associated with the routing number (e.g., `WELLS FARGO`).
`country` required	string	Two-letter ISO code representing the country the bank account is located in.
`currency` required	string	Three-letter [ISO code for the currency](https://stripe.com/docs/payouts) paid out to the bank account.
`customer`	one of multiple schemas	The ID of the customer that the bank account is associated with.
`default_for_currency`	boolean	Whether this bank account is the default external account for its currency.
`fingerprint`	string	Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.
`future_requirements`	one of multiple schemas	Information about the [upcoming new requirements for the bank account](https://docs.stripe.com/connect/custom-accounts/future-requirements), including what information needs to be collected, and by when.
`id` required	string	Unique identifier for the object.
`last4` required	string	The last four digits of the bank account number.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`requirements`	one of multiple schemas	Information about the requirements for the bank account, including what information needs to be collected.
`routing_number`	string	The routing transit number for the bank account.
`status` required	string	For bank accounts, possible values are `new`, `validated`, `verified`, `verification_failed`, `tokenized_account_number_deactivated` 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 the status is `tokenized_account_number_deactivated`, the account utilizes a tokenized account number which has been deactivated due to expiration or revocation. This account will need to be reverified to continue using it for money movement. 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`, `verification_failed`, and `tokenized_account_number_deactivated`. If a payout fails, the status is set to `errored` and scheduled payouts are stopped until account details are updated. In the US and 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.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

DELETE /v1/customers/{customer}/subscriptions/{subscription_exposed_id}

Cancel a subscription

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.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`subscription_exposed_id`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`invoice_now`	boolean	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.
`prorate`	boolean	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.

Responses

HTTP 200: Successful response.

Field	Type	Description
`application`	one of multiple schemas	ID of the Connect Application that created the subscription.
`application_fee_percent`	number	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.
`automatic_tax` required	subscription_automatic_tax
`billing_cycle_anchor` required	integer	The reference point that aligns future [billing cycle](https://docs.stripe.com/subscriptions/billing-cycle) dates. It sets the day of week for `week` intervals, the day of month for `month` and `year` intervals, and the month of year for `year` intervals. The timestamp is in UTC format.
`billing_cycle_anchor_config`	one of multiple schemas	The fixed values used to calculate the `billing_cycle_anchor`.
`billing_mode` required	subscriptions_resource_billing_mode
`billing_schedules` required	array of subscriptions_resource_billing_schedules	Billing schedules for this subscription.
`billing_thresholds`	one of multiple schemas	Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period
`cancel_at`	integer	A date in the future at which the subscription will automatically get canceled
`cancel_at_period_end` required	boolean	Whether this subscription will (if `status=active`) or did (if `status=canceled`) cancel at the end of the current billing period.
`canceled_at`	integer	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.
`cancellation_details`	one of multiple schemas	Details about why this subscription was cancelled
`collection_method` required	string	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`.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	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).
`customer` required	one of multiple schemas	ID of the customer who owns the subscription.
`customer_account`	string	ID of the account representing the customer who owns the subscription.
`days_until_due`	integer	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`.
`default_payment_method`	one of multiple schemas	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_source`	one of multiple schemas	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_tax_rates`	array of tax_rate	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`	string	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.
`discounts` required	array of one of multiple schemas	The discounts applied to the subscription. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount.
`ended_at`	integer	If the subscription has ended, the date the subscription ended.
`id` required	string	Unique identifier for the object.
`invoice_settings` required	subscriptions_resource_subscription_invoice_settings
`items` required	object	List of subscription items, each with an attached price.
`latest_invoice`	one of multiple schemas	The most recent invoice this subscription has generated over its lifecycle (for example, when it cycles or is updated).
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`managed_payments`	one of multiple schemas	Settings for Managed Payments for this Subscription and resulting [Invoices](/api/invoices/object) and [PaymentIntents](/api/payment_intents/object).
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_pending_invoice_item_invoice`	integer	Specifies the approximate timestamp on which any pending invoice items will be billed according to the schedule provided at `pending_invoice_item_interval`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) the charge was made on behalf of for charges associated with this subscription. See the [Connect documentation](https://docs.stripe.com/connect/subscriptions#on-behalf-of) for details.
`pause_collection`	one of multiple schemas	If specified, payment collection for this subscription will be paused. Note that the subscription status will be unchanged and will not be updated to `paused`. Learn more about [pausing collection](https://docs.stripe.com/billing/subscriptions/pause-payment).
`payment_settings`	one of multiple schemas	Payment settings passed on to invoices created by the subscription.
`pending_invoice_item_interval`	one of multiple schemas	Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](/api/invoices/create) for the given subscription at the specified interval.
`pending_setup_intent`	one of multiple schemas	You can use this [SetupIntent](https://docs.stripe.com/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://docs.stripe.com/billing/migration/strong-customer-authentication#scenario-2).
`pending_update`	one of multiple schemas	If specified, [pending updates](https://docs.stripe.com/billing/subscriptions/pending-updates) that will be applied to the subscription once the `latest_invoice` has been paid.
`presentment_details`	subscriptions_resource_subscription_presentment_details
`schedule`	one of multiple schemas	The schedule attached to the subscription
`start_date` required	integer	Date when the subscription was first created. The date might differ from the `created` date due to backdating.
`status` required	string	Possible values are `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `canceled`, `unpaid`, or `paused`. For `collection_method=charge_automatically` a subscription moves into `incomplete` if the initial payment attempt fails. A subscription in this status can only have metadata and default_source updated. Once the first invoice is paid, the subscription moves into an `active` status. If the first invoice is not paid within 23 hours, the subscription transitions to `incomplete_expired`. This is a terminal status, the open invoice will be voided and no further invoices will be generated. A subscription that is currently in a trial period is `trialing` and moves to `active` when the trial period is over. A subscription can only enter a `paused` status [when a trial ends without a payment method](https://docs.stripe.com/billing/subscriptions/trials#create-free-trials-without-payment). A `paused` subscription doesn't generate invoices and can be resumed after your customer adds their payment method. The `paused` status is different from [pausing collection](https://docs.stripe.com/billing/subscriptions/pause-payment), which still generates invoices and leaves the subscription's status unchanged. If 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). If 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.
`test_clock`	one of multiple schemas	ID of the test clock this subscription belongs to.
`transfer_data`	one of multiple schemas	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.
`trial_end`	integer	If the subscription has a trial, the end of that trial.
`trial_settings`	one of multiple schemas	Settings related to subscription trials.
`trial_start`	integer	If the subscription has a trial, the beginning of that trial.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/subscriptions/{subscription_exposed_id}

Retrieve a subscription

Retrieves the subscription with the given ID.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`subscription_exposed_id`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`application`	one of multiple schemas	ID of the Connect Application that created the subscription.
`application_fee_percent`	number	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.
`automatic_tax` required	subscription_automatic_tax
`billing_cycle_anchor` required	integer	The reference point that aligns future [billing cycle](https://docs.stripe.com/subscriptions/billing-cycle) dates. It sets the day of week for `week` intervals, the day of month for `month` and `year` intervals, and the month of year for `year` intervals. The timestamp is in UTC format.
`billing_cycle_anchor_config`	one of multiple schemas	The fixed values used to calculate the `billing_cycle_anchor`.
`billing_mode` required	subscriptions_resource_billing_mode
`billing_schedules` required	array of subscriptions_resource_billing_schedules	Billing schedules for this subscription.
`billing_thresholds`	one of multiple schemas	Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period
`cancel_at`	integer	A date in the future at which the subscription will automatically get canceled
`cancel_at_period_end` required	boolean	Whether this subscription will (if `status=active`) or did (if `status=canceled`) cancel at the end of the current billing period.
`canceled_at`	integer	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.
`cancellation_details`	one of multiple schemas	Details about why this subscription was cancelled
`collection_method` required	string	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`.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	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).
`customer` required	one of multiple schemas	ID of the customer who owns the subscription.
`customer_account`	string	ID of the account representing the customer who owns the subscription.
`days_until_due`	integer	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`.
`default_payment_method`	one of multiple schemas	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_source`	one of multiple schemas	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_tax_rates`	array of tax_rate	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`	string	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.
`discounts` required	array of one of multiple schemas	The discounts applied to the subscription. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount.
`ended_at`	integer	If the subscription has ended, the date the subscription ended.
`id` required	string	Unique identifier for the object.
`invoice_settings` required	subscriptions_resource_subscription_invoice_settings
`items` required	object	List of subscription items, each with an attached price.
`latest_invoice`	one of multiple schemas	The most recent invoice this subscription has generated over its lifecycle (for example, when it cycles or is updated).
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`managed_payments`	one of multiple schemas	Settings for Managed Payments for this Subscription and resulting [Invoices](/api/invoices/object) and [PaymentIntents](/api/payment_intents/object).
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_pending_invoice_item_invoice`	integer	Specifies the approximate timestamp on which any pending invoice items will be billed according to the schedule provided at `pending_invoice_item_interval`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) the charge was made on behalf of for charges associated with this subscription. See the [Connect documentation](https://docs.stripe.com/connect/subscriptions#on-behalf-of) for details.
`pause_collection`	one of multiple schemas	If specified, payment collection for this subscription will be paused. Note that the subscription status will be unchanged and will not be updated to `paused`. Learn more about [pausing collection](https://docs.stripe.com/billing/subscriptions/pause-payment).
`payment_settings`	one of multiple schemas	Payment settings passed on to invoices created by the subscription.
`pending_invoice_item_interval`	one of multiple schemas	Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](/api/invoices/create) for the given subscription at the specified interval.
`pending_setup_intent`	one of multiple schemas	You can use this [SetupIntent](https://docs.stripe.com/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://docs.stripe.com/billing/migration/strong-customer-authentication#scenario-2).
`pending_update`	one of multiple schemas	If specified, [pending updates](https://docs.stripe.com/billing/subscriptions/pending-updates) that will be applied to the subscription once the `latest_invoice` has been paid.
`presentment_details`	subscriptions_resource_subscription_presentment_details
`schedule`	one of multiple schemas	The schedule attached to the subscription
`start_date` required	integer	Date when the subscription was first created. The date might differ from the `created` date due to backdating.
`status` required	string	Possible values are `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `canceled`, `unpaid`, or `paused`. For `collection_method=charge_automatically` a subscription moves into `incomplete` if the initial payment attempt fails. A subscription in this status can only have metadata and default_source updated. Once the first invoice is paid, the subscription moves into an `active` status. If the first invoice is not paid within 23 hours, the subscription transitions to `incomplete_expired`. This is a terminal status, the open invoice will be voided and no further invoices will be generated. A subscription that is currently in a trial period is `trialing` and moves to `active` when the trial period is over. A subscription can only enter a `paused` status [when a trial ends without a payment method](https://docs.stripe.com/billing/subscriptions/trials#create-free-trials-without-payment). A `paused` subscription doesn't generate invoices and can be resumed after your customer adds their payment method. The `paused` status is different from [pausing collection](https://docs.stripe.com/billing/subscriptions/pause-payment), which still generates invoices and leaves the subscription's status unchanged. If 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). If 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.
`test_clock`	one of multiple schemas	ID of the test clock this subscription belongs to.
`transfer_data`	one of multiple schemas	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.
`trial_end`	integer	If the subscription has a trial, the end of that trial.
`trial_settings`	one of multiple schemas	Settings related to subscription trials.
`trial_start`	integer	If the subscription has a trial, the beginning of that trial.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/customers/{customer}/subscriptions/{subscription_exposed_id}

Update a subscription on a customer

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.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`subscription_exposed_id`	path	string

Field	Type	Description
`add_invoice_items`	array of object	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.
`application_fee_percent`	one of multiple schemas	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).
`automatic_tax`	object	Automatic tax settings for this subscription. We recommend you only include this parameter when the existing value is being changed.
`billing_cycle_anchor`	string	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://docs.stripe.com/billing/subscriptions/billing-cycle).
`billing_thresholds`	one of multiple schemas	Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds.
`cancel_at`	one of multiple schemas	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`	boolean	Indicate whether this subscription should cancel at the end of the current period (`current_period_end`).
`cancellation_details`	object	Details about why this subscription was cancelled
`collection_method`	string	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`.
`days_until_due`	integer	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`.
`default_payment_method`	string	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_source`	one of multiple schemas	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_tax_rates`	one of multiple schemas	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.
`discounts`	one of multiple schemas	The coupons to redeem into discounts for the subscription. A populated array overwrites the existing discounts on the subscription. If not specified or empty array, it leaves the subscription's discounts unchanged. If empty string, it clears the subscription's discounts.
`expand`	array of string	Specifies which fields in the response should be expanded.
`invoice_settings`	object	All invoices will be billed using the specified settings.
`items`	array of object	A list of up to 20 subscription items, each with an attached price.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`	boolean	Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `false` (on-session).
`pause_collection`	one of multiple schemas	If specified, payment collection for this subscription will be paused. Note that the subscription status will be unchanged and will not be updated to `paused`. Learn more about [pausing collection](https://docs.stripe.com/billing/subscriptions/pause-payment).
`payment_behavior`	string	Controls how Stripe handles payment when a subscription update requires payment and `collection_method=charge_automatically`.
`payment_settings`	object	Payment settings to pass to invoices created by the subscription.
`pending_invoice_item_interval`	one of multiple schemas	Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](/api/invoices/create) for the given subscription at the specified interval.
`proration_behavior`	string	Determines how to handle [prorations](https://docs.stripe.com/billing/subscriptions/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`.
`proration_date`	integer	If set, prorations will be calculated as though the subscription was updated at the given time. This can be used to apply exactly the same prorations that were previewed with the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint. `proration_date` 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.
`transfer_data`	one of multiple schemas	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`	one of multiple schemas	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`	boolean	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://docs.stripe.com/billing/subscriptions/trials) to learn more.
`trial_settings`	object	Settings related to subscription trials.

Responses

HTTP 200: Successful response.

Field	Type	Description
`application`	one of multiple schemas	ID of the Connect Application that created the subscription.
`application_fee_percent`	number	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.
`automatic_tax` required	subscription_automatic_tax
`billing_cycle_anchor` required	integer	The reference point that aligns future [billing cycle](https://docs.stripe.com/subscriptions/billing-cycle) dates. It sets the day of week for `week` intervals, the day of month for `month` and `year` intervals, and the month of year for `year` intervals. The timestamp is in UTC format.
`billing_cycle_anchor_config`	one of multiple schemas	The fixed values used to calculate the `billing_cycle_anchor`.
`billing_mode` required	subscriptions_resource_billing_mode
`billing_schedules` required	array of subscriptions_resource_billing_schedules	Billing schedules for this subscription.
`billing_thresholds`	one of multiple schemas	Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period
`cancel_at`	integer	A date in the future at which the subscription will automatically get canceled
`cancel_at_period_end` required	boolean	Whether this subscription will (if `status=active`) or did (if `status=canceled`) cancel at the end of the current billing period.
`canceled_at`	integer	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.
`cancellation_details`	one of multiple schemas	Details about why this subscription was cancelled
`collection_method` required	string	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`.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	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).
`customer` required	one of multiple schemas	ID of the customer who owns the subscription.
`customer_account`	string	ID of the account representing the customer who owns the subscription.
`days_until_due`	integer	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`.
`default_payment_method`	one of multiple schemas	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_source`	one of multiple schemas	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://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
`default_tax_rates`	array of tax_rate	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`	string	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.
`discounts` required	array of one of multiple schemas	The discounts applied to the subscription. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount.
`ended_at`	integer	If the subscription has ended, the date the subscription ended.
`id` required	string	Unique identifier for the object.
`invoice_settings` required	subscriptions_resource_subscription_invoice_settings
`items` required	object	List of subscription items, each with an attached price.
`latest_invoice`	one of multiple schemas	The most recent invoice this subscription has generated over its lifecycle (for example, when it cycles or is updated).
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`managed_payments`	one of multiple schemas	Settings for Managed Payments for this Subscription and resulting [Invoices](/api/invoices/object) and [PaymentIntents](/api/payment_intents/object).
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_pending_invoice_item_invoice`	integer	Specifies the approximate timestamp on which any pending invoice items will be billed according to the schedule provided at `pending_invoice_item_interval`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) the charge was made on behalf of for charges associated with this subscription. See the [Connect documentation](https://docs.stripe.com/connect/subscriptions#on-behalf-of) for details.
`pause_collection`	one of multiple schemas	If specified, payment collection for this subscription will be paused. Note that the subscription status will be unchanged and will not be updated to `paused`. Learn more about [pausing collection](https://docs.stripe.com/billing/subscriptions/pause-payment).
`payment_settings`	one of multiple schemas	Payment settings passed on to invoices created by the subscription.
`pending_invoice_item_interval`	one of multiple schemas	Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](/api/invoices/create) for the given subscription at the specified interval.
`pending_setup_intent`	one of multiple schemas	You can use this [SetupIntent](https://docs.stripe.com/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://docs.stripe.com/billing/migration/strong-customer-authentication#scenario-2).
`pending_update`	one of multiple schemas	If specified, [pending updates](https://docs.stripe.com/billing/subscriptions/pending-updates) that will be applied to the subscription once the `latest_invoice` has been paid.
`presentment_details`	subscriptions_resource_subscription_presentment_details
`schedule`	one of multiple schemas	The schedule attached to the subscription
`start_date` required	integer	Date when the subscription was first created. The date might differ from the `created` date due to backdating.
`status` required	string	Possible values are `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `canceled`, `unpaid`, or `paused`. For `collection_method=charge_automatically` a subscription moves into `incomplete` if the initial payment attempt fails. A subscription in this status can only have metadata and default_source updated. Once the first invoice is paid, the subscription moves into an `active` status. If the first invoice is not paid within 23 hours, the subscription transitions to `incomplete_expired`. This is a terminal status, the open invoice will be voided and no further invoices will be generated. A subscription that is currently in a trial period is `trialing` and moves to `active` when the trial period is over. A subscription can only enter a `paused` status [when a trial ends without a payment method](https://docs.stripe.com/billing/subscriptions/trials#create-free-trials-without-payment). A `paused` subscription doesn't generate invoices and can be resumed after your customer adds their payment method. The `paused` status is different from [pausing collection](https://docs.stripe.com/billing/subscriptions/pause-payment), which still generates invoices and leaves the subscription's status unchanged. If 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). If 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.
`test_clock`	one of multiple schemas	ID of the test clock this subscription belongs to.
`transfer_data`	one of multiple schemas	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.
`trial_end`	integer	If the subscription has a trial, the end of that trial.
`trial_settings`	one of multiple schemas	Settings related to subscription trials.
`trial_start`	integer	If the subscription has a trial, the beginning of that trial.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

DELETE /v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount

Delete a customer discount

Removes the currently applied discount on a customer.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`subscription_exposed_id`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`checkout_session`	string	The Checkout session that this coupon is applied to, if it is applied to a particular session in payment mode. Not present for subscription mode.
`customer`	one of multiple schemas	The ID of the customer associated with this discount.
`customer_account`	string	The ID of the account representing the customer associated with this discount.
`deleted` required	boolean	Always true for a deleted object
`id` required	string	The ID of the discount object. Discounts can't be fetched by ID. Use `expand[]=discounts` in API calls to expand discount IDs in an array.
`invoice`	string	The invoice that the discount's coupon was applied to, if it was applied directly to a particular invoice.
`invoice_item`	string	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`promotion_code`	one of multiple schemas	The promotion code applied to create this discount.
`source` required	discount_source
`start` required	integer	Date that the coupon was applied.
`subscription`	string	The subscription that this coupon is applied to, if it is applied to a particular subscription.
`subscription_item`	string	The subscription item that this coupon is applied to, if it is applied to a particular subscription item.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount

/v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`subscription_exposed_id`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`checkout_session`	string	The Checkout session that this coupon is applied to, if it is applied to a particular session in payment mode. Not present for subscription mode.
`customer`	one of multiple schemas	The ID of the customer associated with this discount.
`customer_account`	string	The ID of the account representing the customer associated with this discount.
`end`	integer	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.
`id` required	string	The ID of the discount object. Discounts can't be fetched by ID. Use `expand[]=discounts` in API calls to expand discount IDs in an array.
`invoice`	string	The invoice that the discount's coupon was applied to, if it was applied directly to a particular invoice.
`invoice_item`	string	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`promotion_code`	one of multiple schemas	The promotion code applied to create this discount.
`source` required	discount_source
`start` required	integer	Date that the coupon was applied.
`subscription`	string	The subscription that this coupon is applied to, if it is applied to a particular subscription.
`subscription_item`	string	The subscription item that this coupon is applied to, if it is applied to a particular subscription item.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

DELETE /v1/customers/{customer}/tax_ids/{id}

Delete a Customer tax ID

Deletes an existing tax_id object.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`id`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`deleted` required	boolean	Always true for a deleted object
`id` required	string	Unique identifier for the object.
`object` required	string	String representing the object's type. Objects of the same type share the same value.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/customers/{customer}/tax_ids/{id}

Retrieve a Customer tax ID

Retrieves the tax_id object with the given identifier.

Request parameters

Parameter	Location	Type	Description
`customer`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`id`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`country`	string	Two-letter ISO code representing the country of the tax ID.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer`	one of multiple schemas	ID of the customer.
`customer_account`	string	ID of the Account representing the customer.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`owner`	one of multiple schemas	The account or customer the tax ID belongs to.
`type` required	string	Type of the tax ID, one of `ad_nrt`, `ae_trn`, `al_tin`, `am_tin`, `ao_tin`, `ar_cuit`, `au_abn`, `au_arn`, `aw_tin`, `az_tin`, `ba_tin`, `bb_tin`, `bd_bin`, `bf_ifu`, `bg_uic`, `bh_vat`, `bj_ifu`, `bo_tin`, `br_cnpj`, `br_cpf`, `bs_tin`, `by_tin`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `cd_nif`, `ch_uid`, `ch_vat`, `cl_tin`, `cm_niu`, `cn_tin`, `co_nit`, `cr_tin`, `cv_nif`, `de_stn`, `do_rcn`, `ec_ruc`, `eg_tin`, `es_cif`, `et_tin`, `eu_oss_vat`, `eu_vat`, `fo_vat`, `gb_vat`, `ge_vat`, `gi_tin`, `gn_nif`, `hk_br`, `hr_oib`, `hu_tin`, `ic_nif`, `id_npwp`, `il_vat`, `in_gst`, `is_vat`, `it_cf`, `jp_cn`, `jp_rn`, `jp_trn`, `ke_pin`, `kg_tin`, `kh_tin`, `kr_brn`, `kz_bin`, `la_tin`, `li_uid`, `li_vat`, `lk_vat`, `ma_vat`, `md_vat`, `me_pib`, `mk_vat`, `mr_nif`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `ng_tin`, `no_vat`, `no_voec`, `np_pan`, `nz_gst`, `om_vat`, `pe_ruc`, `ph_tin`, `pl_nip`, `py_ruc`, `ro_tin`, `rs_pib`, `ru_inn`, `ru_kpp`, `sa_vat`, `sg_gst`, `sg_uen`, `si_tin`, `sn_ninea`, `sr_fin`, `sv_nit`, `th_vat`, `tj_tin`, `tr_tin`, `tw_vat`, `tz_vat`, `ua_vat`, `ug_tin`, `us_ein`, `uy_ruc`, `uz_tin`, `uz_vat`, `ve_rif`, `vn_tin`, `za_vat`, `zm_tin`, or `zw_tin`. Note that some legacy tax IDs have type `unknown`
`value` required	string	Value of the tax ID.
`verification`	one of multiple schemas	Tax ID verification information.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors