Customer Portal

The Customer Portal is a hosted self-service page for one customer: their current subscription and next charge, their invoice history with PDF downloads, and their billing details and payment methods. You do not build or host it — you create a short-lived session with the API (or send a link from the dashboard) and redirect the customer to the URL it returns. Use it behind a “Manage billing” button in your product, in billing emails, or as the payment page for an invoice. Sections and permissions are configured per organization and can be overridden per session. The objects it displays — customers, subscriptions, invoices, payments — are described in How Alguna works.

Portal sections

Section	What the customer sees
Plan overview	Subscription name and status, estimated next charge and its date, pricing breakdown by product, and — if allowed — cancel and change-plan actions
Invoices	Issue and due dates, amounts, status, and actions to open an invoice or download its PDF
Billing details	Company details, payment methods, and autopay settings — each editable only if allowed

Opening the portal

Via the API

Create a session with POST /customer-portal-sessions and redirect the customer to the url in the response. Identify the customer by Alguna ID or by one of the aliases you set on the customer, so you never need to store Alguna IDs.

Property	Type	Required	Description
`customer_id`	string	One of the two	The Alguna customer ID
`customer_alias`	string	One of the two	An alias you set on the customer, such as your own user ID or a CRM record ID
`plan_overview_settings`	object	No	Override the Plan overview section for this session
`invoice_list_settings`	object	No	Override the Invoices section
`billing_details_settings`	object	No	Override the Billing details section

Omit a settings object, or any field inside one, to use your organization’s default.

curl -X POST https://api.alguna.io/customer-portal-sessions \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_alias": "acme-user-4821",
    "plan_overview_settings": {
      "show_section": true,
      "allow_subscription_cancel": true
    },
    "invoice_list_settings": {
      "show_section": true
    },
    "billing_details_settings": {
      "show_section": true,
      "allow_payment_method_edit": true
    }
  }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/customer-portal-sessions",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={
        "customer_alias": "acme-user-4821",
        "plan_overview_settings": {
            "show_section": True,
            "allow_subscription_cancel": True,
        },
        "invoice_list_settings": {"show_section": True},
        "billing_details_settings": {
            "show_section": True,
            "allow_payment_method_edit": True,
        },
    },
    timeout=10,
)
response.raise_for_status()
portal_url = response.json()["url"]
# redirect the customer to portal_url

const session = await alguna.portal.createSession({
  customer_alias: "acme-user-4821",
  plan_overview_settings: { show_section: true, allow_subscription_cancel: true },
  invoice_list_settings: { show_section: true },
  billing_details_settings: { show_section: true, allow_payment_method_edit: true },
});
// redirect the customer to session.url

Response

{
  "id": "a8B3kLmQ",
  "url": "https://portal.alguna.io/hs/abc123",
  "customer_id": "cust_abc123",
  "expires_at": "2026-04-01T11:00:00Z",
  "created_at": "2026-04-01T10:00:00Z"
}

Sessions expire 1 hour after creation (expires_at) and are single-use per token, so create one at the moment the customer clicks through rather than storing the link. Reference: Create a customer portal session.

Via the dashboard

Open Customers and select the customer
Click Send Portal Link
The customer receives an email with a link that expires like an API-minted session

The same email can be sent by an automation — for example after an invoice is issued, or when a card is about to expire.

Configuring sections

Organization defaults live under Settings → Organization → Customer portal. A session can override any of them for one customer.

Plan overview settings

Property	Description
`show_section`	Show or hide the whole Plan overview section
`allow_subscription_cancel`	Let the customer cancel their subscription
`allow_self_serve_change`	Let the customer change plan without contacting you

Invoice list settings

Property	Description
`show_section`	Show or hide the Invoices section

Billing details settings

Property	Description
`show_section`	Show or hide the Billing details section
`allow_account_edit`	Let the customer edit their account details
`allow_payment_method_edit`	Let the customer add or change a payment method
`allow_autopay_edit`	Let the customer turn autopay on or off

Common combinations:

Goal	Session settings
Payment method update only	`plan_overview_settings.show_section: false`, `invoice_list_settings.show_section: false`, `billing_details_settings.allow_payment_method_edit: true`
Invoices only	`invoice_list_settings.show_section: true`, `plan_overview_settings.show_section: false`, `billing_details_settings.show_section: false`
Enterprise customer who must talk to sales to cancel	`plan_overview_settings.allow_subscription_cancel: false`

Branding and domain

The portal uses the logo, colors and brand slug set under Settings → Organization → Customizations → Branding — see Branding. By default it is served from an Alguna-hosted URL, returned as url on the session; to serve it from your own domain, see Custom domains.

Security

Short-lived — every session carries expires_at (1 hour); after that the customer needs a new one
Single-use — a token is bound to one session
Customer-scoped — a session shows one customer’s data only
Passwordless — possession of the link is the credential, so mint it on demand and never log or email it in bulk

Reacting to what customers do

Actions taken in the portal raise the same webhooks as any other change:

Event	When
`subscription.cancelation_scheduled`	The customer scheduled a cancellation
`subscription.canceled`	The cancellation took effect
`subscription.version.updated`	A self-serve plan change created or published a version
`payment.created` / `payment.updated`	The customer paid an invoice

Next steps

Customer portal integration guide

The “Manage billing” button, end to end.

Hosted checkout

Take the first payment before there is a subscription to manage.

Custom domains

Serve hosted pages from your own domain.

Collections

Dunning flows that send customers to the portal to pay.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

Portal sections

Opening the portal

Via the API

Via the dashboard

Configuring sections

Plan overview settings

Invoice list settings

Billing details settings

Branding and domain

Security

Reacting to what customers do

Next steps

Customer portal integration guide

Hosted checkout

Custom domains

Collections

​Portal sections

​Opening the portal

​Via the API

​Via the dashboard

​Configuring sections

​Plan overview settings

​Invoice list settings

​Billing details settings

​Branding and domain

​Security

​Reacting to what customers do

​Next steps

Customer portal integration guide

Hosted checkout

Custom domains

Collections

Portal sections

Opening the portal

Via the API

Via the dashboard

Configuring sections

Plan overview settings

Invoice list settings

Billing details settings

Branding and domain

Security

Reacting to what customers do

Next steps