Become a Paddle partner
Join the Paddle partner program to read this content. You'll also get access to our partner API and agent tooling. Let us know a few details about your business to get started. Already a partner? Log in to view this page.
The customer portal is the main way that customers manage their own subscriptions. They can update a payment method, download invoices, and cancel a subscription without the seller building those screens. You generate an authenticated link into the portal from inside the seller's app.
Take care not to confuse customer portal sessions with magic sessions that are used to open the Paddle dashboard.
Overview
Manage subscriptions in two steps:
- Create a customer portal session
Generate a preauthenticated link to the customer portal and surface it in the seller's app. - Build upgrade and downgrade workflows Optional
Use the Paddle API to upgrade or downgrade items on a subscription.
Create a portal session
- Layer
- Your agent
- Authentication
- Seller API key
- Environment
- Sandbox, Live
A customer portal session returns authenticated links that sign the customer in to the customer portal so they can manage their subscriptions.
To create a customer portal session, send a request to the POST /customers/{customer_id}/portal-sessions endpoint. Pass a subscription_ids array (up to 25) to get deep links to the cancel and update payment method pages for those subscriptions.
If successful, Paddle returns an authenticated cancel_subscription and update_subscription_payment_method link for each subscription, plus the general portal links in urls.general. Surface these in the seller's app in a customer management screen.
{ "subscription_ids": ["sub_01jqz3n5p7r9s1t3v5w7x9y1z3"]}{ "data": { "id": "cpls_01jcggxbs9b4tff8zy7kfwwr1s", "customer_id": "ctm_01jqz4a6b8c0d2e4f6g8h0j2k4", "urls": { "general": { "overview": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=overview&token=pga_eyJhbGc..." }, "subscriptions": [ { "id": "sub_01jqz3n5p7r9s1t3v5w7x9y1z3", "cancel_subscription": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=cancel_subscription&subscription_id=sub_01jqz3n5p7r9s1t3v5w7x9y1z3&token=pga_eyJhbGc...", "update_subscription_payment_method": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=update_subscription_payment_method&subscription_id=sub_01jqz3n5p7r9s1t3v5w7x9y1z3&token=pga_eyJhbGc..." } ] }, "created_at": "2026-04-22T15:47:10.761048551Z" }, "meta": { "request_id": "0936d329-68b4-4c9f-b33c-d872d3ffbaf1" }}The links are temporary and shouldn't be cached: create a fresh session each time you need one, and open the portal in a new tab rather than embedding it.
When a customer makes a change using the portal, nothing automatically updates in the seller's app. Use webhooks to gate access to the seller's app based on the customer's subscription status.
Build upgrade and downgrade workflows Optional
- Layer
- Your agent
- Authentication
- Seller API key
- Environment
- Sandbox, Live
Customers can't change plan in the customer portal yet, so to offer upgrades or downgrades in-app, build them using the Paddle API.
To upgrade or downgrade items on a subscription, send a request to the PATCH /subscriptions/{subscription_id} endpoint with the new items, and set proration_billing_mode to control how the change is billed.
{ "items": [ { "price_id": "pri_01hv0vax6rv18t4tamj848ne4d", "quantity": 2 } ], "proration_billing_mode": "prorated_immediately"}{ "data": { "id": "sub_01jqz3n5p7r9s1t3v5w7x9y1z3", "status": "active", "customer_id": "ctm_01jqz4a6b8c0d2e4f6g8h0j2k4", "currency_code": "USD", "collection_mode": "automatic", "created_at": "2026-04-22T07:13:19.02Z", "updated_at": "2026-04-22T08:25:51.744Z", "started_at": "2026-04-22T07:13:18.412737Z", "next_billed_at": "2026-05-22T07:13:18.412737Z", "current_billing_period": { "starts_at": "2026-04-22T07:13:18.412737Z", "ends_at": "2026-05-22T07:13:18.412737Z" }, "billing_cycle": { "interval": "month", "frequency": 1 }, "scheduled_change": null, "items": [ { "status": "active", "quantity": 2, "recurring": true, "price": { "id": "pri_01hv0vax6rv18t4tamj848ne4d", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "description": "Monthly (per seat)", "unit_price": { "amount": "500", "currency_code": "USD" } } } ], "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01jqz3n5p7r9s1t3v5w7x9y1z3/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01jqz3n5p7r9s1t3v5w7x9y1z3/cancel" } }, "meta": { "request_id": "668b5e0c-9ff9-4cdc-b33a-79bc1894d294" }}