Getting started

In this guide we'll look at how simple it is to add Boathouse to your web app to give your user's a way to purchase a plan and then manage that subscription.

This Getting Started guide is also available as a video tutorial on YouTube.

Assuming you’ve already setup your Paddle account (we recommend a sandbox account for testing) the first thing you’ll need to do is connect Boathouse to Paddle. If you don't have a Paddle account yet, check our guide on setting up Paddle for SaaS.

1. Connecting to Paddle

When you create a new Boathouse account you'll first be prompted to connect to Paddle using a Paddle API Key.

Paddle API Keys allow add-ons to connecto to your Paddle Account to read data. You can access your API keys in your Paddle Dashboard from the “Developer Tools” > “Authentication” section (Link for Production / Link for Sandbox).

By default you have a "Default" API key but it's recommended to create a seperate key for every service that connects to Paddle.

2. Setup your Pricing Tables

Paddle let’s you specify some basic information for each subscription plan, but you will likely want to show a lot more details on the pricing tables for your product. In Boathouse you can add more information to each plan which will then be used when generating your pricing tables.

Note: One common feature you might want to add is a free plan which you won’t add to Paddle. In Boathouse you can add a free plan that is not linked to any Paddle plan but still displayed like one.

In the “Plans and Pricing Tables” section of Boathouse, simply add all the plan variants to your pricing table.

Note: You only add the base plan (i.e. the monthly plan) but not the annual option. So if you have a Free, Pro and Premium plan (with the latter two having monthly and annual options, you just add 3 plans. And then in the next step we will configure the annual plan for each plan in the Customization.

For each plan you can click on "Customize" and adjust the displayed name, description and add features. You will see a live preview of any changes.

If your base (i.e. monthly) plan has an associated annual option, select that at the bottom.

3. Add the pricing table to your website

The Boathouse pricing tables has two modes (but both display the same information you configured in your Boathouse account):

The anonymous (public) pricing table

This will show your plans and redirect users that want to subscribe to your “Create Account” page. You can simply add this using the IFRAME snippet which almost all CMS and Website builders support.

Note: Replace the CREATEACCOUNTURL link with the link to your create account page (fully qualified and URL encoded).

Authenticated pricing table and checkout

This is shown to users on your upgrade page and requires passing in either the email (or a Paddle Customer ID). When the users click on “Subscribe” a Paddle Checkout will open for the users to pay for the subscription. We will add that to a sample web app in the next section.

4. Add the checkout and billing page to your web app

In this tutorial we will create a simple single billing page to handle both the checkout and billing management. This example will be shown in ASP.NET but uses a server side language and HTML template which is supported in most web stacks. Contact us if you’re having any issue and we will try and provide an example.

Note: Advanced users may want to change the logic to fit their app or stack. The core of the implementation is the call to the Boathouse API that will give you the information you need to customize your user flow.

Disable Caching

First off for any implementation of the billing page make sure to disable any form of browser or server caching. Boathouse will always give you the most up-to-date information it gets from Paddle which you want to show the user. You can call the API as often as you want, we will handle the caching.

Check for a Paddle Transaction Parameter

In some scenarios (e.g. update payment method) Paddle will redirect the user to your web app instead of hosting the UI themselves to ensure the experience is consistent with what your user expects. The URL Paddle will use is defined as the “Default Payment Link” in your Paddle Dashboard under Checkout Settings" (Link in Production / Link in Sandbox).

This “Default Payment Link” needs to point to a page that has PaddleJS embedded (the Paddle library that handles the Checkout) which the billing page that we are creating does, so we are simply going to check for a query string parameter (_ptxn) and show the page without any logic (thus loading PaddleJS and triggering the Paddle feature). Of course you can implement that as a seperate page if you want.

The “Checkout” parameter

When the Paddle Checkout completes we are going to redirect to the same page in order to run our logic again (check for the subscription status using the Boathouse API). But we are going to add a checkout parameter to the query string in order to delay the rendering by a few seconds.

This is necessary in order to allow Paddle to process the payment and add the subscription to the customer’s account. (Otherwise the API may return a value indicating there is no active subscription for the user even though they are still being processed.)

Call the Boathouse API

Calling the Boathouse API is a simple HTTP POST request with a JSON payload.

You need to add four parameters. The first two portalId and secret are available on your Boathouse configuration page:

The second two are the user’s email address and if you have it the Paddle Customer ID.

If you only pass the email, Boathouse will check to see if there’s a Paddle customer with that email and return the ID to you or create a new customer in Paddle and return that ID to you.

Note: You should always store the Paddle Customer ID that Boathouse API returns in your database and add it to any future call to the Boathouse API, because the Paddle Customer ID is permanent and will survive any account email changes. Otherwise changing the account’s email address would cause the account’s subscription status to be reset until you manually match the new email to the previous Paddle account.

Handle the Subscription Status

The Boathouse API will return an array of subscriptions the user has paid for. The returned ID will be the Price ID in Paddle, so you can identify which plan the user has subscribed to.

Note: In our example we only have a single Pro Plan and the monthly or annual version both activate the same feature set, so we don’t bother checking the Price IDs.

Case A: The user has just upgraded

In this case our database shows the pro features are not enabled, but should be. So we activate them and redirect the user to a the root page of the app (or if you like you can send them to a specific upgrade welcome page).

Case B: The user has upgraded in the past (is an active subscriber)

In this case we simply redirect to the hosted billing page that the Boathouse API returned. This page will allow the user to manage their subscription, change the plan and update their payment information.

Case C: The user is still no the free plan (has not upgraded)

In this case we just show the page where we will embed the pricing table and checkout in the next step.

Embedding the Pricing Tables

In the actual HTML template you first add the HTML that the Boathouse API returned. This renders a pricing table to the page with a monthly/annual switcher (if you have configured annual plans).

Then you add PaddleJS to the page, making sure to set the environment if you are using a sandbox account, setting the correct client token and adding the event handle that refreshes the page when the checkout completes.

Handling Cancellations

In order to deactivate the pro features if the user has cancelled, simply call the Boathouse API as part of your login flow and deactivate the feature is the “activeSubscriptions” does not contain any value any more.

That's it!

You now have a full fledged checkout and billing management for your SaaS or web app.

Want to see what else Boathouse can do for you, check out these links or browse our help site.

Need any help?

You can reach us via email at help@boathouse.pro or directly schedule a call here.