---
title: "Create a customer portal session"
method: POST
path: "/customers/{customer_id}/portal-sessions"
tags: ["Customer portals"]
---

# Create a customer portal session

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

## Request

- Base URL: `https://sandbox-api.paddle.com`
- URL: `https://sandbox-api.paddle.com/customers/{customer_id}/portal-sessions`
- Auth: HTTP bearer

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.

## Path parameters

- `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`.

## Request body

- CustomerPortalSessionCreate: Represents a customer portal session creation request.
  - `subscription_ids` SubscriptionId[]: List of subscriptions to create authenticated customer portal deep links for.

## Response `201`

The request has succeeded and a new resource has been created as a result.

- object
  - `data` CustomerPortalSession, required: Represents a customer portal session.
    - `id` string, required: Unique Paddle ID for this customer portal session entity, prefixed with `cpls_`.
    - `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`.
    - `urls` CustomerPortalSessionUrls, required: Authenticated customer portal deep links. For security, the `token` appended to each link is temporary. You shouldn't store these links.
      - `general` CustomerPortalSessionUrlsGeneral, 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` CustomerPortalSessionUrlsSubscriptionsItem[]: 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.
        - `id` string, required: Unique Paddle ID for this subscription entity, prefixed with `sub_`.
        - `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.
  - `meta` Meta, 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.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-10-19** (v1) `4f35a8c6ea4d`: 1 info
  - added the required property `data/urls/allOf[subschema #1: CustomerPortalSessionUrls]/subscriptions/items/view_subscription` to the response with the `201` status
- **2026-07-09** (v1) `e1ac347eb3c5`: 1 breaking, 3 info
  - added the pattern `^ctm_[a-z\d]{26}$` to the `path` request parameter `customer_id`
  - api tag `Customer portals` added
  - api tag `Customer portal sessions` removed
  - api tag `Customers` removed
- **2026-02-02** (v1) `9ba8be0f2006`: 12 breaking, 2 warning, 11 info
  - added the new path request parameter `customer_id`
  - request body became required
  - the `data/created_at` response's property type changed from `string` to no type, and format from `date-time` to no format for status `201`
  - the `data/customer_id` response's property type changed from `string` to no type for status `201`
  - …21 more
- **2024-12-06** (v1) `274e5b2be190`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/customers/:customer_id/portal-sessions/post.md)

---

[API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)