KATELYN STEIN: Today we released Accounts v2, our next-generation user-representation API. We've reimagined how you can model a complex business on Stripe. We'll walk through building an integration using the new API, and we'll explain the new concepts along the way. Then we'll talk about how you can upgrade an existing integration to use the v2 API. And finally, we'll wrap with a preview of what's to come. Let's jump in. 

A complex business like a SaaS platform makes money through multiple revenue lines. Typically, this includes charging a subscription fee for using their software and taking a cut for services, like processing payments. This is a really common setup. It's how thousands of platforms on Stripe monetize. Let's build a platform like this together. We're going to build a platform for pet salon owners to manage their businesses. Let's call this app Furever. 

Furever's users—pet salon owners—will enable their users—et parents—to schedule appointments and pay for them. Let's say that Furever gets their first user, a salon called Angela's Animals. Angela will sign up to use Furever, and the first thing they'll do is charge her their subscription fee. That's their first revenue line. Then, Furever will enable Angela to accept payments for her appointments. That's their second revenue line. Until now, modeling a business like Angela's on Stripe required two different user-representation APIs.

Angela needed to be a customer in order to charge her, and she needed to be an account in order to enable her to accept payments. And this has a lot of problems. Multiple APIs means separate IDs for each resource and duplicating data like Angela's name and address across them. It also means Furever would need to build their integration to work with both APIs, and they would have to use separate Stripe Dashboard views to manage Angela's business. 

We've designed Accounts v2 to solve these problems in a first-class way. We've combined the customer and the account to form the Account v2. A platform like Furever can build their entire integration using this single-user representation API. So now let's take a closer look at the API together. An account v2 represents an individual or a company that Furever is doing business with. At the top level, we can see Furever's unique ID for Angela that they'll use throughout their integration. 

From there, the API breaks down into three core components. First, there's who Angela is—this is the identity. Then there's what Angela wants to do—these are the configurations. And last, there's the data we need to collect to enable her to do what she wants—these are the requirements. And now let's go to Rod's screen, and he will help us build Furever's integration. 

ROD HOWARTH: Cool. So the way I'm going to do this is by taking Furever's API key and making API requests on their behalf. I'm going to use cURL in my terminal to simulate the kind of calls that you would expect them to make in their own application code. 

So to get things started, let's imagine that Angela is going through onboarding for the Furever platform. She's about to be asked to pay the $10-a-month subscription fee. To get that started, we'll first need to create a v2 account to represent Angela. 

KATELYN STEIN: So Rod is creating a v2 account and requesting the customer configuration. He's supplying information about Angela that she would have given in Furever's onboarding flow. 

ROD HOWARTH: So adding a configuration to an account enables it for use in a set of associated product flows. The configuration object itself contains the settings that relate to those flows. We've added the customer configuration to Angela's account so that she can make payments. And so at the top level here, we can see that this information is unique to the relationship between these two parties. We can see things like the contact email and the display name. You can kind of think of this as the address book entry for Furever. 

Most importantly, though, is this account ID. Furever would take this ID that was stored in their system and they would use it throughout the codebase whenever they need to call Stripe's API. I'm going to take a copy of it now and use it throughout the demo. 

KATELYN STEIN: So now let's take a closer look at that configuration. Configurations represent the personas an account can take on. This is a really important concept and, in fact, the most important difference from V1. 

ROD HOWARTH: So if we look at the configuration that we added, we can see that it contains the kind of settings that you might otherwise expect to see on the customer's v1 API. So things like the default payment method and the prefix for invoices that Angela receives. We've put them here under the customer configuration now. You can also see that there's this capabilities hash. Capabilities are a special kind of setting that unlocks specific product flows, but only after you've met certain requirements. We've requested the automatic indirect tax capability because we'd like Angela's account to be set up so we can automatically calculate the tax on her subscription fees. 

We can see that it's currently restricted because there's requirements that are past due. We'll come back to that. So for now, we've only added one configuration to Angela's account, but the key benefit of the Accounts v2 API is that we can add multiple configurations at the same time. This is what really allows it to be the single API to represent your users on Stripe. We're launching with three configurations—customers, which allow an account to make payments, merchants, which allow an account to receive payments from others, and recipients, which allow an account to receive funds from others. 

