Create a Stripe Customer Portal link

Plan switching (self_serve is never offered as a switch target — see sarvex-v1-architecture.md §Domain 8) and cancellation happen inside this portal session, alongside payment-method and invoice management. There is no separate checkout-based upgrade endpoint: every merchant already has a subscription from account creation, so an upgrade is a price change on the existing subscription — exactly what the portal’s subscription-update feature does.

POST/billing/portal-link

Authorization

AuthorizationBearer token (JWT) · headerrequired

JWT issued by the external IdP via the OAuth 2.0 authorization-code flow (Kinde in production; a simulator in test). The client obtains it and sends it as a Bearer token on every authenticated call. Sarvex's services verify it — issuer, audience, signature (IdP JWKS), expiry — and read identity and tenant from its claims. Sarvex does not issue or revoke these tokens. merchant_id/store_id are read from the verified claims (and the merchant→store mapping), never from the URL. The operator scope is required for /operator/*. Operators acting on a specific merchant pass the X-Operate-As header, which is recorded in the audit log.

Responses

200

Hosted portal URL.

urlstring<uri>

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (JWT)Remember on this deviceInclude my values in samples

Request

curl -X POST "https://api.sarvex.example.com/v1/billing/portal-link" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.sarvex.example.com/v1/billing/portal-link", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.post(
    "https://api.sarvex.example.com/v1/billing/portal-link",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "url": "http://example.com"
}