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.

Path parameters

Name	Description
customer*

Request body

Field Type Description

address

object | string

The customer's address. Learn about country-specific requirements for calculating tax.

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

object | string

Either a token, like the ones returned by Stripe.js, or a dictionary containing a user's bank account details.

business_name

string | string

The customer's business name. This may be up to *150 characters*.

card

object | string

A token, like the ones returned by Stripe.js.

cash_balance

object

Balance information and default balance settings for this customer.

1 nested field

Field

Type

Description

settings

object

1 nested field

Field	Type	Description
reconciliation_mode	string

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 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 property.

description

string

An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.

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

Specifies which fields in the response should be expanded.

individual_name

string | string

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.

4 nested fields

Field	Type	Description
custom_fields	array<object> \| string
default_payment_method	string
footer	string
rendering_options	object \| string

metadata

object | string

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

Customer's preferred languages, ordered by preference.

shipping

object | string

The customer's shipping information. Appears on invoices emailed to this customer.

source string

tax

object

Tax details about the customer.

2 nested fields

Field	Type	Description
ip_address	string \| string
validate_location	string

tax_exempt

string

The customer's tax exemption. One of none, exempt, or reverse.

Response

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.