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.

Query parameters

Name	Description
created	Only return customers that were created during the given date interval.
email	A case-sensitive filter on the list based on the customer's `email` field. The value must be a string.
ending_before	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	Specifies which fields in the response should be expanded.
limit	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
starting_after	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	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.

Request body

object (no properties in spec)

Response

Field Type Description

data*

array<customer>

array item fields

Field Type Description

address

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.

business_name

string

The customer's business name.

cash_balance

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*

integer (unix-time)

Time at which the object was created. Measured in seconds since the Unix epoch.

currency

string

Three-letter ISO code for the currency 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

string | bank_account | card | source

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 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, 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

Describes the current discount active on the customer, if there is one.

string

The customer's email address.

id*

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

4 nested fields

Field	Type	Description
custom_fields	array<invoice_setting_custom_field>	Default custom fields to be displayed on invoices for this customer.
default_payment_method	string \| payment_method	ID of a payment method that's attached to the customer, to be used as the customer's default payment method for subscriptions and invoices.
footer	string	Default footer to be displayed on invoices for this customer.
rendering_options	invoice_setting_customer_rendering_options	Default options for invoice PDF rendering for this customer.

livemode*

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 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*

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<string>

The customer's preferred locales (languages), ordered by preference.

shipping

Mailing and shipping address for the customer. Appears on invoices emailed to this customer.

sources

object

The customer's payment sources, if any.

4 nested fields

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

subscriptions

object

The customer's current subscriptions, if any.

4 nested fields

Field Type Description

data*

array<subscription>

Details about each object.

array item fields

Field Type Description

application

string | application | deleted_application

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* subscription_automatic_tax

billing_cycle_anchor*

integer (unix-time)

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. The timestamp is in UTC format.

billing_cycle_anchor_config

subscriptions_resource_billing_cycle_anchor_config

The fixed values used to calculate the billing_cycle_anchor.

billing_mode* subscriptions_resource_billing_mode

billing_schedules*

array<subscriptions_resource_billing_schedules>

Billing schedules for this subscription.

billing_thresholds

subscription_billing_thresholds

Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period

cancel_at

integer (unix-time)

A date in the future at which the subscription will automatically get canceled

cancel_at_period_end*

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 (unix-time)

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

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.

created*

integer (unix-time)

Time at which the object was created. Measured in seconds since the Unix epoch.

currency*

string (currency)

Three-letter ISO currency code, in lowercase. Must be a supported currency.

customer*

string | customer | deleted_customer

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

string | payment_method

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 or default_source.

default_source

string | bank_account | card | source

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 or default_source.

default_tax_rates

array<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*

array<string | discount>

The discounts applied to the subscription. Subscription item discounts are applied before subscription discounts. Use expand[]=discounts to expand each discount.

ended_at

integer (unix-time)

If the subscription has ended, the date the subscription ended.

id*

string

Unique identifier for the object.

invoice_settings* subscriptions_resource_subscription_invoice_settings

items*

object

List of subscription items, each with an attached price.

4 nested fields

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

latest_invoice

string | invoice

The most recent invoice this subscription has generated over its lifecycle (for example, when it cycles or is updated).

livemode*

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

smor_resource_managed_payments

Settings for Managed Payments for this Subscription and resulting Invoices and PaymentIntents.

has_more*

boolean

True if this list has another page of items after this one that can be fetched.

object*

string

String representing the object's type. Objects of the same type share the same value. Always has the value list.

url*

string

The URL where this list can be accessed.

tax

customer_tax

4 nested fields

Field	Type	Description
automatic_tax*	string	Surfaces if automatic tax computation is possible given the current customer location information.
ip_address	string	A recent IP address of the customer used for tax reporting and tax location inference.
location	customer_tax_location	The identified tax location of the customer.
provider*	string	The tax calculation provider used for location resolution. Defaults to `stripe` when not using a third-party provider.

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.

4 nested fields

Field Type Description

data*

array<tax_id>

Details about each object.

array item fields

Field	Type	Description
country	string	Two-letter ISO code representing the country of the tax ID.
created*	integer (unix-time)	Time at which the object was created. Measured in seconds since the Unix epoch.
customer	string \| customer	ID of the customer.
customer_account	string	ID of the Account representing the customer.
id*	string	Unique identifier for the object.
livemode*	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
object*	string	String representing the object's type. Objects of the same type share the same value.
owner	tax_i_ds_owner	The account or customer the tax ID belongs to.
type*	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`, `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*	string	Value of the tax ID.
verification	tax_id_verification	Tax ID verification information.

has_more*

boolean

True if this list has another page of items after this one that can be fetched.

object*

string

String representing the object's type. Objects of the same type share the same value. Always has the value list.

url*

string

The URL where this list can be accessed.

has_more*

boolean

True if this list has another page of items after this one that can be fetched.

object*

string

String representing the object's type. Objects of the same type share the same value. Always has the value list.

url*

string

The URL where this list can be accessed.