Instead of having three different APIs for these three different use cases, we've modeled them as configurations that you add to an account. So all you need to do is create a v2 account and add the multiple configurations, and you'll be ready to go. 

KATELYN STEIN: Next, let's take a closer look at the identity. The identity contains real-world facts about Angela's business. This is another key concept. 

ROD HOWARTH: So we've requested the account with the identity included, and we can see that the response contains this hash, which is a place to store structured information about Angela's seller. This is where we put things like the company name, address, tax IDs, ID documents, etc. So while the configuration contains the kind of settings that remain the same across—the kind of settings that are unique to individual products, the identity contains the kind of settings that remain the same across all product flows. By storing them here, we're able to reuse them as we add more and more configurations to an account. 

This is another key change from v1. We've taken the multiple different APIs that might otherwise collect information about Angela's salon and unify them under Accounts v2. Furever just needs to collect this information once, and then it'll be reused as they adopt more and more of Stripe's products. 

KATELYN STEIN: Next, let's fetch the requirements for this account. Requirements contain the data we need to collect in order to activate capabilities. 

ROD HOWARTH: So requirements are a concept that's returning from Accounts v1. 

In Accounts v1, requirements were arrays of strings that pointed you to the fields that you needed to collect to finish onboarding. But what we heard from platforms was that they needed more information about each individual requirement. Things like when it's due, why we've asked for it, and what it impacts. To address this, we've introduced this hash-based structure for each individual requirement in Accounts v2. If we have a look at the response here, we can see the requirements' entries contain one entry at the moment, which is Angela's address country. 

We can see that we requested this because of the automatic indirect tax capability, which is currently restricted because the information is past due. Finally, we can see that we're awaiting action from the user, which means that the next step is for Furever to collect this information to continue onboarding. 

KATELYN STEIN: So let's supply the address. Rod is doing that now by updating the account identity. 

ROD HOWARTH: So we've asked Angela for her salon address, and we supplied it via the API. Now that supplying the full address resolves the address country requirement, and as a result, the automatic indirect tax capability has come back as active. We can also see there's no more entries left to collect in the requirements. So this gives you an idea for what an API-based onboarding flow might look like. You create an account v2, you apply the configurations, tweak any settings, request capabilities, and then use the requirements to guide you through onboarding. 

KATELYN STEIN: And you may have noticed that each time Rod retrieved the account from the API, the response looked different. That's because Rod's using an include parameter in his API calls. The include pattern is new, and allows you to specify exactly what you want to see in the response. 

ROD HOWARTH: So in Accounts v1, we found that users really enjoyed being able to configure a lot of things about an account in a single request. But the flip side of this is the API responses can get quite large, slow to render, and intimidating for new users. With Accounts v2, our design challenge was how do we add even more functionality to the API while also making it easier to reason about? 

So that's where the include pattern comes in. With the include pattern, we've divided up the API into logical components, things like the configurations, requirements, and identity. And every time you make a request to the API, you specify what you would like to see returned in the response. So this gives you the flexibility to work with different pieces of the API. You can request them all at once, or just certain individual components. You choose what you want to see in the response. 

KATELYN STEIN: Now that we've got the basics of the API, let's see what it looks like in the Dashboard. 

ROD HOWARTH: So if we head over to the customers list, we can see Angela's Animals is now visible here. We can see that on the right, there's some of the information that we collected earlier via the API, and we can see the configurations show that there's one customer configuration added. Finally, if we go over to the Workbench—and for those of you that don't know, Workbench is our hub for developer activity in the Dashboard—if we go check that out, we can see some of the events that we've created. We can see that, so far, these are the events that have been firing as we've been making our requests in the terminal. Now, with Accounts v2, we've divided up the events into more granular, thin events. So this is using Stripe's new thin-event style of events. And what this allows you to do is listen to specific parts of the API in your webhook handlers. 

Whereas Accounts v1 had one giant event for all updates to an account, the Accounts v2 is divided up so that you can build your webhook handlers to match your needs. Additionally, we've expanded the include pattern to work here as well. So we can see here that as we've been making our requests, there's requirements of updated configuration customer identity, and they have this square brackets convention around them. This tells you that it's an includable part of the API. 

Finally, if we go to the logs, another thing that's interesting to point out here is that every time you see an account ID, we annotate it with the tag of the configurations that are added to the account. And so right now, we've only added the customer configuration, and so that's showing up here. 

