# Use the Accounts v2 API in your existing integration Learn how to update integrations built on Accounts v1 and Customers v1. Follow this guide if you want to update your Accounts v1 and Customers v1 Connect platform integration to gain access to the following Accounts v2 features: - Associate your connected accounts with payments they make to your platform without creating Customer objects. - Avoid network costs by allowing connected accounts to pay your platform using their Stripe balance. - Enable your connected accounts to hold funds on your platform using Treasury v2. If you don’t need Accounts v2 features, you can continue to use your Accounts v1 and Customers v1 platform integration. ## Use v2 endpoints for all your accounts You can use the Accounts v2 API with your existing v1 `Accounts` without making any changes to them. > #### Account creation delay > > A new v1 `Account` might require up to 10 minutes before you can use it with an Accounts v2 endpoint. When the `Account` is ready for API v2 requests, it sends a `v2.core.account.created` webhook event. ### Add a customer configuration Adding the `customer` configuration to an `Account` allows you to provide the `Account` ID in any API request that accepts a `Customer` ID, such as creating a subscription. Instead of providing a `Customer` ID in the `customer` parameter, you provide the `Account` ID in the `customer_account` parameter. The following example uses the Accounts v2 API to add the `customer` configuration to an existing v1 Account, then updates an existing subscription to charge the Account using its Stripe balance. 1. Update the `Account` to add the `customer` configuration. ```curl curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "configuration": { "customer": { "capabilities": { "automatic_indirect_tax": { "requested": true } } } }, "include": [ "configuration.customer", "identity" ] }' ``` 1. Retrieve the connected account to confirm it has the `card_payments` capability in the merchant configuration. This capability must be active in order to use the Stripe balance as a payment method. ```curl curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "include": [ "configuration.merchant", "identity", "defaults" ] }' ``` 1. Add the connected account’s Stripe balance as a payment method. ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d customer_account=acct_1abc \ -d "payment_method_types[]=stripe_balance" \ -d confirm=true \ -d usage=off_session \ -d "payment_method_data[type]=stripe_balance" ``` 1. Create a subscription that charges the connected account using its Stripe balance. ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer_account=acct_1abc \ -d payment_behavior=default_incomplete \ -d "items[0][price]={{PRICE_ID}}" \ -d "payment_settings[save_default_payment_method]=on_subscription" ``` You no longer need to maintain a separate `Customer` object to accept subscription payments from this connected account. ## Transition your integration in stages Because you can use both the Accounts v1 and v2 APIs with your `Accounts`, you can update your integration at the pace that meets your business needs. For example, you can: - Call `/v2/core/accounts` endpoints for `Accounts` created using API v1. - Call `/v1/accounts` endpoints for `Accounts` created using API v2. - Call `/v1/customers` endpoints for `Accounts` with the customer configuration. - Use the Events API v2 to listen for changes to objects created using either API version. These compatibilities let you update your integration in stages, without maintaining multiple versions in production or updating your entire integration at once. We recommend updating your integration in this order: 1. Set up a new endpoint to listen to [v2 Events](https://docs.stripe.com/event-destinations.md#thin-events). 1. Change your `Account` and `Customer` `create` calls to create customer-configured `Accounts` using `/v2/core/accounts`. 1. Change your `Account` and `Customer` `update` calls to use `/v2/core accounts`. 1. Change your `Account` and `Customer` `retrieve` calls to use `/v2/core/accounts`. ### Use v2 Accounts in v1 endpoints If you reference v2 objects in v1 endpoints, the response returns the v2 data in the v1 object structure. For example, - Referencing a v2 `Account` in a `/v1/accounts` endpoint returns the data in the structure of a v1 `Account`. - Referencing a v2 `Account` in a `/v1/customers` endpoint returns the data in the structure of a v1 `Customer`, and includes both the `customer` ID and `customer_account` ID. ```curl curl https://api.stripe.com/v1/customers/acct_1abc \ -u "<>:" \ -d "business_name=Furever Plus" ``` You can use customer-configured `Accounts` in the Customers v1 API, but you can’t reference v1 `Customers` in the Accounts v2 API. You must either migrate customer data into a new customer-configured `Account`, or update an existing connected account to add the `customer` configuration. ## Webhook events v2 `Accounts` send both [v1 (snapshot) Events and v2 (thin) Events](https://docs.stripe.com/event-destinations.md#events-overview). The v1 events depend on the updated configuration. For example, updating properties of the `merchant` configuration emits v1 `account.updated` events, while updating properties of the `customer` configuration emits v1 `customer.updated` events. We recommend setting up new endpoints to listen to v2 events. Webhooks for Connect users listen for events in different scopes, depending on the source of the event: - **Your account**: Most events triggered by resources that exist in your account. That includes most requests made using your API keys and without [authenticating as another Stripe account](https://docs.stripe.com/connect/authentication.md), such as: - `v2.core.account.*` events for v2 `Accounts` in your account - Events for `Customers` in your account - Events for direct charges on your account - Events for *indirect charges* (A charge type where customers transact directly with your platform instead of with a connected account. Indirect charges include destination charges and separate charges and transfers) on your account for your connected accounts - **Connected accounts**: Events triggered by resources that exist in connected accounts and some resources that exist in your account, such as: - `v2.core.account.*` events for v2 `Accounts` representing customers and recipients of your connected accounts - v1 `account.updated` events for both v1 and v2 `Accounts` representing customers and recipients of your connected accounts - *Direct charges* (A charge type where customers transact directly with a connected account, which is always the merchant of record. With each payment, the connected account pays fees to Stripe and, optionally, to your platform) for customers of your connected accounts > #### Event scopes for v2 Accounts representing connected accounts > > v2 `Account` objects trigger both v1 and v2 `Events`, which can have different scopes. For events triggered by connected accounts, v2 `Events` use the **Your account** scope, while v1 `Events` use the **Connected accounts** scope, even when triggered by the same v2 `Account`. > > The behavior of v2 `Account` events differs from that of v1 `Account` events, in that all events associated with v1 `Account` objects use the **Connected accounts** scope. The following table describes which scope to select when you create a webhook: | Event source | Event scope | | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Updates to v1 `Account` objects representing connected accounts | Connected accounts | | Updates to v2 `Account` objects representing connected accounts | - v2 events: Your account (scope changed from API v1) - v1 events: Connected accounts | | Updates to `Customer` objects representing connected accounts | Your account | | Updates to v2 `Account` objects representing customers of connected accounts that pay direct charges | - v2 events: Connected accounts - v1 events: Connected accounts | | Updates to `Customer` objects representing customers of connected accounts that pay direct charges | Connected accounts | | Updates to v2 `Account` objects representing customers of connected accounts that pay indirect charges created on the platform | - v2 events: Your account - v1 events: Your account | | Updates to `Customer` objects representing customers of connected accounts that pay indirect charges created on the platform | Your account | | Direct charges paid to connected accounts | Connected accounts | | Updates to `Invoices` and `Subscriptions` that connected accounts charge their customers using direct charges | Connected accounts | | Indirect charges created on the platform for customers of connected accounts | Your account | | Updates to `Invoices` and `Subscriptions` that customers of connected accounts pay using indirect charges created on the platform | Your account | | Direct charges created on the platform, including charges paid by connected accounts | Your account | To listen to v2 `Events` triggered by `Accounts` representing your connected accounts: 1. Open the [Webhooks](https://dashboard.stripe.com/workbench/webhooks) tab in Workbench. 1. Create a new event destination, or modify an existing one. 1. In the **Events from** section, select **Your account**. 1. In the **Events** section, select the v2 event types you want the webhook to listen to, then click **Continue**. 1. Select the Destination type and click **Continue**. 1. Complete the endpoint setup by following the interactive builder for the selected destination type. ### Account version differences in the Events v2 API Most `v2.core.account` event types don’t correspond directly to `v1.account` event types. For example, changing any property on an `Account` triggers a `v1.account.updated` event. However, the same action might trigger property-specific events for v2, such as `v2.core.account[identity].updated` or `v2.core.account[configuration.recipient].updated`. We send the `v2.core.account.updated` event only for updates to top-level properties, such as `dashboard` or `display_name`, that don’t trigger one of the more specific update events. ## Accounts API v2 limitations You must use Accounts v1 in the following cases: - Accounts connected using OAuth - Accounts that have signed a recipient service agreement - To request or manage the following capabilities: - `treasury` - `card_issuing_*` - [deprecated capabilities](https://docs.stripe.com/connect/account-capabilities.md?accounts-namespace=v2#deprecated-capabilities) such as `legacy_payments` - deprecated payment methods - payment methods in public or private preview > #### Cross-border payouts > > Use [Global payouts](https://docs.stripe.com/global-payouts.md) to send cross-border payouts.