Customer Portal sessions and config

The Customer Portal lets a customer manage their own subscriptions and payment methods without contacting support. A session begins with a magic link: the customer requests a link by email, then the verify step exchanges the emailed token for a session cookie. These endpoints cover that handshake, the current session, the bootstrap payload the UI loads first, and the portal's configuration.

Everything else in the portal — subscriptions, payment methods, account — runs on the cookie established here. The portal is white-label, so its branding and allowed actions come from the merchant's portal config.

The portal session

Returned by the list and retrieve endpoints on this page.

Endpoints

GET/api/v1/merchants/:merchant_id/portal-config

Branding and behaviour of the self-service portal your customers use to manage their subscriptions. Returns defaults when nothing has been configured yet.

Path parameters

Example request

curl https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/portal-config \
  -H "Cookie: tf_portal_session=…"

Example response — 200

{
  "merchant_id": "mrc_123",
  "allow_cancellation": true,
  "allow_plan_change": true,
  "allow_payment_method_change": true,
  "cancellation_survey": true,
  "custom_cancellation_message": "Operation completed successfully"
}

PUT/api/v1/merchants/:merchant_id/portal-config

Upserts the configuration — the first call creates it, later calls replace the fields you send.

Path parameters

Request fields

Example request

curl -X PUT https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/portal-config \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_cancellation": true,
    "allow_plan_change": true,
    "allow_payment_method_change": true,
    "cancellation_survey": true,
    "custom_cancellation_message": "Operation completed successfully"
  }'

Example response — 200

{
  "merchant_id": "mrc_123",
  "allow_cancellation": true,
  "allow_plan_change": true,
  "allow_payment_method_change": true,
  "cancellation_survey": true,
  "custom_cancellation_message": "Operation completed successfully"
}

POST/api/v1/portal/auth/email-change/confirm

Confirm an email change via the emailed token.

Request fields

Example request

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/email-change/confirm \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "string"
  }'

POST/api/v1/portal/auth/logout

Clear the portal session cookie.

Example request

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/logout \
  -H "Cookie: tf_portal_session=…"

GET/api/v1/portal/auth/me

Get the current portal session account.

Example request

curl https://api.tokeflow.com/api/v1/portal/auth/me \
  -H "Cookie: tf_portal_session=…"

Example response — 200

{
  "id": "cpa_123",
  "organization_id": "org_123",
  "merchant_id": "mrc_123",
  "email": "customer@example.com",
  "expires_in": 1800
}

POST/api/v1/portal/auth/request-link

Request a portal magic-link email.

Request fields

Example request

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/request-link \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_123",
    "merchant_id": "mrc_123",
    "email": "customer@example.com"
  }'

POST/api/v1/portal/auth/verify

Verify a magic-link token; sets the session cookie.

Request fields

Example request

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/verify \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "string"
  }'

Example response — 200

{
  "id": "cpa_123",
  "organization_id": "org_123",
  "merchant_id": "mrc_123",
  "email": "customer@example.com",
  "expires_in": 1800
}

GET/api/v1/portal/bootstrap

Resolve merchant branding + flags for the portal.

Query parameters

Example request

curl -G https://api.tokeflow.com/api/v1/portal/bootstrap \
  -H "Cookie: tf_portal_session=…" \
  --data-urlencode "merchant_id=mrc_123" \
  --data-urlencode "organization_id=org_123" \
  --data-urlencode "merchant=acme-store"

Example response — 200

{
  "organization_id": "org_123",
  "merchant_id": "mrc_123",
  "merchant_slug": "acme-store",
  "merchant_name": "Acme Store",
  "branding": {
    "site_title": "Acme Store",
    "favicon": "string",
    "logo_light_mode": "string",
    "logo_dark_mode": "string",
    "theme_primary_color": "#1A73E8",
    "theme_secondary_color": "#0B5394",
    "custom_url": "https://acme.example.com",
    "show_name_with_logo": false
  },
  "config": {
    "allow_cancellation": true,
    "allow_plan_change": true,
    "allow_payment_method_change": true,
    "cancellation_survey": false,
    "custom_cancellation_message": "Operation completed successfully"
  }
}

Errors

Errors use the standard envelope. The most common cases here:

Related

• Portal subscriptions
• Portal payment methods
• Merchant portal config