Skip to content
Create account or Sign in
/Ask AI
Create accountSign in
APIs & SDKsHelp
Canada
English (United States)

Represent customers using Account objectsPublic preview

Manage your customers using the Accounts v2 API instead of the Customers API.

The Accounts v2 API uses configurations to enable functionality for Account objects. When using the v2 API, you can represent a customer using an Account object instead of a Customer object by assigning the customer configuration to the Account. When making a request that accepts a Customer ID as the argument to the customer parameter, instead provide the Account ID as the argument to the customer_account parameter.

The following example creates an Account with the customer configuration and requests the common automatic_indirect_tax capability, which is part of the customer configuration. Requesting the capability is optional; you can simply add the configuration by specifying configuration.customer.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "country": "us",
        "individual": {
            "given_name": "Jenny Rosen"
        }
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'

When you enable the Accounts v2 API, your Stripe-hosted integrations, such as Checkout, create Accounts with the customer configuration instead of Customer objects. If your code references Customer objects, we recommend that you update it to reference customer-configured Account objects instead.

Purposev1 referencev2 reference
Customer referencecustomercustomer_account
Customer identificationcus_xxxxxacct_xxxxx
Set billing addressaddress
Set shipping addressshippingconfiguration.customer.shipping

Provide an Account as the customer

API requests such as Subscriptions and SetupIntents require you to specify a customer. These requests accept either the customer or customer_account parameter. The following example creates a subscription and specifies the customer by passing an Account ID as the customer_account.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -H "Stripe-Version: 2025-04-30.preview" \
  -d customer_account=acct_xxxxx \
  -d "items[0][price]=price_CBb6IXqvTLXp3f" \
  -d "items[0][quantity]=5"

Reference Accounts in Customers v1 integrations

A request that specifies customer_account returns both customer and customer_account properties, with correspondingly formatted values. This maintains compatibility with existing Billing and Payments integrations.

Example response
{
  "id": "sub_1Mow234",
  .
  .
  .
  "customer": "cus_xxxxx",
  "customer_account": "acct_xxxxx"
}

You can also retrieve or update customer-configured Accounts using the /v1/customers endpoint.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v1/customers/acct_1234 \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:"

Accounts v2 webhooks

Webhooks for Accounts v2 send thin events.

Actionv1 eventv2 event
Customer createdcustomer.createdAccounts v2 sends separate events indicating the account creation and the customer configuration:
  • v2.core.account.created
  • v2.core.account[configuration.customer].updated
Billing address updatedcustomer.updatedv2.core.account[identity].updated
Subscription actionscustomer.subscription.[action]None; use the v1 event
Customer deletedcustomer.deletedv2.core.account.closed

Customer invoice properties

Data valueCustomers v1 propertyAccounts v2 property
Customer stored creditinvoice_credit_balanceNone; see Reference an Accounts v2 ID in a /v1/customers path
Customer invoice prefixinvoice_prefixconfiguration.customer.billing.invoice.prefix
Custom settingsinvoice_settings.custom_fieldsconfiguration.customer.billing.invoice.custom_fields
Default payment methodinvoice_settings.default_payment_methodconfiguration.customer.billing.default_payment_method
Invoice footerinvoice_settings.footerconfiguration.customer.billing.invoice.footer
Invoice rendering optionsinvoice_settings.rendering_optionsconfiguration.customer.billing.invoice.rendering.template

Reference an Account ID with a Customers endpoint

The Accounts v2 API doesn’t have endpoints for every customer function. To perform the following actions for an Account object, use the v1/customers endpoint and pass the Account ID (acct_xxxxx) as the path parameter.

Use case v1 endpoint with account ID
Manage cash balances
  • v1/customers/acct_xxxxx/cash_balances
  • v1/customers/acct_xxxxx/cash_balances/:id
Manage cash balance transactions
  • GET v1/customers/acct_xxxxx/cash_balance_transactions
  • GET v1/customers/acct_xxxxx/cash_balance_transactions/:id
  • POST v1/test_helpers/customers/acct_xxxxx/fund_cash_balance
  • POST v1/customers/acct_xxxxx/funding_instructions
  • GET v1/customers/acct_xxxxx/funding_instructions

Manage invoice credit balance

For Account objects, the ending_balance of the account’s most recently finalized invoice corresponds to the Customer object’s invoice_credit_balance.

  • POST v1/customers/acct_xxxxx/balance_transactions
  • POST v1/customers/acct_xxxxx/balance_transactions/:id
  • GET v1/customers/acct_xxxxx/balance_transactions/:id
  • GET v1/customers/acct_xxxxx/balance_transactions

