Redocly billing portal integration
This guide describes how to integrate an embeddable Rebilly billing portal into the Redocly environment.
Prerequisites
Complete these steps to create resources that are required to integrate the embeddable billing portal into your website. If you have already created these resources, skip to the Integration section.
To obtain your Rebilly API keys, see Manage API keys
Upsert a customer
This step creates or updates (upserts) a customer with a specified ID.
This operation prevents duplicate customers. If the customer already has an identifier within your system, that customer is updated. If the customer does not have an identifier, a new customer is created.
For more information, see Upsert a customer.
Interactive example
Create a subscription order
Each customer can have one subscription only.
Mark other orders with the custom field excludeFromBillingPortal=true to remove them from the billing portal.
This step creates a subscription order.
For more information, see Create an order.
Interactive example
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.jsOptional: 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.
Setup complete
You now have the standard setup of the Redocly billing portal.
- client/index.html
1<!doctype html>2<html lang="en">3 <head>4 <script src="https://cdn.rebilly.com/billing-portal/@latest/main.js" type="text/javascript"></script>5 <style>6 body {7 background: #000000;8 color: #ffffff;9 }1011 rebilly-billing-portal {12 --r-surface: black;13 --r-text: white;14 --r-primary: #ff6d00;15 --r-font-family: 'Trebuchet MS', 'Helvetica', 'Arial', sans-serif;16 }17 </style>18 </head>19 <body>20 <rebilly-billing-portal />21 </body>22</html>Set up billing portal notifications
This section describes how to set up billing portal notifications.
To provide updates without rendering the entire billing portal, use the rebilly-billing-portal-notification web component.
Web component set up
Integrate the embeddable billing portal notification web component 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.jsOptional: portal theming
Optionally, override any Revel design tokens to theme the portal.
Mount the web component
Obtain the customer's JWT using the billingPortalToken property from the Retrieve an order endpoint.
Add the rebilly-billing-portal-notification 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-notification component instead.
Add optional HTML
Optionally, you may add custom HTML to render within the notification. This is useful for CTAs or routing.
Setup complete
You have now fully integrated the billing portal notification web component.
- client/index.html
1<!doctype html>2<html lang="en">3 <head>4 <script src="https://cdn.rebilly.com/billing-portal/@latest/main.js" type="text/javascript"></script>5 <style>6 body {7 background: #000000;8 color: #ffffff;9 }1011 rebilly-billing-portal-notification {12 --r-surface: black;13 --r-text: white;14 --r-primary: #ff6d00;15 --r-font-family: 'Trebuchet MS', 'Helvetica', 'Arial', sans-serif;16 }17 </style>18 </head>19 <body>20 <rebilly-billing-portal-notification>21 <!-- Optional rendering to provide custom action -->22 <button>My custom button</button>23 </rebilly-billing-portal-notification>24 </body>25</html>Visual preview
Once setup, rebilly-billing-portal-notification will render one or more admonitions, as follows:
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.
Related webhooks
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.
Related endpoints
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();.