KATELYN STEIN: Now that we've got an account set up for Angela, the next thing Furever wants to do is charge her their subscription fee. Rod is heading over to the product catalog in the Dashboard, where we can see that we already have a $10-a-month fee set up. Furever enables Angela to pay this fee via credit card. 

To do that, Rod will use the Setup Intents API to create a payment method for Angela's card for future payments. Once he's got that payment method, he can grab the ID and use it to charge a subscription. The Setup Intents subscription APIs are existing Stripe v1 APIs. We've built Accounts v2 to be fully interoperable with all existing Stripe v1 APIs. 

ROD HOWARTH: So for APIs that accept a customer, the way that we've made the v1 APIs work with Accounts v2 is by adding this new customer account property. That customer account property accepts a v2 account ID, but only if it's been configured as a customer. So these APIs will continue to work with a customer's v1, but now they also support Accounts v2. 

KATELYN STEIN: Now that Angela has paid her subscription, the next thing Furever wants to do is enable her to accept payments for her appointments. As we discussed earlier, in v1, this would mean creating a completely fresh representation of Angela in the v1 Accounts API. 

But with Accounts v2, all we need to do is add a merchant configuration to Angela's account, and she'll be all ready to accept payments. So now Rod is hopping back to the terminal, and he is creating—he's adding a merchant configuration to Angela's existing account and requesting the card payments capability. 

ROD HOWARTH: So adding this merchant configuration allows us to accept payments on Angela's behalf. And the settings that are in that merchant configuration are the things that relate to that. So for example, we can see the colors to use on her checkout page, her merchant category code, and a statement descriptor. 

Additionally, we can see the capabilities here. There's a lot more capabilities on the merchant configuration than there was on the customer configuration. In fact, there's one for every payment method that Stripe supports. This is very similar to Accounts v1. So what we've essentially done is take those capabilities and put them under the merchant configuration. We can see that, at the moment, we've only requested the card payments capability, and it's currently restricted because there's missing requirements. 

Additionally, we can see that we've been automatically given the Stripe Balance Payouts capability. Now, the reason for this is that every time you create an account and request a merchant configuration, we provision you with a balance to store your payments funds in, and those funds need to be paid out. The Stripe Balance Payouts capability communicates that status. 

KATELYN STEIN: Let's check out Angela's merchant configuration in the Dashboard. 

ROD HOWARTH: Cool. So we can see on the connected accounts list that Angela's Animal shows up here. This is our existing connected account details Dashboard that we've updated to support Accounts v2. Again, we can see that the information we collected by the API is visible here. We can see the Configurations widget once again shows up on this screen. This Configurations widget tells you that there's more configurations than just the one you're looking at on the account. And so we can see that it also has the customer configuration. 

If we scroll to the top, we'll see the requirements that are outstanding that we need to collect in order to activate card payments. Now, Furever will need to collect this information, but one key part of the accounts API is that we were able to reuse the information that we collected earlier to proactively resolve some of these requirements. So if you recall earlier, when we were setting up Angela as a customer, we collected her business address. And normally, that would show up on this list, but thanks to the reuse of the identity, we were able to resolve it. 

KATELYN STEIN: This is a really, really key benefit of Accounts v2. We're configuring Angela to use a completely different part of Stripe's product suite, and we're making it much faster and easier to do so by reusing information we already know about her. So Furever could choose to collect all of these requirements using our embedded onboarding form directly in their app. 

Rod is showing us an example of this here. While we really highly recommend that approach, here we'll use the API for demo purposes. So Rod's applying all the remaining requirements to get the card payments capability activated for Angela. Stripe will begin verifying this information in the background. 

ROD HOWARTH: Cool. So we've imagined that we've collected all the information from Angela and supplied it by the API, and so that's enough to get card payments active. But to get payouts activated, we need one more thing, which is a bank account to pay out the funds to. 

KATELYN STEIN: To better support Accounts v2, we've created new top-level v1 APIs to manage your external accounts and automatic payout settings. Here, Rod is using the new External Accounts API to set up a bank account for Angela's payouts. 

ROD HOWARTH: So for those of you that have used the existing External Accounts API, you'll probably notice that the API response looks very similar. So one of our principles when we were designing Accounts v2 is that we didn't want new users who are working with only v2 accounts to have to think about v1 customers or accounts. And the existing external accounts API is attached to the v1 accounts API. So what we've done is we've made it a top-level API primitive. 

