> ## 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

> Enable self-service account management for your customers

The Customer Portal provides a self-service interface where your customers can view their subscription, invoices, and billing information. Reduce support burden while giving customers control over their accounts.

***

## Portal Sections

The Customer Portal has three main sections:

| Section                 | What Customers See                                                   |
| ----------------------- | -------------------------------------------------------------------- |
| **Plan Overview**       | Current subscription, pricing tiers, next charge date, cancel option |
| **Invoices**            | Invoice history with status, amounts, and PDF downloads              |
| **Billing Information** | Company details, payment methods, auto-pay settings                  |

***

## Sending Portal Access

### Via Dashboard

1. Navigate to **Customers** → select customer
2. Click **Send Portal Link**
3. Customer receives email with secure link
4. Link expires after configured time

### Via API

Create a portal session programmatically to embed in your application.

**Endpoint:** `POST /portal/customer-session/customer-portal`

**Request:**

| Property                 | Type   | Required    | Description                                                    |
| ------------------------ | ------ | ----------- | -------------------------------------------------------------- |
| `accountId`              | string | If no alias | The Alguna account ID                                          |
| `accountAlias`           | string | If no ID    | External ID (e.g., your Salesforce ID or internal customer ID) |
| `planOverviewSettings`   | object | Optional    | Configure the Plan Overview section                            |
| `invoiceListSettings`    | object | Optional    | Configure the Invoices section                                 |
| `billingDetailsSettings` | object | Optional    | Configure the Billing Information section                      |

**Example Request:**

```json theme={null}
{
  "accountId": "acc_123456",
  "planOverviewSettings": {
    "showSection": true,
    "allowSubscriptionCancel": true
  },
  "invoiceListSettings": {
    "showSection": true
  },
  "billingDetailsSettings": {
    "showSection": true
  }
}
```

**Response:**

```json theme={null}
{
  "sessionUrl": "https://yourcompany.alguna.app/portal/NWyfb389IdjI930..."
}
```

Redirect your customer to the `sessionUrl` to access their portal.

***

## Configuring Portal Sections

### Plan Overview Settings

Control what customers see in the Plan Overview section:

| Property                  | Default | Description                                   |
| ------------------------- | ------- | --------------------------------------------- |
| `showSection`             | `true`  | Show or hide the entire Plan Overview section |
| `allowSubscriptionCancel` | `true`  | Allow customers to cancel their subscription  |

The Plan Overview shows:

* Subscription name and status
* Estimated next charge amount
* Next charge date
* Pricing breakdown by product (tiers, quantities, fees)

### Invoice List Settings

| Property      | Default | Description                       |
| ------------- | ------- | --------------------------------- |
| `showSection` | `true`  | Show or hide the Invoices section |

The Invoices section displays:

* Issue date and due date
* Invoice amount
* Status (Paid, Issued, Overdue)
* Invoice ID
* Open Invoice and Download PDF actions

### Billing Details Settings

| Property      | Default | Description                                  |
| ------------- | ------- | -------------------------------------------- |
| `showSection` | `true`  | Show or hide the Billing Information section |

Customers can view and manage:

* Company billing details
* Payment methods
* Auto-pay settings

***

## Branding

The portal displays your company branding:

1. Navigate to **Settings** → **Branding**
2. Upload your logo
3. Set primary colors
4. The portal will use your branding automatically

***

## Custom Domain

By default, the portal is served at:

```
https://yourcompany.alguna.app/portal/...
```

You can use your own domain (e.g., `billing.yourcompany.com`) for a seamless customer experience. See [Custom Domains](/hosted/custom-domains) for setup instructions.

***

## Security

Portal sessions are:

* Time-limited (expire after configured duration)
* Tied to a specific customer account
* Accessible via secure, single-use tokens
* No password required

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Brand Consistently" icon="palette">
    Match portal branding to your main application.
  </Card>

  <Card title="Control Cancellation" icon="shield">
    Use `allowSubscriptionCancel: false` for enterprise customers who should contact sales.
  </Card>

  <Card title="Hide Sections as Needed" icon="eye-slash">
    Use `showSection: false` to simplify the portal for specific customers.
  </Card>

  <Card title="Use Account Alias" icon="link">
    Pass your internal customer ID as `accountAlias` to avoid storing Alguna IDs.
  </Card>
</CardGroup>

***

## API Reference

<CardGroup cols={2}>
  <Card title="Create Portal Session" icon="link" href="/api-reference/customers/createCustomerPortal">
    Generate portal links via API.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Track subscription and invoice events.
  </Card>
</CardGroup>

***

## Next Steps

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

  <Card title="Custom Domains" icon="globe" href="/hosted/custom-domains">
    Use your own domain for hosted pages.
  </Card>
</CardGroup>