Customer-Account object property map

The following table describes how properties of Customer objects correspond to properties of customer-configured Account objects. Except where noted, Stripe copies the mapped values when generating an Account corresponding to an existing Customer.

Mapped values remain synchronized. For example, if you set identity.country on an Account, then when you pass that Account ID as the customer_account to a v1 endpoint, the returned country contains the same value.

Customers v1 property Accounts v2 propertyNotes
address {all properties} identity.business_details.address or identity.individual.address When Stripe associates a v1 Customer with a v2 Account, address is only included if it passes validation. address.country (string in v1 and enum in v2) is only included if it matches either a valid enum or country name, ignoring case and any special characters.
country identity.country When Stripe associates a v1 Customer with a v2 Account, address.country (string) only copies to identity.country (enum) if it matches either a valid enum or country name, ignoring case and any special characters.
business_name identity.business_details.registered_name
created {not mapped} When Stripe associates a v1 Customer with a v2 Account, the Account’s created property reflects the timestamp when the Account was created, not the original Customer.
currency {not mapped} The v2 Account’s defaults.currency property doesn’t apply to the customer configuration.
customer_account id When Stripe associates a v1 Customer with a v2 Account, the Customer’s customer_account property contains the ID of that Account. The ID of the Customer isn’t available on the Account. Users who create v2 Accounts representing customers don’t need to use a v1 Customer ID.
description {not mapped} The v1 Customer description isn’t available on the v2 Account. However, it appears (read-only) on the customer details page in the Dashboard.
email contact_email
id {not mapped} The ID of the v1 Customer isn’t available on the v2 Account. Users who create v2 Accounts representing customers don’t need to use a v1 Customer ID.
individual_name display_name When Stripe associates a v1 Customer with a v2 Account, it only copies individual_name if the Customer’s name is null.
invoice_prefix configuration.customer.billing.invoice.prefix
invoice_settings custom_fields configuration.customer.billing.invoice.custom_fields The Account array is limited to 4 elements.
default_payment_methodconfiguration.customer.billing.invoice.default_payment_method
footer configuration.customer.billing.invoice.footer
rendering_options configuration.customer.billing.invoice.rendering When Stripe associates a v1 Customer with a v2 Account, invoice_settings.rendering_options.amount_tax_display (string) only copies to configuration.customer.billing.invoice.rendering.amount_tax_display (enum) if it matches an enum value (include_inclusive_tax or exclude_tax).
livemode livemode
metadata metadata
name display_name When Stripe associates a v1 Customer with a v2 Account, if name is null, the Customer’s individual_name copies to display_name.
next_invoice_sequence configuration.customer.billing.invoice.next_sequence
phone identity.business_details.phone or identity.individual.phone
preferred_locales defaults.locales The Customer property preferred_locales is a nullable array of strings, and the Account property defaults.locales is a nullable array of enums. When Stripe associates a v1 Customer with a v2 Account, a given preferred_locales string is only included if it matches a defaults.locales enum value, ignoring case and any special characters.
shipping configuration.customer.shipping
subscriptions {not mapped} The v2 Account object doesn’t include an array of subscriptions. To retrieve a customer’s subscriptions, use the Subscriptions API and filter by customer or customer_account.
tax automatic_tax configuration.customer.capabilities.automatic_indirect_tax.status {value not synchronized} The Account property is only available after requesting the Automatic Indirect Tax capability. Also, it doesn’t have an equivalent to the Customer property’s not_collecting value. It only indicates the status of the capability.
ip_address configuration.customer.automatic_indirect_tax.ip_address
location configuration.customer.automatic_indirect_tax.location {value not synchronized} When Stripe associates a v1 Customer with a v2 Account, tax.location isn’t automatically included. You must request the Automatic Indirect Tax capability to set configuration.customer.automatic_indirect_tax.location.
provider {not mapped} If a Customer is associated with a third-party tax provider, Stripe doesn’t automatically associate that Customer with an Account.
tax_exempt configuration.customer.automatic_indirect_tax.exempt
tax_ids {not mapped} The v2 Account object doesn’t include an array of tax IDs. To retrieve a customer’s tax IDs, use the Tax IDs API and filter by owner.customer or owner.customer_account.
test_clock configuration.customer.test_clock
On this page
Morty Proxy This is a proxified and sanitized view of the page, visit original site.