PApaddlehq
Customer portals

Create a customer portal session

Changed on

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.

post/customers/{customer_id}/portal-sessions

Request

  • Base URL
    https://sandbox-api.paddle.com
  • Auth
    HTTP bearer

Path parameters

customer_idstring required

Unique Paddle ID for this customer entity, prefixed with ctm_.

Example:ctm_01grnn4zta5a1mf02jjze7y2ys

Paddle ID of the customer entity to work with.

Request body

subscription_idsSubscriptionId[]

List of subscriptions to create authenticated customer portal deep links for.

Example request

{
  "subscription_ids": [
    "sub_01h04vsc0qhwtsbsxh3422wjs4"
  ]
}

Response

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

Example response

{
  "data": {
    "id": "cpls_01h4ge9r64c22exjsx0fy8b48b",
    "customer_id": "ctm_01grnn4zta5a1mf02jjze7y2ys",
    "urls": {
      "general": {
        "overview": "https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=overview&token="
      },
      "subscriptions": [
        {
          "id": "sub_01h04vsc0qhwtsbsxh3422wjs4",
          "cancel_subscription": "https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=cancel_subscription&subscription_id=sub_01h04vsc0qhwtsbsxh3422wjs4&token=",
          "update_subscription_payment_method": "https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=update_subscription_payment_method&subscription_id=sub_01h04vsc0qhwtsbsxh3422wjs4&token=",
          "view_subscription": "https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=view_subscription&subscription_id=sub_01h04vsc0qhwtsbsxh3422wjs4&token="
        }
      ]
    },
    "created_at": "2024-10-12T07:20:50.52Z"
  },
  "meta": {
    "request_id": "b15ec92e-8688-40d4-a04d-f44cbec93355"
  }
}

Changes

  • v14f35a8c6ea4dRevision changes
    • info

      added the required property ///// to the response with the status

  • v1e1ac347eb3c5Revision changes
    • breaking

      added the pattern ^ctm_[a-z\d]{26}$ to the path request parameter customer_id

    • info

      api tag Customer portals added

    • info

      api tag Customer portal sessions removed

    • info

      api tag Customers removed