# Represent customers using Account objects Manage your customers using the Accounts v2 API instead of the Customers API. The Accounts v2 API uses *configurations* (Account configurations represent role-based functionality that you can enable for accounts, such as merchant, customer, or recipient) 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](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) 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`. ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: $latestPreviewApiVersion" \ --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. | Purpose | v1 reference | v2 reference | | ----------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Customer reference | `customer` | `customer_account` | | Customer identification | `cus_xxxxx` | `acct_xxxxx` | | Set billing address | [address](https://docs.stripe.com/api/customers/create.md#create_customer-address) | - [identity.individual.address](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-identity-individual-address) if the entity type is `individual`. - [identity.business_details.address](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-identity-business_details-address) if the entity type is any type other than `individual`. | | Set shipping address | [shipping](https://docs.stripe.com/api/customers/create.md#create_customer-shipping) | [configuration.customer.shipping](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-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`. ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Version: $latestPreviewApiVersion" \ -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. ```javascript { "id": "sub_1Mow234", . . . "customer": "cus_xxxxx", "customer_account": "acct_xxxxx" } ``` You can also retrieve or update customer-configured Accounts using the `/v1/customers` endpoint. ```curl curl -X POST https://api.stripe.com/v1/customers/acct_1234 \ -u "<>:" ``` ## Accounts v2 webhooks Webhooks for Accounts v2 send [thin events](https://docs.stripe.com/event-destinations.md#thin-events). | Action | v1 event | v2 event | | ----------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Customer created | `customer.created` | Accounts v2 sends separate events indicating the account creation and the customer configuration: - `v2.core.account.created` - `v2.core.account[configuration.customer].updated` | | Billing address updated | `customer.updated` | `v2.core.account[identity].updated` | | Subscription actions | `customer.subscription.[action]` | None; use the v1 event | | Customer deleted | `customer.deleted` | `v2.core.account.closed` | ## Customer invoice properties | Data value | Customers v1 property | Accounts v2 property | | ------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Customer stored credit | `invoice_credit_balance` | None; see [Reference an Accounts v2 ID in a /v1/customers path](https://docs.stripe.com/connect/use-accounts-as-customers.md#reference-accounts-v2-in-v1-customers-path) | | Customer invoice prefix | `invoice_prefix` | [configuration.customer.billing.invoice.prefix](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-prefix) | | Custom settings | `invoice_settings.custom_fields` | [configuration.customer.billing.invoice.custom_fields](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-custom_fields) | | Default payment method | `invoice_settings.default_payment_method` | [configuration.customer.billing.default_payment_method](https://docs.stripe.com/api/v2/core/accounts/update.md#v2_update_accounts-response-configuration-customer-billing-default_payment_method) | | Invoice footer | `invoice_settings.footer` | [configuration.customer.billing.invoice.footer](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-footer) | | Invoice rendering options | `invoice_settings.rendering_options` | [configuration.customer.billing.invoice.rendering.template](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-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](https://docs.stripe.com/api/invoices/object.md?api-version=preview#invoice_object-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 property | Notes | | ------------------------ | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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_method` | `configuration.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` | | ## Enable the Accounts v2 preview Previously, the Accounts v2 API was only available to Connect platforms. It’s now available in preview for all Stripe users. Accounts v2 gives you a unified way to represent your users across Stripe products. Instead of using `Customer` objects, which only provide functionality for storing payment methods and making recurring payments, you can use `Account` objects, which offer greater flexibility through the use of configurations when additional functionality is required. To enable the preview: 1. Go to [Account previews and features](https://dashboard.stripe.com/settings/features/product-previews) in your Dashboard. 1. Enable the **Reusable payment methods for Global Payouts** toggle. If you don’t see the toggle, request access using the form at the top of this page. When you opt in, your existing `Customer` objects are automatically synced with corresponding customer-configured v2 `Account` objects. When you create a new customer in the Dashboard, it generates a customer-configured `Account` object, not a `Customer` object. You can use these `Accounts` in [most integrations that reference Customer objects](https://docs.stripe.com/connect/use-accounts-as-customers.md#reference-accounts-in-customers-v1-integrations). Enabling the Accounts v2 preview also enables [reusable payment credentials for Global Payouts](https://docs.stripe.com/global-payouts/credential-reuse.md), which let you store and reuse payment methods across Global Payouts transactions. ## Limitations and opting out The Accounts v2 preview doesn’t support the following features: - [Cloning customers](https://docs.stripe.com/get-started/data-migrations/pan-copy-self-serve.md) - [Sharing customers and payment methods in an organization](https://docs.stripe.com/get-started/account/orgs/sharing/customers-payment-methods.md) - Third-party tax integrations (Stripe Tax is supported) To opt out, turn off the toggle in [Account previews and features](https://dashboard.stripe.com/settings/features/product-previews). Opting out doesn’t revert existing `Customer` objects that are already associated with v2 `Account` objects. If you need unsupported functionality for those customers, you need to create new `Customer` objects for them.