Stripe: Create a customer

← Customers operations · Get started

Operation stripe.postcustomers

Provider route: POST /v1/customers. 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"]["postCustomers"]>[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.postCustomers(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(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
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.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.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.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.payment_method	string	Optional	Maximum length: 5000
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: deferred, immediately
body.tax_exempt	string	Optional	The customer’s tax exemption. One of `none`, `exempt`, or `reverse`. One of: , exempt, none, reverse
body.tax_id_data	array	Optional	The customer’s tax IDs.
body.tax_id_data[]	Model	Each item	Expand Create a customer — request body — body tax id data item
body.test_clock	string	Optional	ID of the test clock to attach to the customer. Maximum length: 5000

Referenced models: Create a customer — request body — body invoice settings, Create a customer — request body — body tax id data item

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

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

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 customer — request body — body tax id data item

Field	Type	Presence	Description and constraints
$	object	Root
type	string	Required within parent	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, ic_nif, 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, zw_tin Maximum length: 5000
value	string	Required within parent

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 customer — response body — invoice settings

Field	Type	Presence	Description and constraints
$	object	Root
custom_fields	JSON	Optional
custom_fields (anyOf 1)	array	Alternative	Default custom fields to be displayed on invoices for this customer.
custom_fields (anyOf 1)[]	Model	Each item	Expand Pay an invoice — response body — custom fields Custom fields displayed on the invoice item
custom_fields (anyOf 2)	null	Alternative
default_payment_method	JSON	Optional
default_payment_method (anyOf 1)	JSON	Alternative	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.
default_payment_method (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
default_payment_method (anyOf 1) (anyOf 2)	Model	Alternative	Expand Create a Payment Method — response body
default_payment_method (anyOf 2)	null	Alternative
footer	JSON	Optional
footer (anyOf 1)	string	Alternative	Default footer to be displayed on invoices for this customer. Maximum length: 5000
footer (anyOf 2)	null	Alternative
rendering_options	JSON	Optional
rendering_options (anyOf 1)	JSON	Alternative	Default options for invoice PDF rendering for this customer.
rendering_options (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a customer — response body — invoice settings rendering options value amount tax display, template
rendering_options (anyOf 2)	null	Alternative

Referenced models: Pay an invoice — response body — custom fields Custom fields displayed on the invoice item, Create a customer — response body — invoice settings rendering options value amount tax display, template, Create a Payment Method — response body

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

Create a Payment Method — response body — zip

Field	Type	Presence	Description and constraints
$	object	Root

Policy, approvals and errors

SDK function policy ID: stripe.postcustomers. Catalog operation: PostCustomers. 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