Basics

Boathouse API

We ensure integrating Boathouse is a simple as possible. There is one API call that you will make to get all the information you need to implement a "pricing" and "manage subscription" page in your software.

Calling Boathouse API

Send a JSON payload to the Boathouse API as follows.

HTTP POST to https://my.boathouse.co/api/v1
{
  "portalId": "xxx", // replace these values with
  "secret":"xxx", // those from your Boathouse dashboard
  "email": "[email protected]"
}

Alternatively if you already have the Paddle Customer ID you can also provide that.

HTTP POST to https://my.boathouse.co/api/v1
{
  "portalId": "xxx", // replace these values with
  "secret":"xxx", // those from your Boathouse dashboard
  "paddleCustomerId": "ctm_123"
}

Boathouse will return the following payload.

{
  "paddleCustomerId": "ctm_123",
  "activeSubscriptions": ["pri_123"],
  "oneTimePurchases": ["pri_123"],
  "billingPortalUrl": "https://my.boathouse.co/portal?c=xxx",
  "pricingTableHtml": "<div>...</div>",
  "success": true
}

The important values are:

  • paddleCustomerId: The customer ID from Paddle that corresponds to the email you provided. If the customer did not exist a record in Paddle was created, otherwise it will return the existing value. Store this along side your account information and use it in future calls to the Boathouse API.
  • activeSubscriptions: An array of Paddle price ids of any active subscriptions for this user.
  • oneTimePurchases: An array of Paddle price ids of any purchases of one-time products for this user (if activated for this portal).
  • billingPortalUrl: A pre-signed link to redirect your user to if they want to manage their subscriptions.
  • pricingTableHtml: A ready made pricing table showing all your available plans (with monthly/annual toggle if configured).

How you use these values is up to you but we recommend the following:

  • Create your "Pricing" page that calls the Boathouse API for the currently logged-in user and embed the pricing table returned (don't forget to add PaddleJS).

  • Create a "Manage Subscription" page that calls the Boathouse API for the currently logged-in user.

    • If the user does not have an active subscription embed the pricing table into the page (don't forget to add PaddleJS) and offer the user the opportunity to subscribe to a plan.
    • If the user has an active subscription redirect the user to the billingPortalUrl to manage their subscription.

Refresh page when checkout completes

Add another attribute to the PaddleJS on your "Manage Subscription" page that will refresh the page when the checkout has completed, allowing your page to call the Boathouse API again and ensure the subscription is active.

Paddle.Setup({
  token: "live_abc" // replace with a client side token generated in Paddle Dashboard
  eventCallback: (e) => {
    if (e.name == "checkout.completed") { location.reload(); }
  }
});

Adding Paddle Checkout parameters

Paddle supports a number of additional attributes to customize the checkout or add custom data to subscriptions. To add these to the pricing table checkout functionality add a paddleCheckoutOptions object. The properties align to the HTML attributes provided by Paddle, see their documentation for details on their functionality.

HTTP POST to https://my.boathouse.co/api/v1
{
  "portalId": "xxx",
  "secret":"xxx",
  "email": "[email protected]", // or paddleCustomerId
  "paddleCheckoutOptions":{ // optional and all properties of this object are optional
    "customData": "{\"text\":\"Boathouse\",\"number\":123}" // note this must be a valid JSON object with quotes around the properties!
    "theme": "light", // or "dark"
    "locale": "de",
    "allowLogout": "false",
    "showAddDiscounts": "false",
    "discountCode": "VOUCHER001",
  }
}

Custom data only applied on checkout

These checkout parameters only apply when a checkout is performed. The custom data is applied to the Paddle subscription object, not the customer object. No custom data is updated when you call the API, only when the checkout is completed by your customer.

Previous
Setup Paddle for SaaS