Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Update a customer 

Core Resources
Customers
Update a customer

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 source 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 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 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 default_source for a customer will not trigger this behavior.

This request accepts mostly the same arguments as the customer creation call.

Parameters

  • addressobjectRequired if calculating taxes

    The customer’s address.

    • address.citystring

      City, district, suburb, town, or village.

    • address.countrystringRequired if calculating taxes

      A freeform text field for the country. However, in order to activate some tax features, the format should be a two-letter country code (ISO 3166-1 alpha-2).

    • address.line1string

      Address line 1 (e.g., street, PO Box, or company name).

    • address.line2string

      Address line 2 (e.g., apartment, suite, unit, or building).

    • address.postal_codestringRequired if calculating taxes

      ZIP or postal code.

    • address.statestring

      State, county, province, or region.

  • descriptionstring

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

  • emailstring

    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.

  • metadataobject

    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.

  • namestring

    The customer’s full name or business name.

  • phonestring

    The customer’s phone number.

  • shippingobject

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

    • shipping.addressobjectRequired

      Customer shipping address.

      • shipping.address.citystring

        City, district, suburb, town, or village.

      • shipping.address.countrystringRequired if calculating taxes

        A freeform text field for the country. However, in order to activate some tax features, the format should be a two-letter country code (ISO 3166-1 alpha-2).

      • shipping.address.line1string

        Address line 1 (e.g., street, PO Box, or company name).

      • shipping.address.line2string

        Address line 2 (e.g., apartment, suite, unit, or building).

      • shipping.address.postal_codestringRequired if calculating taxes

        ZIP or postal code.

      • shipping.address.statestring

        State, county, province, or region.

    • shipping.namestringRequired

      Customer name.

    • shipping.phonestring

      Customer phone (including extension).

  • taxobjectRecommended if calculating taxes

    Tax details about the customer.

    • tax.ip_addressstring

      A recent IP address of the customer used for tax reporting and tax location inference. Stripe recommends updating the IP address when a new PaymentMethod is attached or the address field on the customer is updated. We recommend against updating this field more frequently since it could result in unexpected tax location/reporting outcomes.

    • tax.validate_locationenumRecommended if calculating taxes

      A flag that indicates when Stripe should validate the customer tax location. Defaults to auto.

      Possible enum values
      auto

      Validate the customer’s tax location immediately if it has automatic tax enabled subscriptions. Recommended. Default.

      deferred

      Defer the validation of the customer’s tax location until needed, such as when Stripe Tax is calculating taxes on an Invoice. Deprecated.

      immediately

      Validate the customer’s tax location immediately. An error is returned and the customer is not created/updated if the tax location is invalid.

More parameters

  • balanceinteger

    An integer amount in cents 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.

  • cash_balanceobject

    Balance information and default balance settings for this customer.

    • cash_balance.settingsobject

      Settings controlling the behavior of the customer’s cash balance, such as reconciliation of funds received.

      • cash_balance.settings.reconciliation_modeenum

        Controls how funds transferred by the customer are applied to payment intents and invoices. Valid options are automatic, manual, or merchant_default. For more information about these reconciliation modes, see Reconciliation.

        Possible enum values
        automatic
        manual
        merchant_default

  • default_sourcestring

    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.

  • invoice_prefixstring

    The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.

  • invoice_settingsobject

    Default invoice settings for this customer.

    • invoice_settings.custom_fieldsarray of objects

      The list of up to 4 default custom fields to be displayed on invoices for this customer. When updating, pass an empty string to remove previously-defined fields.

      • invoice_settings.custom_fields.namestringRequired

        The name of the custom field. This may be up to 40 characters.

      • invoice_settings.custom_fields.valuestringRequired

        The value of the custom field. This may be up to 140 characters.

    • invoice_settings.default_payment_methodstring

      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.

    • invoice_settings.footerstring

      Default footer to be displayed on invoices for this customer.

    • invoice_settings.rendering_optionsobject

      Default options for invoice PDF rendering for this customer.

      • invoice_settings.rendering_options.amount_tax_displayenum

        How line-item prices and amounts will be displayed with respect to tax on invoice PDFs. One of exclude_tax or include_inclusive_tax. include_inclusive_tax will include inclusive tax (and exclude exclusive tax) in invoice PDF amounts. exclude_tax will exclude all tax (inclusive and exclusive alike) from invoice PDF amounts.

        Possible enum values
        exclude_tax
        include_inclusive_tax

      • invoice_settings.rendering_options.templatestring

        ID of the invoice rendering template to use for future invoices.

  • next_invoice_sequenceinteger

    The sequence to be used on the customer’s next invoice. Defaults to 1.

  • preferred_localesarray of strings

    Customer’s preferred languages, ordered by preference.

  • sourcestring

    When using payment sources created via the Token or Sources APIs, passing source will create a new source object, make it the new customer default source, and delete the old customer default if one exists. If you want to add additional sources instead of replacing the existing default, use the card creation API. Whenever you attach a card to a customer, Stripe will automatically validate the card.

  • tax_exemptenum

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

    Possible enum values
    exempt
    none
    reverse

Returns

Returns the customer object if the update succeeded. Raises an error if update parameters are invalid (e.g. specifying an invalid coupon or an invalid source).

POST /v1/customers/:id
curl https://api.stripe.com/v1/customers/cus_NffrFeUfNV2Hib \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "metadata[order_id]"=6735
Response
{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  "address": null,
  "balance": 0,
  "created": 1680893993,
  "currency": null,
  "default_source": null,
  "delinquent": false,
  "description": null,
  "email": "jennyrosen@example.com",
  "invoice_prefix": "0759376C",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": null,
    "footer": null,
    "rendering_options": null
  },
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "name": "Jenny Rosen",
  "next_invoice_sequence": 1,
  "phone": null,
  "preferred_locales": [],
  "shipping": null,
  "tax_exempt": "none",
  "test_clock": null
}