Migrate to Accounts v2 or back to Accounts v1Public preview

The Accounts v2 API allows you to represent your connected accounts and customers as single configurable entities on Stripe. It combines Accounts v1 and Customers v1 functionality in a single API.

Migrate to Accounts v2 from Accounts v1 and Customers v1

If your existing integration uses either Accounts v1 or Customers v1, you can transition to using the Accounts v2 API to create new accounts. These account objects can represent both connected accounts and customers.

To update your integration to use Accounts v2 for new accounts and customers:

1. From the Settings > Product Previews page in your Dashboard, enable Accounts v2 to opt in.
2. Acknowledge the following Accounts v2 behavior:
   • You retain access to the Accounts v1 and Customers v1 APIs, and any existing Accounts v1 and Customers v1 objects persist following enablement.
   • Stripe interfaces like the Dashboard, Checkout, embedded onboarding, and hosted onboarding default to creating Accounts v2 objects instead of Accounts v1 or Customers v1 objects.
   • API documentation defaults to Accounts v2 content. You can still access Accounts v1 and Customers v1 documentation.
   • Treasury and Issuing don’t support Accounts v2 objects. You can still use Treasury and Issuing with Accounts v1 objects.
3. Update your integration to use the Accounts v2 API. You can’t reference Accounts v1 or Customers v1 objects in Accounts v2 endpoints. After you migrate, you must either:
   • Create Accounts v2 objects to replace your existing Accounts v1 and Customers v1 objects.
   • Update your integration to call API v1 endpoints for Accounts v1 and Customer v1 objects, and API v2 endpoints for Accounts v2 objects. You can reference Accounts v2 objects in certain API v1 endpoints, but when referencing an Account representing a customer, use the customer_account parameter instead of the customer parameter.

Migrate to Accounts v1 and Customers v1 from Accounts v2

You can migrate back to using Accounts v1 and Customers v1 by opting out of the Accounts v2 public preview.

To update your integration to use Accounts v1 and Customers v1 for new accounts and customers:

1. From the Settings > Product Previews page in your Dashboard, disable Accounts v2 to opt out.
2. Acknowledge the following opt-out behavior:
   • You retain access to the Accounts v2 API, and any existing Accounts v2 objects persist following opt-out.
   • Stripe interfaces like the Dashboard, Checkout, embedded onboarding, and hosted onboarding default to creating Accounts v1 and Customers v1 objects instead of Accounts v2 objects.
   • API documentation defaults to Accounts v1 and Customers v1 content. You can still access Accounts v2 documentation.
3. Update your integration to use Accounts v1 for connected accounts and Customers v1 for customers.
   • You can use the acct_xxxxx ID from your Accounts v2 objects in the Accounts v1 API to retrieve or update the account. You can also pass it to API v1 endpoints in an account parameter.
   • You can’t use the acct_xxxxx ID from your Accounts v2 objects in the Customers v1 API to retrieve or update the Customer v1 object. However, you can still pass it to API v1 endpoints in a customer_account parameter.

Preview considerations

Accounts v2 allows you to use a single, configurable account for each business on your platform that collects payments directly. The preview release doesn’t support Treasury, Issuing, or payment methods that are in preview. You can still use Treasury, Issuing, or payment methods in preview with Accounts v1.

Enable Accounts v2 for your Connect platform from your Dashboard.