Compare SaaS platform configurations for Accounts v1 and Accounts v2Public preview

Learn how a SaaS platform charges its connected accounts with Stripe Billing using Accounts v2.

SaaS (Software as a Service) platforms using Connect often charge subscription fees for providing their platform services. Accounts v1 requires platforms to maintain separate Stripe objects to enable a single business to both pay for a subscription (as a Customer) and operate on the platform (as an Account). Accounts v2 allows you to manage all your interactions with your connected accounts through a single, multi-configuration object.

The Accounts v2 API

In API v2, Account objects can have multiple configurations. Each configuration represents a different type of business relationship and enables different Stripe products. By assigning multiple configurations to an Account, a SaaS platform can enable both Connect and Billing for it without also having to create a Customer.

The Accounts v2 API provides:

Unified representation: A single Account object can represent multiple relationships between connected accounts and your platform.
Flexible configurations: Enable or change Stripe products and capabilities by changing the configurations assigned to an Account.
Centralised identity data: The Account object stores all of a connected account’s identity data. When you add a configuration to an existing Account, you don’t have to collect requirements that they already provided.

When looking at Stripe documentation, be aware of the structural differences between an Account in API v2 and an Account in API v1. For example:

In Accounts v2, some properties are part of an Account’s configuration or identity properties.
Accounts in API v2 associate functionality such as card_payments and stripe_balance.stripe_transfers with a configuration type.
In API v2, each requirement has its own status properties. In API v1, an Account includes arrays for each requirement status, and requirements appear in one or more of those arrays, according to their status.

The following table illustrates how some Accounts v1 properties map to Accounts v2 properties.

Accounts v1 property	Accounts v2 property
business_profile.url	identity.business_details.url
business_profile.support_url	configuration.merchant.support.url
business_profile.product_description	identity.business_details.product_description
Each requirement appears in one or more arrays, according to its status. requirements.currently_due requirements.eventually_due requirements.past_due	All requirements are in a single array. To check a requirement’s status, look at its `minimum_deadline.status`. Individual requirement status: requirements.entries.minimum_deadline.status Earliest due status: requirements.summary.minimum_deadline.status

Using Connect and Billing in API v1 with Accounts and Customers

In API v1, Account objects support only Connect features. To charge a connected account using a subscription, a platform must create a Customer object representing the same connected account. Accounts v1 and Customers v1 have no explicit relationship, so the platform must manage those objects separately and maintain a map of Account IDs to Customer IDs.

SaaS platform relationships with Accounts and Customers in API v1

Using Connect and Billing in API v2 with Accounts

With Accounts v2, a connected account that collects payments and pays you a subscription fee doesn’t require both an Account object and a Customer object. Instead, you represent it by assigning the applicable configurations to the Account.

To enable a connected account to collect payments from customers, assign the Merchant configuration to the corresponding Account.

Platform and Account with Merchant configuration

To enable the platform to collect payments, including subscription payments, from the connected account, add the Customer configuration to the Account.

Platform and Account with Merchant and Customer configurations

Note

You can collect application fees from an Account with the Merchant configuration. Assigning the Customer configuration to it doesn’t affect that ability.

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.