# Represent customers using Account objects Manage your customers using the Accounts v2 API instead of the Customers API. The Accounts v2 API is GA for Connect users, and in public preview for other Stripe users. All Stripe users can enable Accounts v2 [in their Dashboard](https://dashboard.stripe.com/settings/connect/platform-setup). However, when making calls to the Accounts v2 API, preview users need to [specify a preview version](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning). 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` | |