Skip to main content
The customer portal is a set of endpoints your application can put in front of its own customers. A customer can see their plan, usage, credits, and invoices, and can change plans or buy credits if you allow it. You control access through short-lived portal sessions, so customers never use your API key.

​
How it works

  1. Your backend creates a portal session for a customer with your API key.
  2. Your backend passes the session token to the browser.
  3. The browser calls the portal endpoints with the session token as a Bearer token.
Sessions are scoped to one customer and expire after expiresInSeconds (up to 24 hours).

​
Create a session

Create the session on your server, and only when the customer is signed in to your application.

​
What the customer can see

With the session token, the portal calls return:
  • GET /v1/portal/me: the customer’s own profile.
  • GET /v1/portal/config: which portal features are enabled.
  • GET /v1/portal/plans: plans the customer can switch to.
  • GET /v1/portal/usage: consumption for the current period.
  • GET /v1/portal/entitlements: features and remaining allowances.
  • GET /v1/portal/wallets and GET /v1/portal/credits: credit balances.
  • GET /v1/portal/invoices: invoices.
  • GET /v1/portal/upcoming: the next invoice.
To change plans, call GET /v1/portal/plan-change/preview?planId=… to show the customer what will happen, then POST /v1/portal/plan-change to apply it. Preview doesn’t change anything, so show it before the customer confirms. To buy credits when allowCreditPurchases is on, call POST /v1/portal/wallets/:type/purchase, where :type is the credit type. The purchase is invoiced to the customer.

​
Build your own UI

The portal is a set of plain HTTP endpoints, so you can build the screens in your own application. The React SDK provides hooks for entitlements and credits that you can use alongside them.