Redocly billing portal integration

This guide describes how to integrate an embeddable Rebilly billing portal into the Redocly environment.

Prerequisites

To complete this guide, you must have a website ID, an organization ID, a secret API key, customer ID, and a subscription order ID.

You must also have a payment gateway configured in your Rebilly account. For sandbox testing, the TestProcessor gateway is pre-configured.

Each customer can have one subscription only.

Mark other orders with the custom field excludeFromBillingPortal=true to remove them from the billing portal.

If you already have your IDs and API keys, continue to Integration. If you do not, create a customer, a subscription order, and get your IDs and API key in Set up your environment.

Integration

Set up the billing portal user interface

In this step you embed the Rebilly billing portal into your website.

Web component setup

Integrate the embeddable billing portal into any page in your application.

Install the library

Install the Redocly billing portal library using the following script and add it to your HTML file:

https://cdn.rebilly.com/billing-portal/@latest/main.js

Optional: portal theming

Optionally, override any Revel design tokens to theme the portal.

To update the theme after the web component is mounted, use document.querySelector('rebilly-billing-portal').updateTheme();.

Mount the web component

Obtain the customer's JWT using the billingPortalToken property from the Retrieve an order endpoint.

Add the rebilly-billing-portal tag to your HTML file and pass the customer's JWT token as the token query parameter in the URL of the page.

Optionally, you can pass the token as an attribute to the rebilly-billing-portal component instead.

<!doctype html>
<html lang="en">
    <head>
        <script src="https://cdn.rebilly.com/billing-portal/@latest/main.js" type="text/javascript"></script>
        <style>
            body {
                background: #000000;
                color: #ffffff;
            }

            rebilly-billing-portal {
                --r-surface: black;
                --r-text: white;
                --r-primary: #ff6d00;
                --r-font-family: "Trebuchet MS", "Helvetica", "Arial", sans-serif;
            }
        </style>
    </head>
    <body>
        <rebilly-billing-portal />
    </body>
</html>

Additional information

This section provides additional information and settings for the billing portal integration.

Report plan usage

Plan usage is displayed in the billing portal UI for the customer. To report metered billing plans usage, see Create a usage record. To report other plans usage, use the Update Subscription item endpoint and specify quantityFilled as an integer usage value. The quantityFilled value cannot be greater than the item quantity of the plan in the related order. For more information, see Update a subscription order item.

Usage limits can be set by the customer. The billing portal UI uses the Update an order endpoint to manage the customer's usage limits.

Subscription plans

Subscription change

When a customer makes changes to subscription plans using the billing portal UI, the Storefront Change subscription items endpoint is used. A quote is automatically created when a customer makes a change to their subscription — see Create a quote. When the invoice that is attached to the quote is paid, and the quote is fulfilled, changes are applied to the subscription. If recurrence restrictions are applied for plans, all items must have the same recurrence.

Subscription downgrade

If a plan change results in a subscription downgrade and the invoice displays a negative amount, a credit memo is automatically generated for the customer.

Trial subscription

When a trial ends, the subscription is assigned the "trial-ended" status. If the customer chooses to convert the trial to a real subscription, a trial conversion quote is generated. The process follows the same flow as changing subscription items.

When a customer changes subscription plans during a trial period, the changes become effective after an invoice is paid, and the trial continues until its original end date. If a customer changes subscription plans during the real subscription period, the changes are applied immediately after the invoice is paid.

The subscription-items-changed event is emitted when a customer makes changes to their order items and fulfills the quote.

Quote lifecycle events:

  • quote-accepted: Emitted when an invoice that was generated for subscription plan changes is paid.
  • quote-created: Emitted when a change subscription plans request is sent and a quote with an attached invoice is created.
  • quote-expired: Emitted when an invoice that was generated for subscription plan changes is not paid in 30 minutes and the quote expired.

Usage limit events:

  • hard-usage-limit-reached: Emitted when the usage of a subscription metered billing item exceeds the configured hard limit.
  • soft-usage-limit-reached: Emitted when the usage of a subscription metered billing item exceeds the configured hard limit.

Billing portal UI permissions

Customer JWT with billing portal permission is required to use Storefront Billing Portal endpoint.

In addition to the customer's JWT, the customer's subscription is also returned as an embedded object in the response. This is used to track the customer's selected plans within the billing portal.

Update theming

While overriding the default styles, any Revel design tokens can be used to theme the portal.

After the billing portal is mounted, changes to CSS variables are not detected. To trigger a style update call the updateTheme function.

updateTheme is exposed on the web component element and can be accessed by calling document.querySelector('rebilly-billing-portal').updateTheme();.