Generate authenticated customer portal links

What's new?

We've updated the Paddle API so that now you can create customer portal sessions. Customer portal sessions generate links that automatically log a customer in to the customer portal. You can also generate deep links that let customers make changes to their subscriptions.

How it works

The customer portal is a secure, Paddle-hosted site that customers can use to manage their own subscriptions, payments, and account information. You can link to the customer portal to add core subscription management functionality to your app rather than building your own billing management screens from scratch.

Previously, if you linked the portal from your app then customers had to sign in to the portal. With this update, you can create customer portal sessions to generate authenticated links to the customer portal for a customer. This makes sense in the context of your app, where customers are already authenticated, and makes for a more seamless customer experience.

When creating portal sessions, you can include an array 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 to let customers do things like update their payment method or cancel a subscription.

Examples

Request

This example creates a customer portal session with deep links for a subscription.

1
2
3
4
5
1{
2  "subscription_ids": [
3    "sub_01h04vsc0qhwtsbsxh3422wjs4"
4  ]
5}

Response

If successful, Paddle returns a list of authenticated customer portal URLs. The general URL is always returned, linking to the customer portal homepage for a customer. Deep links for subscriptions are returned for the subscriptions passed as part of the request.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "cpls_01h4ge9r64c22exjsx0fy8b48b",
4    "customer_id": "ctm_01gysfvfy7vqhpzkq8rjmrq7an",
5    "urls": {
6      "general": {
7        "overview": "https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=overview&token=pga_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjdG1fMDFncm5uNHp0YTVhMW1mMDJqanplN3kyeXMiLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE3Mjc2NzkyMzh9._oO12IejzdKmyKTwb7BLjmiILkx4_cSyGjXraOBUI_g"
8      },
9      "subscriptions": [
10        {
11          "id": "sub_01h04vsc0qhwtsbsxh3422wjs4",
12          "cancel_subscription": "https://customer-portal.paddle.com/cpl_01j7zbyqs3vah3aafp4jf62qaw?action=cancel_subscription&subscription_id=sub_01h04vsc0qhwtsbsxh3422wjs4&token=pga_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjdG1fMDFncm5uNHp0YTVhMW1mMDJqanplN3kyeXMiLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE3Mjc2NzkyMzh9._oO12IejzdKmyKTwb7BLjmiILkx4_cSyGjXraOBUI_g",
13          "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"
14        }
15      ]
16    },
17    "created_at": "2024-10-25T06:53:58Z"
18  },
19  "meta": {
20    "request_id": "fa176777-4bca-49ec-aa1e-f53885333cb7"

Summary of changes

Fields

This is a summary of the changes to fields in the Paddle API:

API operations

This is a summary of new operations in the Paddle API:

Next steps

This change is available in version 1 of the Paddle API.

It's a non-breaking change, meaning it doesn't impact existing integrations.

You can create a customer portal session using the Paddle API to get started.

Learn more