Create customer portal session API Reference

POST

/tenants/{tenant}/billing/portal-session

curl --request POST \
  --url https://api.kupe.cloud/api/v1/tenants/acme/billing/portal-session \
  --header 'Authorization: <Authorization>'

Creates a fresh, authenticated Paddle customer-portal session for the tenant and returns its deep links: the portal overview page (invoices, payments, saved payment methods) and — when the tenant has a linked payment-method subscription — the update-payment-method form. Use this to update the card on file (e.g. to recover a PastDue invoice); Paddle retries failed charges automatically once the payment method is fixed. The returned URLs are short-lived and authenticated — open them immediately; do NOT store them. Create a new session each time. Requires admin role.

Authorizations

• BearerAuth

Parameters

Path Parameters

tenant

required

string

Tenant name

Responses

200

Fresh portal URLs (short-lived — do not store)

Media type application/json

object

overviewURL

OverviewURL is the authenticated customer-portal overview page (invoices, payments, saved payment methods).

string

updatePaymentMethodURL

UpdatePaymentMethodURL opens the portal with the payment-method update form pre-opened for the tenant’s payment-method subscription. Omitted when the tenant has no linked subscription yet.

string

Example

{
  "overviewURL": "https://customer-portal.paddle.com/cpl_01x/overview?token=...",
  "updatePaymentMethodURL": "https://customer-portal.paddle.com/cpl_01x/subscriptions/sub_01y/update-payment-method?token=..."
}

401

Missing or invalid authentication

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

403

Not an admin of this tenant

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

404

Tenant not found

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

409

Tenant has no billing profile yet

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

429

Rate limit exceeded

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

503

Billing integration not configured or Paddle unavailable

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}