Stripe Customers API
This object represents a customer of your business. Use it to create recurring charges and track payments that belong to the same customer.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Customers API
description: >-
This object represents a customer of your business. Use it to create
recurring charges and track payments that belong to the same customer.
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/customers:
get:
description: >-
<p>Returns a list of your customers. The customers are returned sorted
by creation date, with the most recent customers appearing first.</p>
operationId: getCustomers
parameters:
- explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: >-
A case-sensitive filter on the list based on the customer's `email`
field. The value must be a string.
in: query
name: email
required: false
schema:
maxLength: 512
type: string
style: form
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
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.
in: query
name: test_clock
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/CustomerResourceCustomerList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Customers
- Get
post:
description: <p>Creates a new customer object.</p>
operationId: postCustomers
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
address:
explode: true
style: deepObject
cash_balance:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
invoice_settings:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
preferred_locales:
explode: true
style: deepObject
shipping:
explode: true
style: deepObject
tax:
explode: true
style: deepObject
tax_id_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCustomersRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/customer'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Customers
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Customers
- Post
/v1/customers/search:
get:
description: >-
<p>Search for customers you’ve previously created using Stripe’s <a
href="/docs/search#search-query-language">Search Query Language</a>.
Don’t use search in read-after-write flows where strict consistency is
necessary. Under normal operating
conditions, data is searchable in less than a minute. Occasionally,
propagation of new or updated data can be up
to an hour behind during outages. Search functionality is not available
to merchants in India.</p>
operationId: getCustomersSearch
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for pagination across multiple pages of results. Don't
include this parameter on the first call. Use the next_page value
returned in a previous response to request subsequent results.
in: query
name: page
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
The search query string. See [search query
language](https://stripe.com/docs/search#search-query-language) and
the list of supported [query fields for
customers](https://stripe.com/docs/search#query-fields-for-customers).
in: query
name: query
required: true
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersSearchRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/SearchResult'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Search
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Customers
- Get
- Search
/v1/customers/{customer}:
delete:
description: >-
<p>Permanently deletes a customer. It cannot be undone. Also immediately
cancels any active subscriptions on the customer.</p>
operationId: deleteCustomersCustomer
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/DeleteCustomersCustomerRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/deleted_customer'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Delete Customers Customer
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Customer
- Customers
- Delete
get:
description: <p>Retrieves a Customer object.</p>
operationId: getCustomersCustomer
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersCustomerRequest'
required: false
responses:
'200':
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Customer
- Customers
- Get
post:
description: >-
<p>Updates the specified customer by setting the values of the
parameters passed. Any parameters not provided will be left unchanged.
For example, if you pass the <strong>source</strong> parameter, that
becomes the customer’s active source (e.g., 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 <strong>source</strong> parameter: for each of the
customer’s current subscriptions, if the subscription bills
automatically and is in the <code>past_due</code> state, then the latest
open invoice for the subscription with automatic collection enabled will
be retried. This retry will not count as an automatic retry, and will
not affect the next regularly scheduled payment for the invoice.
Changing the <strong>default_source</strong> for a customer will not
trigger this behavior.</p>
<p>This request accepts mostly the same arguments as the customer
creation call.</p>
operationId: postCustomersCustomer
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
address:
explode: true
style: deepObject
bank_account:
explode: true
style: deepObject
card:
explode: true
style: deepObject
cash_balance:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
invoice_settings:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
preferred_locales:
explode: true
style: deepObject
shipping:
explode: true
style: deepObject
tax:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCustomersCustomerRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/customer'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Customers Customer
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Customer
- Customers
- Post
/v1/customers/{customer}/balance_transactions:
get:
description: >-
<p>Returns a list of transactions that updated the customer’s <a
href="/docs/billing/customer/balance">balances</a>.</p>
operationId: getCustomersCustomerBalanceTransactions
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: >-
#/components/schemas/GetCustomersCustomerBalanceTransactionsRequest
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/CustomerBalanceTransactionList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer Balance Transactions
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Balance
- Customer
- Customers
- Get
- Transactions
post:
description: >-
<p>Creates an immutable transaction that updates the customer’s credit
<a href="/docs/billing/customer/balance">balance</a>.</p>
operationId: postCustomersCustomerBalanceTransactions
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/PostCustomersCustomerBalanceTransactionsRequest
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/customer_balance_transaction'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Customers Customer Balance Transactions
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Balance
- Customer
- Customers
- Post
- Transactions
/v1/customers/{customer}/balance_transactions/{transaction}:
get:
description: >-
<p>Retrieves a specific customer balance transaction that updated the
customer’s <a href="/docs/billing/customer/balance">balances</a>.</p>
operationId: getCustomersCustomerBalanceTransactionsTransaction
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: transaction
required: true
schema:
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: >-
#/components/schemas/GetCustomersCustomerBalanceTransactionsTransactionRequest
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/customer_balance_transaction'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer Balance Transactions Transaction
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Balance
- Customer
- Customers
- Get
- Transaction
- Transactions
post:
description: >-
<p>Most credit balance transaction fields are immutable, but you may
update its <code>description</code> and <code>metadata</code>.</p>
operationId: postCustomersCustomerBalanceTransactionsTransaction
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- in: path
name: transaction
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/PostCustomersCustomerBalanceTransactionsTransactionRequest
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/customer_balance_transaction'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Customers Customer Balance Transactions Transaction
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Balance
- Customer
- Customers
- Post
- Transaction
- Transactions
/v1/customers/{customer}/bank_accounts:
get:
deprecated: true
description: >-
<p>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 <code>limit</code> and <code>starting_after</code> parameters to
page through additional bank accounts.</p>
operationId: getCustomersCustomerBankAccounts
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersCustomerBankAccountsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/BankAccountList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer Bank Accounts
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Accounts
- Bank
- Customer
- Customers
- Get
post:
description: >-
<p>When you create a new credit card, you must specify a customer or
recipient on which to create it.</p>
<p>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 <a
href="/docs/api#update_customer">update the customer</a> to have a new
<code>default_source</code>.</p>
operationId: postCustomersCustomerBankAccounts
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
bank_account:
explode: true
style: deepObject
card:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCustomersCustomerBankAccountsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_source'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Customers Customer Bank Accounts
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Accounts
- Bank
- Customer
- Customers
- Post
/v1/customers/{customer}/bank_accounts/{id}:
delete:
description: <p>Delete a specified source for a given customer.</p>
operationId: deleteCustomersCustomerBankAccountsId
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- in: path
name: id
required: true
schema:
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/DeleteCustomersCustomerBankAccountsIdRequest
required: false
responses:
'200':
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/payment_source'
- $ref: '#/components/schemas/deleted_payment_source'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Delete Customers Customer Bank Accounts Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Accounts
- Bank
- Customer
- Customers
- Delete
- Identifiers
get:
deprecated: true
description: >-
<p>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.</p>
operationId: getCustomersCustomerBankAccountsId
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
# --- truncated at 32 KB (302 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-customers-api-openapi.yml