Customer Portal Integration

The Customer Portal is a hosted, passwordless page where a customer sees their subscription, pays and downloads invoices, and manages payment methods — so billing questions that would otherwise reach support are self-served. This guide covers opening it from your product with a “Manage billing” button, sending links from the dashboard, and choosing what customers are allowed to change. The session API and every setting are on the Customer Portal page.

How It Works

Sending Portal Access

Via Dashboard

Send a portal link directly to a customer:

Navigate to Customers → [Customer Name]
Click Send Portal Link or Send Billing Email
Customer receives an email with a secure link
The link is short-lived and single-use

Via Your Application

Create a portal session with POST /customer-portal-sessions and redirect the customer to the url it returns. Identify the customer by customer_id or by customer_alias — your own user ID, if you set it as an alias on the customer.

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" }'

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"},
    timeout=10,
)
response.raise_for_status()
portal_url = response.json()["url"]

const session = await alguna.portal.createSession({ customer_alias: "acme-user-4821" });
// redirect to session.url

Sessions expire after 1 hour and are single-use. See Customer Portal for the per-section settings and the API reference.

What Customers Can Do

View Invoices

Customers can see all their invoices:

Current and past invoices
Invoice status (paid, pending, overdue)
Download invoice PDFs
View line item details

Update Payment Method

Customers can manage their payment methods:

Add new credit card
Update existing card
Set default payment method
Add bank account (if enabled)

View Subscription

Customers can see their subscription details:

Current plan and pricing
Billing cycle dates
Next invoice date
Contract terms

Self-Service Changes

If enabled, customers can:

Upgrade to a higher plan
Downgrade to a lower plan
Add or remove seats
Cancel subscription

Portal Configuration

Settings → Organization → Customer portal

Configure what customers can do:

Feature	Description
Plan overview	Show the subscription, next charge and pricing breakdown
Self-serve changes	Let the customer change plan without contacting you
Cancel subscription	Let the customer cancel
Invoice list	Show invoice history with PDF downloads
Billing details	Show company details and payment methods
Edit account details	Let the customer edit their own billing details
Edit payment method	Let the customer add or change a payment method
Edit autopay	Let the customer turn autopay on or off

These are your organization’s defaults. A portal session can override any of them for a single customer.

Enabling Self-Service

Go to Settings → Organization → Customer portal
Enable self-serve plan changes and, if you want it, self-cancellation
Save settings

To allow it for some customers but not others, leave the defaults restrictive and pass plan_overview_settings.allow_self_serve_change on the sessions where it should be available.

Branding

The portal uses the logo, colors and brand slug set under Settings → Organization → Customizations → Branding — see Branding. To serve it from your own domain, see Custom domains.

Portal Sessions

Session Expiration

Each session carries an expires_at and is single-use. Create a session when the customer clicks through to billing rather than emailing a link you generated earlier.

Security

Each link is unique and single-use
Sessions are tied to a specific customer
No login required, so the link is the credential: treat it as a secret

Webhooks

Receive notifications when customers take action:

Event	When Sent
`subscription.version.updated`	A self-serve plan change created or published a version
`subscription.cancelation_scheduled`	The customer scheduled a cancellation
`subscription.canceled`	The cancellation took effect
`payment.created`	A payment was started
`payment.updated`	A payment changed status

Configure webhooks under Settings → Connections → Developers → Webhooks. See Webhooks for the full event list and payloads.

Common Use Cases

”Manage Billing” Button

Add a button in your app that takes customers to the portal:

Create a /billing route in your application
When it is accessed, create a portal session and redirect to the session url
Because sessions are single-use, create a fresh one on every visit

Payment Method Only

To narrow the portal to payment details, hide the other sections on the session:

plan_overview_settings.show_section: false
invoice_list_settings.show_section: false
billing_details_settings.allow_payment_method_edit: true

Invoice Access

To give customers invoices and nothing else, show only the invoice list:

invoice_list_settings.show_section: true
plan_overview_settings.show_section: false

Troubleshooting

Portal Link Not Working

Check the session’s expires_at — it may have lapsed
Check whether the link has already been used; sessions are single-use
Verify the customer exists, then create a new session

Customer Can’t See Invoices

Verify the customer has invoices
Check that invoice_list_settings.show_section is not set to false on the session, and that the section is enabled in your organization defaults

Self-Service Changes Not Available

Check that self-service is enabled in Settings → Organization → Customer portal, and not overridden to false on the session
Verify the plans allow self-service changes
Ensure the customer’s current plan permits changes

Best Practices

Easy Access

Add a clear “Manage Billing” link in your app navigation.

Brand Consistently

Configure branding so the portal matches your app.

Limit Self-Service

Control which changes customers can make on their own.

Handle Webhooks

Listen for portal events to keep your app in sync.

Next Steps

Customer Portal

Full portal configuration and API reference.

Hosted Checkout

Set up hosted checkout pages.

Collections

Dunning that sends customers to the portal to pay.

Developer quick start

API basics, SDK and webhooks.

​How It Works

​Sending Portal Access

​Via Dashboard

​Via Your Application

​What Customers Can Do

​View Invoices

​Update Payment Method

​View Subscription

​Self-Service Changes

​Portal Configuration

​Settings → Organization → Customer portal

​Enabling Self-Service

​Branding

​Portal Sessions

​Session Expiration

​Security

​Webhooks

​Common Use Cases

​”Manage Billing” Button

​Payment Method Only

​Invoice Access

​Troubleshooting

​Portal Link Not Working

​Customer Can’t See Invoices

​Self-Service Changes Not Available

​Best Practices