Customer Portal

The customer portal lets your end-customers manage their own subscriptions — view invoices, update cards, change plans, cancel — without touching your support team. Access is bootstrapped from a portal link containing a cp_xxx token, then hardened with an email OTP: nobody gets a session just by holding the link.

Portal endpoints live under https://api-gateway.lunixi.com/api/portal/v1 and are called by the customer's browser (hosted portal or your embed) — never with your secret key.

How it works

Validate the portal token

curl -X POST https://api-gateway.lunixi.com/api/portal/v1/validate \
  -H "Content-Type: application/json" \
  -d '{ "token": "cp_9f3ab27c41d0" }'

{
  "success": true,
  "requireEmailVerification": true,
  "effectivePlanSelectionMode": "SELF_SERVICE",
  "allowedPlanIds": ["plan_01JX2G3M8V"],
  "permissions": {
    "canStartSubscription": true,
    "canCancelSubscription": true,
    "canChangePlan": true,
    "canUpdatePaymentMethod": true,
    "canViewInvoices": true,
    "canDownloadInvoicePdf": true
  },
  "brandLogoUrl": "…",
  "brandPrimaryColor": "#4F46E5",
  "supportEmail": "[email protected]",
  "customerFirstName": "Ayşe",
  "customerEmailMasked": "a***@example.com",
  "hasActiveSubscription": false
}

permissions is a set of can* booleans reflecting what you configured for the link — render only the actions that are true.

OTP verification

# 1) send the code to the customer's registered e-mail
curl -X POST https://api-gateway.lunixi.com/api/portal/v1/otp/request \
  -H "Content-Type: application/json" \
  -d '{ "token": "cp_9f3ab27c41d0" }'
# → { "otpChallengeId": "…", "channel": "EMAIL",
#     "destinationMasked": "a***@example.com", "expiresAt": "…" }
 
# 2) exchange the challenge id + code for a session JWT
curl -X POST https://api-gateway.lunixi.com/api/portal/v1/otp/verify \
  -H "Content-Type: application/json" \
  -d '{
    "token": "cp_9f3ab27c41d0",
    "otpChallengeId": "1f0c7f2e-3f4a-4b1e-9a34-1f4f0b6c2d81",
    "otpCode": "482913"
  }'

Reading portal data

All read endpoints take the session JWT in x-portal-session:

curl https://api-gateway.lunixi.com/api/portal/v1/subscriptions \
  -H "x-portal-session: <session-jwt>"

Self-service actions

All four write actions take the session JWT as sessionToken in the request body (not the x-portal-session header):

Start a subscription

curl -X POST https://api-gateway.lunixi.com/api/portal/v1/subscriptions/start \
  -H "Content-Type: application/json" \
  -d '{
    "sessionToken": "<session-jwt>",
    "planId": "plan_01JX2G3M8V",
    "paymentMethodToken": "pmt_01JX7D2W5K",
    "idempotencyKey": "portal-start-84172"
  }'

Cancel — with e-mail confirmation

curl -X POST https://api-gateway.lunixi.com/api/portal/v1/subscriptions/cancel \
  -H "Content-Type: application/json" \
  -d '{
    "sessionToken": "<session-jwt>",
    "subscriptionId": "sub_01JX5B8R3M",
    "cancelAtPeriodEnd": true,
    "emailConfirmationToken": "ect_01JX8E4Y7N"
  }'

Hosted portal vs SDK embed

For embedding, the JS SDK offers Lunixi.portal.mount() (drop-in portal UI), Lunixi.portal.create() (headless — you build the UI on top of the same flows) and hybrid pieces like Lunixi.portal.plans.mount() / cardForm.mount(). The embed is bootstrapped server-side with your secret key via POST /api/v1/subscriptions/portal/sdk-session (customerId, origin, sdkMode: FULL | HEADLESS | HYBRID). Full SDK reference: Pricing & Portal SDK.

Errors

Webhooks

Portal actions produce the same events as their merchant-API equivalents, so your backend hears about self-service changes automatically:

Next steps

• Pricing & Portal SDK — embed the portal or the pricing catalog
• Subscriptions — the merchant-side view of the same lifecycle
• Invoices — what customers see under their invoice tab