> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# POST /customers/{customer_id}/portal-sessions

**Create a customer portal session**

Creates a customer portal session for a customer.

The [customer portal](https://developer.paddle.com/concepts/customer-portal) is a secure, Paddle-hosted site that allows
customers to manage their own subscriptions, payments, and account information without you having to build custom billing screens.

Customers can:

* View transaction history
* Download invoices
* Update payment methods
* Manage their subscriptions including making changes or cancellations
* Revise details on completed transactions

You can create a customer portal session to generate authenticated links for a customer
so that they're automatically signed in to the portal. It's typically used when linking to
the customer portal from your app where customers are already authenticated.

You can include an array of `subscription_ids` to generate authenticated portal links that let customers make
changes to their subscriptions. You can use these links as part of subscription management workflows rather than
building your own billing screens.

Customer portal sessions are temporary and shouldn't be cached.

The customer portal is fully hosted by Paddle. For security and the best customer experience, don't embed the customer
portal in an iframe.

**Required permissions:** `customer_portal_session.write`

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_id` | string | required | Unique Paddle ID for this customer entity, prefixed with `ctm_`. (pattern: `^ctm_[a-z\d]{26}$`) |

## Request body

- `subscription_ids`: array — List of subscriptions to create authenticated customer portal deep links for. (Items: max 25, unique)

### Request example

```json
{
  "subscription_ids": [
    "sub_01h04vsc0qhwtsbsxh3422wjs4"
  ]
}
```

## Response (201)

- `data`: object (required) — Represents a customer portal session.
  - `id`: string (required) — Unique Paddle ID for this customer portal session entity, prefixed with `cpls_`. (pattern: `^cpls_[a-z\d]{26}$`)
  - `customer_id`: string (required) — Paddle ID of the customer that this customer portal sessions is for, prefixed with `ctm_`. (pattern: `^ctm_[a-z\d]{26}$`)
  - `urls`: object (required) — Authenticated customer portal deep links. For security, the `token` appended to each link is temporary. You shouldn't store these links.
    - `general`: object (required) — Authenticated customer portal deep links that aren't associated with a specific entity.
      - `overview`: string (required) — Link to the overview page in the customer portal.
    - `subscriptions`: array — List of generated authenticated customer portal deep links for the subscriptions passed in the `subscription_ids` array in the request.

If subscriptions are paused or canceled, links open the overview page for a subscription.

Empty if no subscriptions passed in the request. (Items: max 25)
      - `id`: string (required) — Paddle ID of the subscription that the authenticated customer portal deep links are for. (pattern: `^sub_[a-z\d]{26}$`)
      - `cancel_subscription`: string (required) — Link to the page for this subscription in the customer portal with the subscription cancellation form pre-opened. Use as part of cancel subscription workflows.
      - `update_subscription_payment_method`: string (required) — Link to the page for this subscription in the customer portal with the payment method update form pre-opened. Use as part of workflows to let customers update their payment details.

If a manually-collected subscription, opens the overview page for this subscription.
      - `view_subscription`: string (required) — Link to the page for this subscription in the customer portal, with no form pre-opened. Use to let customers manage the subscription themselves rather than sending them into one specific action.
  - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this customer portal session was created.
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

### Response example

```json
{
  "data": {
    "id": "cpls_01h4ge9r64c22exjsx0fy8b48b",
    "customer_id": "ctm_01gysfvfy7vqhpzkq8rjmrq7an",
    "urls": {
      "general": {
        "overview": "https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=overview&token=pga_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjdG1fMDFncm5uNHp0YTVhMW1mMDJqanplN3kyeXMiLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE3Mjc2NzkyMzh9._oO12IejzdKmyKTwb7BLjmiILkx4_cSyGjXraOBUI_g"
      },
      "subscriptions": [
        {
          "id": "sub_01h04vsc0qhwtsbsxh3422wjs4",
          "cancel_subscription": "https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=cancel_subscription&subscription_id=sub_01h04vsc0qhwtsbsxh3422wjs4&token=pga_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjdG1fMDFncm5uNHp0YTVhMW1mMDJqanplN3kyeXMiLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE3Mjc2NzkyMzh9._oO12IejzdKmyKTwb7BLjmiILkx4_cSyGjXraOBUI_g",
          "update_subscription_payment_method": "https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=update_subscription_payment_method&subscription_id=sub_01h04vsc0qhwtsbsxh3422wjs4&token=pga_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjdG1fMDFncm5uNHp0YTVhMW1mMDJqanplN3kyeXMiLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE3Mjc2NzkyMzh9._oO12IejzdKmyKTwb7BLjmiILkx4_cSyGjXraOBUI_g",
          "view_subscription": "https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=view_subscription&subscription_id=sub_01h04vsc0qhwtsbsxh3422wjs4&token=pga_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjdG1fMDFncm5uNHp0YTVhMW1mMDJqanplN3kyeXMiLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE3Mjc2NzkyMzh9._oO12IejzdKmyKTwb7BLjmiILkx4_cSyGjXraOBUI_g"
        }
      ]
    },
    "created_at": "2024-10-25T06:53:58Z"
  },
  "meta": {
    "request_id": "fa176777-4bca-49ec-aa1e-f53885333cb7"
  }
}
```