> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Portal Integration

> Let customers manage their billing and subscriptions

The Customer Portal gives your customers a self-service interface to view invoices, update payment methods, and manage subscriptions. Send customers a link to access their billing information.

***

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant YourApp
    participant Alguna

    Customer->>YourApp: Clicks "Manage Billing"
    YourApp->>Alguna: Create portal session
    Alguna-->>YourApp: Portal URL
    YourApp->>Customer: Redirect to portal
    Customer->>Alguna: View/manage billing
    Customer->>YourApp: Return to app
```

***

## Sending Portal Access

### Via Dashboard

Send a portal link directly to a customer:

1. Navigate to **Customers → \[Customer Name]**
2. Click **Send Portal Link** or **Send Billing Email**
3. Customer receives email with secure link
4. Link expires after 1 hour (configurable)

### Via Your Application

Work with your development team to create portal sessions programmatically.

See the [Portal API Reference](/api-reference/billing-sessions/create-portal-link) for technical details.

***

## 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 → Customer Portal

Configure what customers can do:

| Feature                 | Description              |
| ----------------------- | ------------------------ |
| **View Invoices**       | See invoice history      |
| **Download PDFs**       | Download invoice PDFs    |
| **Update Payment**      | Change payment method    |
| **View Subscription**   | See subscription details |
| **Self-Serve Changes**  | Allow plan changes       |
| **Cancel Subscription** | Allow self-cancellation  |
| **View Usage**          | See metered usage        |

### Enabling Self-Service

1. Navigate to **Settings → Customer Portal**
2. Under **Self-Serve Options**:
   * Enable **Allow Upgrades**
   * Enable **Allow Downgrades** (optional)
   * Enable **Allow Cancellation** (optional)
3. Select which plans customers can switch between
4. Save settings

***

## Branding

Customize the portal appearance:

1. Navigate to **Settings → Branding**
2. Upload your logo
3. Set primary colors
4. Configure footer text
5. Preview the portal

The portal will match your brand colors and display your logo.

***

## Portal Sessions

### Session Expiration

Portal links expire after 1 hour by default. Configure this in **Settings → Customer Portal → Session Duration**.

### Security

* Each link is unique and single-use
* Sessions are tied to a specific customer account
* No login required (link contains secure token)

***

## Webhooks

Receive notifications when customers take action:

| Event                    | When Sent              |
| ------------------------ | ---------------------- |
| `subscription.activated` | Subscription changed   |
| `subscription.canceled`  | Customer canceled      |
| `payment.updated`        | Payment method updated |

Configure webhooks in **Settings → Webhooks**.

***

## Common Use Cases

### "Manage Billing" Button

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

1. Create a `/billing` route in your application
2. When accessed, create a portal session and redirect
3. Set the return URL to bring customers back to your app

### Payment Method Update

Send customers directly to update their payment:

1. Create portal session with initial page set to "payment\_methods"
2. Customer lands directly on payment update screen

### Invoice Access

Give customers quick access to invoices:

1. Create portal session with initial page set to "invoices"
2. Customer can view and download all invoices

***

## Troubleshooting

### Portal Link Not Working

1. Check the link hasn't expired (default: 1 hour)
2. Verify the customer account exists
3. Create a new portal session

### Customer Can't See Invoices

1. Verify the customer has invoices
2. Check that "View Invoices" is enabled in portal settings

### Self-Service Changes Not Available

1. Check that self-service is enabled in **Settings → Customer Portal**
2. Verify the plans allow self-service changes
3. Ensure the customer's current plan permits changes

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Easy Access" icon="link">
    Add a clear "Manage Billing" link in your app navigation.
  </Card>

  <Card title="Brand Consistently" icon="palette">
    Configure branding so the portal matches your app.
  </Card>

  <Card title="Limit Self-Service" icon="shield">
    Control which changes customers can make on their own.
  </Card>

  <Card title="Handle Webhooks" icon="bell">
    Listen for portal events to keep your app in sync.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Customer Portal" icon="browser" href="/hosted/customer-portal">
    Full portal configuration and API reference.
  </Card>

  <Card title="Hosted Checkout" icon="cart-shopping" href="/hosted/checkout">
    Set up hosted checkout pages.
  </Card>
</CardGroup>