Merchant portal config
Configure the Customer Portal for a merchant — branding and the self-service actions customers are allowed to take.
These endpoints control how the Customer Portal looks and behaves for this merchant: the branding customers see and which self-service actions they may perform, such as changing a plan or updating a card.
The portal runs under your brand, so its configuration belongs to the merchant rather than to Tokeflow. Changes take effect on the customer's next portal session.
These endpoints power the Tokeflow Dashboard UI. They are session-authenticated (JWT bearer) — the token comes from signing in to the Dashboard, not from an sk_/pk_ API key. Requests also carry the x-merchant-id header identifying the merchant in context, and the signed-in user must be a member with access to it.
The portal config object
Returned by the list and retrieve endpoints on this page.
| Field | Type | Description |
|---|---|---|
merchant_id | string | — |
allow_cancellation | boolean | — |
allow_plan_change | boolean | — |
allow_payment_method_change | boolean | — |
cancellation_survey | boolean | — |
custom_cancellation_message | string | null | — |
Endpoints
GET/api/v1/merchant/portal-config
Auth: Dashboard session (JWT bearer). Merchant membership required.
Get the customer-portal configuration.
Example request
curl https://api.tokeflow.com/api/v1/merchant/portal-config \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"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/merchant/portal-config
Auth: Dashboard session (JWT bearer). Merchant membership required.
Update the customer-portal configuration.
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
allow_cancellation | boolean | No | Allow customers to cancel via the portal. |
allow_plan_change | boolean | No | Allow customers to change plan via the portal. |
allow_payment_method_change | boolean | No | Allow customers to add a card during dunning. |
cancellation_survey | boolean | No | Show a cancellation survey. |
custom_cancellation_message | string | No | Markdown shown on the cancellation screen. |
Example request
curl -X PUT https://api.tokeflow.com/api/v1/merchant/portal-config \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
-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"
}Errors
Errors use the standard envelope. The most common cases here:
| HTTP | Meaning |
|---|---|
400 | Invalid parameters or a state that does not allow this operation. |
401 | Missing, expired, or invalid Dashboard session token. |
403 | Authenticated, but the signed-in user lacks access to this entity. |
404 | The record does not exist or is not visible to this entity. |