Integrating the customer portal

[Music] everyone who's built a sas application can tell you there are many moving parts you need a pricing page you need to keep track of your subscribers and their subscriptions you likely need a page to upgrade or downgrade between service offerings and a way to cancel so your customers obviously are going to have payment methods that are updated and all this is complicated further when dealing with secure customer authentication and provisioning so we're ecstatic to share the brand new customer portal which abstracts away a lot of this pain so welcome back to stripe developer office hours i'm cj a developer support engineer and i'm joined today by theo from the billing team at stripe who led the effort on this powerful new product uh as a reminder knowledgeable stripes are standing by to answer your questions live in chat today so go ahead and ask away so today theo is going to give us an overview of the customer portal and walk us through the dashboard configuration next we'll cover modeling your business correctly with products and prices after that we'll take an existing application with user auth and add a link so that customers can use the portal to manage their subscriptions and finally we'll update our webhook handler to automatically provision and de-provision access when customers make changes directly in the portal so hey theo uh you and the billing team have been hard at work to create this awesome new product can you give us just a quick overview of what the portal can do why someone might choose to integrate the customer portal rather than implement all these features themselves definitely thanks cj uh so as cj mentioned i'm theo i'm a product manager here at stripe and today i'm here to show you how you can cut down your integration time and time to launch your product uh with what we call the customer portal so you can see here that there's a ui that your customers can interact with where you can kind of let them change their plan cancel their plan change their payment method or see their billing history it's no secret that these are a lot of pieces of building a product that aren't necessarily going to differentiate your product but are things you just kind of have to build and so today what we want to do is show you how stripe can manage this for you so you don't have to do this yourself so let me walk through these features before handing it back to cj to talk through how to integrate the portal so in test mode in your stripe dashboard head over to your settings and then click on the customer portal to actually go configure your portal you can then customize the portal to your brand by setting up your brand settings and your business name [Music] and then you can see here you can actually choose to enable certain functionality in the portal such as allowing your customers to be their their billing history payment method updates will be auto allowed as long as subscription updates are allowed you can add products you want to enable a customer to switch to if you enable subscription updates and when your users actually make that switch you can choose to prorate that change and here you can see you can issue the invoice of that change immediately or at the end of a billing period same thing for cancelling subscriptions you do it immediately you can prorate it you can cancel at the end of the billing period so there's a lot of customizability here for functionality that your customers might might want to interact with at the bottom here you can see that you can customize the business information so you can actually add a headline you can add some links um you know you save this configuration and here you can now see a preview of the portal and so this is all kind of out of the box for you you don't have to to manage any of this yourself so now i'll pass it back to cj so you can take a look at how to actually integrate this awesome thanks so much theo uh all right cool let's let's jump in and talk about products and prices and how to model your business on stripe to take advantage of the new portal alright so you can now model your business and product offerings in one place products define what you sell prices track how much and how often to charge a product can be used for recurring or one-time purchases and it supports various business structures from tiers to usage-based billings and these are you know both core entities within stripe that work with subscriptions and invoices and checkout so i want to talk about products first as those are the highest level here products are what you sell and you'll need to create at least one before you can charge for it so when you're building a sas application like this one here with a you know sort of good better best model you might have three or at least three products a product for the good a product for the better maybe this pro and then a product for the best which is this this enterprise when each of the levels represents a different set of features or perhaps like increasing levels of service value now in the past i may have just created a single product at the very top level and then had multiple plans under that one product that uh for each of the service levels however in order to take advantage of the customer portal we'll need to ensure that we get this modeling correct from the get-go and it's also worth noting that if you have maybe like a setup fee associated with one of your plans or one of these levels that you want to create that as a separate product also so the api calls pretty simple to create a product we create the product by passing in its name and any optional arguments like description images or a url and in the response we'll get an id that we can then use to reference that product prices define how much and how often to charge for products this includes the product cost which currency to use and if it's a recurring price the billing interval so when we create a price we assign it to the product and specify the unit amount currency and you know optional interval so most businesses displaying this information on their website if the prices are hard-coded and you want to change them later the process is usually manual and requires you to go and deploy new code so to better manage these scenarios you can use this awesome new feature of prices called lookup key and the key allows you to swap out pricing without needing to change the hard-coded prices so you can render different prices in your front end and then use the rendered price to build the customers so the pricing page for today's demo was built using lookup keys and i highly recommend checking them out in the response we'll see the id of the price and we can reference the price from now on with the id of the price we can also list prices passing in their lookup keys and get back the list of prices with a given array of lookup keys so now that we've modeled our business and we can create products and we can create prices let's jump into the core of today's demo which is redirecting to the customer portal all right we're taking a look at the guide for integrating the customer portal there's four steps configuring the portal's features and ui which theo covered for us step two is to implement a redirect to integrate the portal with your application and that's where we're at now so let's jump into step two so the portal session is the entry point into your customer portal and there's going to be a unique short-lived link that we can send folks to for each session so what we want to do is add a button to our ui somewhere and then when clicked we're going to send a post request to some route on the back end where we will then take some action to create a billing portal session and redirect to the resulting you are uh to the resulting url uh so here this is really all of the all the code so we're going to create a button and then we're going to create a portal session redirect so we take a look at our our current ui um we are in the private podcasting dashboard where we're we're showing some private podcasts and we'll go through the whole sas application uh onboarding flow in a bit but here at the top we're showing welcome back to the authenticated user's email address we show their stripe customer id at the top and the status of their subscription and we show that they're subscribed to the pro level for for our sas product here what we want to do is we want to add a button to this view so we are in the episodes we're in the episodes index page here where we're showing the list of private episodes and this page is rendered inside of a layout a rails layout where we can add a button directly at the top for the dashboard we're going to add just a very simple button that when clicked we'll make a post request to our back end and on the back end we will create that customer portal and redirect so let's go take a look at our implementation here so jumping right into the database schema i want to show kind of what we've got going on so we have an email address we're tracking you know the hashed password the plan is actually the lookup key for our price we're storing the stripe customer id and also the subscription status which allows us to provision access so we can say this has been canceled or this is still an active subscription or not okay so then i have a couple of layouts here so within the views i'm going to look at the dashboard layout which is where we want to add our button so this is our welcome back text at the top that shows the email address and the customer id so we just want to add a button here that is going to send a post request to maybe customer portal sessions and we haven't created that route yet but we'll go do that and then here we'll just in the button text we'll say manage billing okay and i've already included this hidden input field with my authenticity token so that i can do csrf checking to make sure that we don't have any cross site request forgery so we have the button on the page if we go back and refresh we should see that button here manage billing and that's that's that's part one all right so now we've got to go make a route that matches this customer portal sessions thing okay so rails generate controller customer portal sessions and this is going to be the controller action or the the controller that will have our redirect okay so here we're going to use the code to create the billing portal session okay so the one thing that we're going to need and that's going to be a little bit unique depending on the application is we need to pull that stripe customer id out of the database so we need to pull this out of the database somewhere typically it's stored in the database it might be stored in you know firebase or some other external database but we want to pass the customer id for that authenticated customer so in in rails here i have it stored under the current user stripe customer id and then the return url we're going to specify as coming just coming right back to our local host for now okay so we've got a portal session here and the portal session has a property called the url and that's what we want to redirect to so in rails we can say redirect to portal session dot url and that will redirect us right to the portal now there's one other thing i need to do within rails and that is define the route so this is where we wanted this to go so resources customer portal sessions and we only want create here that's the only controller action that we're going to support all right now if we refresh this page now let's go back refresh the page click manage billing and that that's it we're we're in the billing portal we're seeing the portal as the customer would see the portal so here we're able to change our plan so we could toggle between you know monthly and yearly subscriptions if we wanted we could pick maybe pick pro we could confirm that change we could also go and you know update our payment method so if we wanted to we could add another card in here i'm going to use the the sca test card to show you that you know the the customer portal is fully sca ready and supports secure customer authentication so i can add a brand new payment method and in the future future invoices will use this new payment method that i've just added if you want you can switch back to that old payment method make that your default by just clicking there you can see your billing history here so you might see you know some older invoices that we could pay you can download as pdf super super handy and then we can also cancel so we could cancel our plan and that is going to you know sort of end the entire customer life cycle so if we go back to our demo here if we refresh the page we'll notice that we are still on the pro plan and we are still active so this is the next step we need to update our web hook handler to provision and d provision access based on actions that are being taken in the customer portal so we'll do that next okay heading back over to the integrating the customer portal guide we have completed step one and two we're headed down to step three to listen to web hooks to receive updates to the customer's subscriptions and payment methods so when subscriptions are changing they're either upgrading downgrading or being canceled we want to be notified of that so we can update our database so here we have a couple of different event types that we can listen to the customer subscription updated event and the customer subscription deleted events are the two types that we're going to listen to today but you might also want to listen to the payment method being attached or detached and also the customer.updated if you're curious which payment method the user would like to have as their default payment method so today what i'm going to do is grab these event types and we'll go update our webhook handler i wanted to quickly just point out that we have a couple great guides here so we have this these web hooks guides that will walk you through and show you full code examples for how to build web hook handlers we're going to start from something very much like the example here with sinatra we've implemented it in rails we also have a stripe developer office hours episode all about web hooks so if you're curious about how to implement web hooks or web hook handlers please go check out those resources so for now what we want to do is we want to make sure that we are provisioning access to the correct plan level or the the correct sort of product and then we also want to cancel subscriptions and remove access when the customer chooses to cancel their plan all right so i'm going to start up a stripe listener which is going to create a direct connection between stripe and my local machine so that when events happen on my stripe account they'll be delivered to the local webhook handler so we say stripe listen forward to host 3000 web hooks we have another developer office hours episode all about the stripe cli and how we can use this tool for testing and building web hooks if you're curious but i want to forward and make sure those events are being passed along to our local web hook handler heading back over to our rails application we're going to open up our webhook handler which is in the webhooks controller in the create method because we're receiving a post request from stripe here is the code for receiving the web hook and down here we have our logic for handling each of the event types we're already handling checkout session completed so we want to add a new handler for customer subscription updated and customer subscription deleted all right it's going to look something like this we're going to say when customer.subscribe or customer.subscription.deleted we can actually use the same logic in this case subscription is going to be the data that's inside of the event object and we're going to first find the user from our database by their stripe customer id which is going to exist on the subscription under the customer property again and the next thing we want to do is update that database so update the user object in the database to have the subscription status that matches the status on the subscription for the data that we received and also if we were upgrading or downgrading between plans we want to make sure that we're updating the lookup key which is stored under the plan field on the user inside of our database so user.update subscription status is going to be subscription.status and plan again this is going to be the lookup key so this is going to live inside of subscription items data key now this works because we're only using one plan per subscription or one price per subscription so we know that the subscription items on that subscription will be of length one so we can confidently reach in and grab out the very first item in this list and then its prices lookup key will be one of those pro starter or enterprise which we want to set an update on our plan so that we can give the right amount of access to the customer now if we receive a customer subscription deleted event this will actually work the same way so we want to grab the subscription find the user by the customer id and then we're going to update the subscription status to canceled because that will be the status of the subscription on the event data that we receive so we will be successfully we should be successfully cancelling that user's access and we'll we'll see and ensure that they aren't able to see any more episodes in our sort of paid service so we also have an existing event type that we're handling here for checkout session completed this is because our application uses stripe checkout in order to start the subscription so we are saying let's grab the session find the user again by their stripe customer id and then update it to active when we receive a checkout session completed because we're confident that at that point the subscription has started payment was successful etc so let's go let's go give this a whirl so if we come over to our application refresh the pricing page here we see you know this good better best so why don't we start off with starter we're just getting started here so for five bucks a month we will get started so we're gonna say jenny rosen at or maybe like five at example.com okay let's register be redirected to checkout we'll go through the checkout flow here with the 4242 card okay let's subscribe jenny to this starter plan when we are redirected back we should see that we have successfully handled that checkup checkout session completed event and we have the subscription is status is set to active and we can see that we are subscribed to the starter which is excellent so let's go manage our billing okay we're going to change our plan so we want to change from the starter maybe to the pro so let's go up one level here so we're going to confirm that change we are going to pay 12 dollars to to upgrade to that version all right now let's head back to the demo and see if we've updated our status successfully so we're still subscribed to the starter so if we refresh maybe we received the web hook and then pro so uh the web hook event delivery sometimes it can come super quickly sometimes it will come even before the page before your local client can refresh other times it might be delayed just a bit we always want to action based on those web hooks though because the retry logic that's built into web hook handling is very powerful so all right so now we've upgraded a pro we're still active let's try going all the way up to the enterprise version and then we'll we'll attempt cancelling so let's change our plan here we're going to be uh taking the next step so we're going to upgrade ourselves to the enterprise version where we're going to pay 29 a month for this paid private podcast situation okay let's head back to the demo and we are subscribed to enterprise okay so that's excellent it seems like we are able to upgrade let's try just downgrading once and then we'll cancel all right so we'll change our plan down to the starter oh actually i also wanted to show you that there are both monthly and yearly plans available and this is something that you can configure inside of your stripe dashboard under your portal settings what's really important here is that if you have a pro product then you might have two prices one is 17 per month and then one is 150 per year so your pro product represents the feature set that you're delivering with the pro level service but then you have two different prices one is the price point at the monthly recurring interval and one is the price point at the annual recurring interval so we have two price points there um okay the the annual prices don't have lookup keys that match our pricing plan so we're just going to stick with monthly for now and we'll click uh select on the starter and we're going to downgrade all the way back down to starter so we'll confirm that today and once we're downgraded then we want to move back to the demo okay so we'll go back to the demo and we are successfully downgraded excellent all right finally let's cancel this subscription so we're going to cancel our plan yes cancel the plan okay and again my settings for the billing portal say that i want to if if the user cuss or if the customer cancels through the portal then cancel immediately so let's go back to the demo we see it's canceled you can't see the episodes anymore that's kind of our logic for provisioning access if the subscriptions cancel we just don't show any episodes so that is the full walk that we were able to sign up upgrade downgrade and cancel we showed some how you might change your change your payment methods so super exciting stuff incredibly powerful all we did was really add a button and add one more event type or one more web hook handler for two different event types in order to provision and de-provision access really really powerful stuff a couple things that i wanted to point out before we wrap up here number one is that this stripe billing portal session uh class is pretty new so if you have stripe ruby that is uh you know maybe a couple even a couple months or even a couple weeks old you might want to upgrade to the latest stripe ruby version so that you get access to these new objects same with other client libraries so if you're using stripe node or stripe java stripe.net any of these you'll want to upgrade likely to one of the newer versions so you can get access to these helpful client library methods a couple other things yeah so the the links that are created here this billing portal session url that's created again is short-lived so you don't want to create this url and store it on in the database on the user uh because you know it's only going to last for a couple minutes so you really just want to create it redirect to it and then consider it kind of gone thanks so much for watching we're constantly striving to improve and one of the ways you can help is by providing feedback about this video in the feedback form below for more stripe developer content subscribe follow us at stripe dev on twitter and register for the monthly stripe developer digest on stripe.dev be well and we'll see you next time

Channel: Stripe Developers

Views: 31,899

Keywords: stripe, payments, billing, customer portal, rails, ruby on rails, ruby, stripe-ruby, Stripe Billing, Integrating the Customer Portal, Setting up the Stripe Customer Portal, How to setup the Stripe customer portal, Stripe Customer Portal, Stripe Billing Portal, Stripe hosted billing portal, Stripe hosted customer portal

Id: u8H6awDJVpM

Length: 24min 30sec (1470 seconds)

Published: Mon Jun 29 2020