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).

Recommended Pages and Workflow

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.

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",
  }
}