And so now you can see the route is v1 external accounts. And the way we access it is the way we access other resources that Angela would own, which is via the Stripe account header. So while existing users can continue using the existing v1 Accounts-based external API, external Accounts API, we believe that new users will find this more ergonomic. 

KATELYN STEIN: Now, Angela is all set up and ready to accept payments. So let's say she does her first dog haircut, and she charges the pet parent $100. Furever would collect the payment information, and they would run a charge using the v1 Payment Intents API, which Rod's doing here. 

ROD HOWARTH: So this is an example of an API which currently works for Accounts v1 that we've also made for work for Accounts v2. And again, we're using a Stripe account header here. And so the key thing here is that we can pass in Angela's v2 account ID to this existing v1 Payment Intents API to say that we'd like to make a charge on her behalf. We're able to do that because we've configured her as a merchant.

KATELYN STEIN: We can use this same approach to read Angela's Stripe balance. Rod's doing this now, and we'll see that her balance is the $100 that she collected for the dog haircut minus network costs and the cut that Furever takes. 

ROD HOWARTH: So again, we're using the Stripe account header here, and we're passing in the v2 account ID that we stored earlier to read her balance. Cool. 

KATELYN STEIN: So we saw how we can use Accounts v2 in existing customer and merchant flows using these existing v1 APIs. In fact, we used five different v1 APIs using Angela's single v2 account ID. A way to think about this is we're releasing a new and improved version of the account's API—we're merging in the customer's API. Anywhere you would use an account v1, you can use an account v2 configured as a merchant. Awesome. And that is not all. [Laughs] I forgot the really cool thing I was about to tell you. That's not all. 

So using the power of v2, we were able to introduce completely new on-network money movement, like actually paying that subscription fee directly from the Stripe Payments balance. This allows you to save on network costs and collect subscription fees with an instant payment method. So let's go back to Rod's screen, and he's going to show us how we can actually update Angela's existing subscription to pay from her balance instead of a card. He's using the Setup Intents API again to create a payment method for Angela's Stripe balance. Once he's done that, he can use that to charge the existing subscription. 

ROD HOWARTH: Sorry, one second. Okay. So what we've done here is we've used the Setup Intents API again with the customer account parameter to say that we're creating a payment method on behalf of Angela. The difference here is that we're saying the payment method type is the Stripe balance. And so this means that the funds come from the Stripe balance. 

Paying with the Stripe balance is a really great example of what Accounts v2 can do. Because we've combined the customer and the merchant under the same object, we're able to unlock really exciting new flows like this. 

KATELYN STEIN: Let's see what this looks like in the Dashboard. 

ROD HOWARTH: So if we scroll down to the configuration section again and follow the link over to the customer, we can see that Angela's Animals has the subscription here. If we click into it, we can see it's now been updated to pay with Stripe balance. So what this means is next time the subscription is renewed, Stripe will automatically deduct the $10 from Angela's payments earnings instead of her credit card. 

KATELYN STEIN: Everything we just showed you is available now in public preview. A brand new integration can be built using the Accounts v2 API as your single-user representation. Next, let's dive deeper into how we will allow existing integrations to use the v2 API. 

ROD HOWARTH: So today we saw how our existing v1 APIs can work with v2 accounts. But what if Furever already had an integration that used v1 customers or v1 accounts, and they wanted to start adopting Accounts v2? How would they go about that? Well, right now they can use those two APIs side-by-side. They can use their existing v1 APIs for their existing users and start onboarding new users as v2 accounts. But later on this year, we're going to be expanding this to have the ability for them to take their existing customers' accounts and use them all with the v2 accounts API. There will be mappings for the v1 fields in v2, and they can go back and forth between these APIs. 

To give you a look into what this will look like, let's dive deeper into how we've designed the interoperability with v1. So earlier today when we created a v2 account and configured it as a customer for Angela, what we actually did behind the scenes was create a linked v1 customer automatically. And we saw that we didn't need to care about this at all. So we just used v2 accounts with the customer account parameter, and we never even need to think about the existence of that v1 customer. 

