Hosted Self-Serve PortalIntegrate Portal

Integrate Portal

Last reviewed: 17 November 2026

The self-serve portal is a web component you embed on your own website. Customers manage their subscriptions in it. There are two ways to sign them in.

Before you start

Turn the portal on for the product in Settings > Hosted Pages (see Configure Portal). When it is off, the portal sessions API, the email code check, the account choice and the portal itself answer “The portal is turned off for this product.” A request for an email code still gets the usual “we have sent a code” reply, but no email goes out. Customers already in the portal go back to the sign-in screen with that message.

Get the embed code

Open the merchant portal, go to the Self-Serve page and choose Add to your site. It shows the snippet for each way below, filled in with your product and script URL.

Use this when customers already sign in to your app. They never see a second login.

  1. On your server, call the portal sessions API after the customer signs in:
POST /portal-sessions
x-api-key: <your Full-Access API key>
Content-Type: application/json
 
{ "productId": "<product ID>", "accountId": "<the customer's account ID>" }

The reply is:

{ "token": "<session token>", "expiresAt": "<time the session ends>" }

The API key must be a Full-Access key (type All or Write). Keep it on your server and never put it in the page. The account must have a subscription on the product.

  1. On the page, load the script and pass the token to the element:
<script src="<web components URL>/self-serve-portal.min.js"></script>
<self-serve-portal
  product-id="<your product ID>"
  session-token="<token from your server>">
</self-serve-portal>

A session lasts 30 minutes. When it ends, the element fires a session-expired event. It bubbles and crosses shadow boundaries, so you can listen for it on document. Get a new token from your server and set it on the element.

document.addEventListener('session-expired', async () => {
  const { token } = await fetch('/my-app/portal-token').then(r => r.json());
  document.querySelector('self-serve-portal').setAttribute('session-token', token);
});

Option 2: Email code

Use this when you have no sign-in of your own. Nothing is needed on your server.

<script src="<web components URL>/self-serve-portal.min.js"></script>
<self-serve-portal product-id="<your product ID>"></self-serve-portal>

The customer enters their email address and gets a 6-digit code by email.

  • The code is valid for 10 minutes.
  • The customer has 5 tries per code.
  • A code can be requested 3 times per 15 minutes for each email address.
  • A new code replaces the old one.
  • The email must be the account’s own email address. Contact emails are not used.
  • If the email belongs to several accounts, the customer picks one.
  • The reply to “send code” is the same whether or not the email has an account, so no one can use it to find out who your customers are.

A wrong or expired code gives “That code is not right or has expired.” Too many tries give “Too many attempts. Try again later.” The session lasts 30 minutes, the same as Option 1.

Element attributes

AttributeRequiredDescription
product-idYesThe product whose subscriptions the portal manages
session-tokenNoA token from POST /portal-sessions. Leave it out to use the email code
data-themeNoTheme settings; the customization screen fills these in for you

Note: The api-key and account-id attributes are no longer used. The portal ignores them and writes a warning to the browser console. Remove them from your pages.

What customers can do

Only the actions you turn on under Customers can appear, for example Change Plan, Change Frequency, Add Addon, Pause/Resume, Renew, Cancel Subscription, Convert Trial and reactivation. Even when turned on, an action shows only when the subscription’s status allows it. See Actions by status and Portal Features.

Not available yet

  • Profile, addresses, payment methods and invoices: these screens show in the preview only. Customers can’t use them in the embedded portal yet.
  • A BillHive-hosted portal URL: the portal runs on your website through the embed code.

Testing

  1. Create a test customer with an email you can read, and a subscription on the product.
  2. Open the page with the embed code. Sign in with your app, or with the test email and code.
  3. Try each enabled action and check the result on the subscription in the merchant portal.

Next steps