Stripe: Update a customer

← Customers operations · Get started

Operation stripe.postcustomerscustomer

Provider route: POST /v1/customers/{customer}. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["customers"]["postCustomersCustomer"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.customers.postCustomersCustomer(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.customers.post_customers_customer(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.customer	string	Required within parent	Maximum length: 5000
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Optional	Additional keys: not allowed
body.address	JSON	Optional	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).
body.address (anyOf 1)	object	Alternative
body.address (anyOf 1).city	string	Optional	Maximum length: 5000
body.address (anyOf 1).country	string	Optional	Maximum length: 5000
body.address (anyOf 1).line1	string	Optional	Maximum length: 5000
body.address (anyOf 1).line2	string	Optional	Maximum length: 5000
body.address (anyOf 1).postal_code	string	Optional	Maximum length: 5000
body.address (anyOf 1).state	string	Optional	Maximum length: 5000
body.address (anyOf 2)	string	Alternative	One of:
body.balance	integer	Optional	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.
body.bank_account	JSON	Optional	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.
body.bank_account (anyOf 1)	Model	Alternative	Expand Update a customer — request body — body / bank_account / account_holder_type: company, individual, object: bank account
body.bank_account (anyOf 2)	string	Alternative	Maximum length: 5000
body.business_name	JSON	Optional	The customer’s business name. This may be up to 150 characters.
body.business_name (anyOf 1)	string	Alternative	Maximum length: 150
body.business_name (anyOf 2)	string	Alternative	One of:
body.card	JSON	Optional	A token, like the ones returned by [Stripe.js](https://stripe.com/docs/js).
body.card (anyOf 1)	Model	Alternative	Expand Create a charge — request body — body / card / object: card
body.card (anyOf 2)	string	Alternative	Maximum length: 5000
body.cash_balance	object	Optional	Balance information and default balance settings for this customer.
body.cash_balance.settings	object	Optional
body.cash_balance.settings.reconciliation_mode	string	Optional	One of: automatic, manual, merchant_default
body.default_alipay_account	string	Optional	ID of Alipay account to make the customer’s new default for invoice payments. Maximum length: 500
body.default_bank_account	string	Optional	ID of bank account to make the customer’s new default for invoice payments. Maximum length: 500
body.default_card	string	Optional	ID of card to make the customer’s new default for invoice payments. Maximum length: 500
body.default_source	string	Optional	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. Maximum length: 500
body.description	string	Optional	An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard. Maximum length: 5000
body.email	string	Optional	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. Maximum length: 512
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.individual_name	JSON	Optional	The customer’s full name. This may be up to 150 characters.
body.individual_name (anyOf 1)	string	Alternative	Maximum length: 150
body.individual_name (anyOf 2)	string	Alternative	One of:
body.invoice_prefix	string	Optional	The prefix for the customer used to generate unique invoice numbers. Must be 1–12 uppercase letters or numbers. Maximum length: 5000
body.invoice_settings	Model	Optional	Expand Create a customer — request body — body invoice settings
body.metadata	JSON	Optional	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`.
body.metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
body.metadata (anyOf 1).*	string	Additional keys
body.metadata (anyOf 2)	string	Alternative	One of:
body.name	string	Optional	The customer’s full name or business name. Maximum length: 256
body.next_invoice_sequence	integer	Optional	The sequence to be used on the customer’s next invoice. Defaults to 1.
body.phone	string	Optional	The customer’s phone number. Maximum length: 20
body.preferred_locales	array	Optional	Customer’s preferred languages, ordered by preference.
body.preferred_locales[]	string	Each item	Maximum length: 5000
body.shipping	JSON	Optional	The customer’s shipping information. Appears on invoices emailed to this customer.
body.shipping (anyOf 1)	object	Alternative
body.shipping (anyOf 1).address	object	Required within parent
body.shipping (anyOf 1).address.city	string	Optional	Maximum length: 5000
body.shipping (anyOf 1).address.country	string	Optional	Maximum length: 5000
body.shipping (anyOf 1).address.line1	string	Optional	Maximum length: 5000
body.shipping (anyOf 1).address.line2	string	Optional	Maximum length: 5000
body.shipping (anyOf 1).address.postal_code	string	Optional	Maximum length: 5000
body.shipping (anyOf 1).address.state	string	Optional	Maximum length: 5000
body.shipping (anyOf 1).name	string	Required within parent	Maximum length: 5000
body.shipping (anyOf 1).phone	string	Optional	Maximum length: 5000
body.shipping (anyOf 2)	string	Alternative	One of:
body.source	string	Optional	Maximum length: 5000
body.tax	object	Optional	Tax details about the customer.
body.tax.ip_address	JSON	Optional
body.tax.ip_address (anyOf 1)	string	Alternative
body.tax.ip_address (anyOf 2)	string	Alternative	One of:
body.tax.validate_location	string	Optional	One of: auto, deferred, immediately
body.tax_exempt	string	Optional	The customer’s tax exemption. One of `none`, `exempt`, or `reverse`. One of: , exempt, none, reverse

Referenced models: Update a customer — request body — body / bank_account / account_holder_type: company, individual, object: bank account, Create a charge — request body — body / card / object: card, Create a customer — request body — body invoice settings

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a customer — response body

Referenced models: Create a customer — response body

Schemas

704 more schemas are linked from the tables above, on the schema pages.

Update a customer — request body — body / bank_account / account_holder_type: company, individual, object: bank account

Field	Type	Presence	Description and constraints
$	object	Root
account_holder_name	string	Optional	Maximum length: 5000
account_holder_type	string	Optional	One of: company, individual Maximum length: 5000
account_number	string	Required within parent	Maximum length: 5000
country	string	Required within parent	Maximum length: 5000
currency	string	Optional	Format: currency
object	string	Optional	One of: bank_account Maximum length: 5000
routing_number	string	Optional	Maximum length: 5000

Create a charge — request body — body / card / object: card

Field	Type	Presence	Description and constraints
$	object	Root
address_city	string	Optional	Maximum length: 5000
address_country	string	Optional	Maximum length: 5000
address_line1	string	Optional	Maximum length: 5000
address_line2	string	Optional	Maximum length: 5000
address_state	string	Optional	Maximum length: 5000
address_zip	string	Optional	Maximum length: 5000
cvc	string	Optional	Maximum length: 5000
encrypted	string	Optional	Maximum length: 5000
exp_month	integer	Required within parent
exp_year	integer	Required within parent
metadata	object	Optional	Additional keys: see wildcard field
metadata.*	string	Additional keys
name	string	Optional	Maximum length: 5000
network_token	object	Optional
network_token.number	string	Optional	Maximum length: 5000
number	string	Required within parent	Maximum length: 5000
object	string	Optional	One of: card Maximum length: 5000
swipe_data	string	Optional	Maximum length: 5000

Create a customer — request body — body invoice settings

Field	Type	Presence	Description and constraints
$	object	Root	Default invoice settings for this customer.
custom_fields	JSON	Optional
custom_fields (anyOf 1)	array	Alternative
custom_fields (anyOf 1)[]	object	Each item
custom_fields (anyOf 1)[].name	string	Required within parent	Maximum length: 40
custom_fields (anyOf 1)[].value	string	Required within parent	Maximum length: 140
custom_fields (anyOf 2)	string	Alternative	One of:
default_payment_method	string	Optional	Maximum length: 5000
footer	string	Optional	Maximum length: 5000
rendering_options	JSON	Optional
rendering_options (anyOf 1)	object	Alternative
rendering_options (anyOf 1).amount_tax_display	string	Optional	One of: , exclude_tax, include_inclusive_tax
rendering_options (anyOf 1).template	string	Optional	Maximum length: 5000
rendering_options (anyOf 2)	string	Alternative	One of:

Create a Location — response body — address

Field	Type	Presence	Description and constraints
$	object	Root
city	JSON	Optional
city (anyOf 1)	string	Alternative	City, district, suburb, town, or village. Maximum length: 5000
city (anyOf 2)	null	Alternative
country	JSON	Optional
country (anyOf 1)	string	Alternative	Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). Maximum length: 5000
country (anyOf 2)	null	Alternative
line1	JSON	Optional
line1 (anyOf 1)	string	Alternative	Address line 1, such as the street, PO Box, or company name. Maximum length: 5000
line1 (anyOf 2)	null	Alternative
line2	JSON	Optional
line2 (anyOf 1)	string	Alternative	Address line 2, such as the apartment, suite, unit, or building. Maximum length: 5000
line2 (anyOf 2)	null	Alternative
postal_code	JSON	Optional
postal_code (anyOf 1)	string	Alternative	ZIP or postal code. Maximum length: 5000
postal_code (anyOf 2)	null	Alternative
state	JSON	Optional
state (anyOf 1)	string	Alternative	State, county, province, or region ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)). Maximum length: 5000
state (anyOf 2)	null	Alternative

Retrieve a cash balance — response body

Field	Type	Presence	Description and constraints
$	object	Root	A customer's `Cash balance` represents real funds. Customers can add funds to their cash balance by sending a bank transfer. These funds can be used for payment and can eventually be paid out to your bank account.
available	JSON	Optional
available (anyOf 1)	object	Alternative	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). Additional keys: see wildcard field
available (anyOf 1).*	JSON	Additional keys
available (anyOf 1).* (anyOf 1)	integer	Alternative
available (anyOf 1).* (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
available (anyOf 2)	null	Alternative
customer	string	Required within parent	The ID of the customer whose cash balance this object represents. Maximum length: 5000
customer_account	JSON	Optional
customer_account (anyOf 1)	string	Alternative	The ID of an Account representing a customer whose cash balance this object represents. Maximum length: 5000
customer_account (anyOf 2)	null	Alternative
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: cash_balance
settings	Model	Required within parent	Expand Retrieve a cash balance — response body — settings

Referenced models: Retrieve a cash balance — response body — settings

Create a customer — response body — tax

Field	Type	Presence	Description and constraints
$	object	Root
automatic_tax	string	Required within parent	Surfaces if automatic tax computation is possible given the current customer location information. Known values: failed, not_collecting, supported, unrecognized_location
ip_address	JSON	Optional
ip_address (anyOf 1)	string	Alternative	A recent IP address of the customer used for tax reporting and tax location inference. Maximum length: 5000
ip_address (anyOf 2)	null	Alternative
location	JSON	Optional
location (anyOf 1)	JSON	Alternative	The identified tax location of the customer.
location (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a customer — response body — tax / location / The identified tax location of the customer / source: billing address, ip address, payment method, shipping destination
location (anyOf 2)	null	Alternative
provider	string	Required within parent	The tax calculation provider used for location resolution. Defaults to `stripe` when not using a [third-party provider](/tax/third-party-apps). Known values: anrok, avalara, sphere, stripe

Referenced models: Create a customer — response body — tax / location / The identified tax location of the customer / source: billing address, ip address, payment method, shipping destination

Create a source — response body — source order shipping

Field	Type	Presence	Description and constraints
$	object	Root
address	Model	Optional	Expand Create a Location — response body — address
carrier	JSON	Optional
carrier (anyOf 1)	string	Alternative	The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. Maximum length: 5000
carrier (anyOf 2)	null	Alternative
name	string	Optional	Recipient name. Maximum length: 5000
phone	JSON	Optional
phone (anyOf 1)	string	Alternative	Recipient phone (including extension). Maximum length: 5000
phone (anyOf 2)	null	Alternative
tracking_number	JSON	Optional
tracking_number (anyOf 1)	string	Alternative	The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas. Maximum length: 5000
tracking_number (anyOf 2)	null	Alternative

Referenced models: Create a Location — response body — address

Delete a customer — response body

Field	Type	Presence	Description and constraints
$	object	Root
deleted	boolean	Required within parent	Always true for a deleted object Known values: True
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: customer

Policy, approvals and errors

SDK function policy ID: stripe.postcustomerscustomer. Catalog operation: PostCustomersCustomer. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source