But if Furever already had an existing integration that relied on v1 customers, they'd see that at that moment, we actually created a new one behind the scenes. They'd see that it was related to the v2 account because it has a new customer account property that links them together. Let's take a look at that. 

KATELYN STEIN: So we'll go back to Rod's screen, where he's hopping over to Angela's customer view in the Dashboard. And we'll see that the account we created for her earlier has this v1 customer ID. If Furever had some part of their system that still needed to read from the v1 customers API, they could do this using that v1 customer ID, which Rod's doing now. 

ROD HOWARTH: Cool. So we've pulled the automatically created v1 customer and retrieved it via the v1 customers API. We can see the customer account property that I mentioned earlier, pointing to Angela's v2 account ID. And we can see that some of the information we collected via the v2 accounts API is now exposed here. And we can even update this information. 

KATELYN STEIN: Updating the v1 customer will automatically also update the account v2. So let's say Angela moves her salon and she has a new address, but Furever's subscription settings form is still writing to the v1 customer's API. They could take that ID that we had earlier and make the address update on the v1 API. Rod's doing this here, and we'll see that the v1 customer was updated. Then we can go ahead and fetch the v2 account. 

ROD HOWARTH: Cool. So we've set a new address via the v1 customers API, and then when we pull the v2 account, we can see that it's updated there as well. So if we head back to the slides, we'll see that a similar concept applies for merchants. When we added the merchant configuration to the v2 account earlier, what happened behind the scenes was we created a linked v1 account. The key difference here, though, is that v1 accounts and v2 accounts share the same ID. We consider them both to be the same logical account, and Accounts v2 is essentially an updated version of Accounts v1 with expanded functionality. So let's take a look at that in action. 

KATELYN STEIN: So let's say Angela moved her salon again, and she has another new address. This time, when she tells Furever about it, their payment settings form is still writing to the v1 Accounts API. In this situation, Furever can use the same account ID for Angela's v2 account and v1 account, and make the update on the v1 API. Rod's doing this here and we'll see the address was updated on the v1 account, and then we can go ahead and fetch the v2 account. 

ROD HOWARTH: Cool. So again, new address, updated via v1 API, and this time, we're passing in the v2 account ID into a v1 account's path. Again, that's because they share the same ID. The address was updated there, and we can retrieve it in the v2 API and see it's updated. So what we're really doing here is exposing different views on the same underlying data. Now, for most people, this is just an implementation detail that they won't need to worry about. But for Furever, with their existing integration, it'll come in really handy when they look to update everything to use Accounts v2. 

The way that we'll do that is we'll go through all of their existing v1 accounts, create a v2 account with the same ID, link them together, and then at that point, they'll be able to go back and forth between these APIs as they upgrade their integration piece by piece. They'll have the flexibility to slowly adopt v2 where it suits them without it being a one-way street. 

KATELYN STEIN: So let's go back to our slides. We'll be releasing this ability to use Accounts v2 with your existing customers in Accounts v1 later on this year. In fact, we have a whole roadmap of new functionality lined up throughout the year. In addition to support for existing integrations, we'll also be releasing more configurations. Future Stripe products and features will be built with v2 support out of the box. We'll build more configurations for new personas, and we'll update existing configurations as needed. 

This means choosing to build on v2 will set you up best to grow with us as we expand our offerings. Now we're going to go back to Rod's screen, and he's going to show us one more thing. We're really excited about this. It's called Blueprints, and it's a step-by-step guide to building your integration, similar to what Rod did today with cURL. 

ROD HOWARTH: Cool. So if we go back to the Workbench and we check out the Blueprints section, we can see there's this subscriptions and embedded payments Blueprint. And what this allows us to do is go through a step-by-step workflow similar to what we did today. There's different steps for different parts of the demo, and you can run them all inside the browser. 

When you run them, they'll create real API objects. On the right, you can see the kind of application code you need to write to make the same call, and you can even customize it for your programming language. So this is a really, really great way to get quickly started with the Accounts v2 API. 

KATELYN STEIN: Accounts v2, our next generation user representation API, is available now. Today we demoed how you can create a v2 account with a unified identity, you can add configurations for various personas, and you can supply requirements to activate capabilities. 

A complex business like a SaaS platform with multiple revenue lines can model their entire business using this single user representation API. Check out this QR code to see our docs and dive deeper. From there, you can even opt in to give the API a shot. We can't wait to see what you build.