Docs

Create a customer portal session

Creates a customer portal session for a customer.

POST /customers/{customer_id}/portal-sessions

Creates a customer portal session for a customer.

The 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.

Requires customer_portal_session.write permission.

Path parameters

customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Unique Paddle ID for this customer entity, prefixed with ctm_.
Pattern: ^ctm_[a-z\d]{26}$

Request body

subscription_idsarray
List of subscriptions to create authenticated customer portal deep links for.
Items: max 25, unique

Response (201)

dataobjectrequired
Represents a customer portal session.
idstringrequired
Example: cpls_01h4ge9r64c22exjsx0fy8b48b
Unique Paddle ID for this customer portal session entity, prefixed with cpls_.
Pattern: ^cpls_[a-z\d]{26}$
customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle ID of the customer that this customer portal sessions is for, prefixed with ctm_.
Pattern: ^ctm_[a-z\d]{26}$
urlsobjectrequired
Authenticated customer portal deep links. For security, the token appended to each link is temporary. You shouldn't store these links.
generalobjectrequired
Authenticated customer portal deep links that aren't associated with a specific entity.
overviewstringrequired
Example: https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=overview&token=
Link to the overview page in the customer portal.
subscriptionsarray

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
idstringrequired
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Paddle ID of the subscription that the authenticated customer portal deep links are for.
Pattern: ^sub_[a-z\d]{26}$
cancel_subscriptionstringrequired
Example: https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=cancel_subscription&subscription_id=sub_01h04vsc0qhwtsbsxh3422wjs4&token=
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_methodstringrequired
Example: https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=update_subscription_payment_method&subscription_id=sub_01h04vsc0qhwtsbsxh3422wjs4&token=

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.

created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this customer portal session was created.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
Request
{
  "subscription_ids": [
    "sub_01h04vsc0qhwtsbsxh3422wjs4"
  ]
}
Response
{
  "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"
        }
      ]
    },
    "created_at": "2024-10-25T06:53:58Z"
  },
  "meta": {
    "request_id": "fa176777-4bca-49ec-aa1e-f53885333cb7"
  }
}

Was this page helpful?