# 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 v2 Financial Accounts.

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 <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.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 <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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

Accounts send both [v1 (snapshot) Events and v2 (thin) Events](https://docs.stripe.com/event-destinations.md#events-overview). We recommend setting up a new endpoint to listen for Accounts v2 events.

1. In your [Stripe Dashboard](https://dashboard.stripe.com), open the Developers menu by clicking **Developers** in the navigation menu footer, then select **Webhooks**.
1. Click **+ Add destination**.
1. In the **Events from** section, select **Connected accounts**.
1. Select **Show advanced options**. In the Payload style section, select **Thin**.
1. In the Events field, select one or more events corresponding to the `Account` object version:
   - For v1, type “v1” to search for v1 object event types. Select **v1.account.updated**.
   - For v2, type “v2” to search for v2 object event types. Select **v2.core.account.updated** or any other **v2.core.account[\*].updated** event.
1. Continue setting up your event destination by following the [interactive webhook endpoint builder](https://docs.stripe.com/webhooks/quickstart.md).

For example, updating an `Account` of either version can send:

- A v1 `account.updated` event
- A v2 `v1.account.updated` event
- A v2 `v2.core.account.updated` event

### 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.