Customer Portal account
Let a customer view and update their own profile, and see their billing and order history in the portal.
These endpoints let a signed-in customer manage their account: read and update their profile, confirm an email change, and browse their billing and order history.
Everything is scoped to the customer that owns the session. Sensitive changes such as an email update go through a confirmation step to prove the customer controls the new address.
These endpoints power the Customer Portal — the self-service surface your end customers use, under your brand. They are authenticated by a portal session cookie, established through the magic-link flow (request a link, then verify the token), not by an API key. See Sessions & config.
The profile object
Returned by the list and retrieve endpoints on this page.
| Field | Type | Description |
|---|---|---|
id | string | — |
name | string | null | — |
email | string | — |
phone | string | null | — |
document_type | string | null | — |
document_number | string | null | Masked — only the last digits are shown. |
merchant_name | string | null | — |
created_at | string | (ISO 8601 UTC). |
Endpoints
GET/api/v1/portal/orders
Auth: Customer Portal session (cookie set by the magic-link flow).
List billing history.
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
page | number | No | Default 1, min 1. |
limit | number | No | Default 20, min 1, max 100. |
date_from | string | No | ISO date — orders on/after |
date_to | string | No | ISO date — orders on/before |
Example request
curl -G https://api.tokeflow.com/api/v1/portal/orders \
-H "Cookie: tf_portal_session=…" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "date_from=string" \
--data-urlencode "date_to=string"Example response — 200
{
"data": [
{
"id": "ord_123",
"order_type": "renewal",
"total_amount": 4990,
"currency": "BRL",
"status": "authorized",
"description": "Premium Monthly \u2014 Renewal",
"created_at": "2026-01-15T12:30:00.000Z"
}
],
"total": 42,
"page": 1,
"limit": 20
}GET/api/v1/portal/orders/:id
Auth: Customer Portal session (cookie set by the magic-link flow).
Get one order (invoice) detail.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
Example request
curl https://api.tokeflow.com/api/v1/portal/orders/obj_1a2b3c4d \
-H "Cookie: tf_portal_session=…"Example response — 200
{
"id": "ord_123",
"order_type": "renewal",
"total_amount": 4990,
"currency": "BRL",
"status": "authorized",
"description": "Premium Monthly \u2014 Renewal",
"created_at": "2026-01-15T12:30:00.000Z",
"items": [
{
"product_name": "Premium Plan",
"offer_name": "Premium Monthly",
"quantity": 1,
"unit_amount": 4990,
"total_amount": 4990,
"installments": 1
}
],
"payment_method": "visa \u2022\u2022\u2022\u2022 4242"
}GET/api/v1/portal/profile
Auth: Customer Portal session (cookie set by the magic-link flow).
Get the customer profile.
Example request
curl https://api.tokeflow.com/api/v1/portal/profile \
-H "Cookie: tf_portal_session=…"Example response — 200
{
"id": "cust_123",
"name": "Jane Doe",
"email": "jane@example.com",
"phone": "+5511999990000",
"document_type": "cpf",
"document_number": "\u2022\u2022\u2022\u2022\u2022\u2022\u202289",
"merchant_name": "Acme Store",
"created_at": "2026-01-15T12:30:00.000Z"
}PUT/api/v1/portal/profile
Auth: Customer Portal session (cookie set by the magic-link flow).
Update name / phone / document.
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | — |
phone | string | No | — |
document_type | string | No | One of cpf, cnpj, passport, tax_id. |
document_number | string | No | — |
Example request
curl -X PUT https://api.tokeflow.com/api/v1/portal/profile \
-H "Cookie: tf_portal_session=…" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Doe",
"phone": "+55 11 99999-0000",
"document_type": "cpf",
"document_number": "12345678909"
}'Example response — 200
{
"id": "cust_123",
"name": "Jane Doe",
"email": "jane@example.com",
"phone": "+5511999990000",
"document_type": "cpf",
"document_number": "\u2022\u2022\u2022\u2022\u2022\u2022\u202289",
"merchant_name": "Acme Store",
"created_at": "2026-01-15T12:30:00.000Z"
}POST/api/v1/portal/profile/email-change
Auth: Customer Portal session (cookie set by the magic-link flow).
Request an email change (sends a confirmation).
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
new_email | string | Yes | — |
Example request
curl -X POST https://api.tokeflow.com/api/v1/portal/profile/email-change \
-H "Cookie: tf_portal_session=…" \
-H "Content-Type: application/json" \
-d '{
"new_email": "new@example.com"
}'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. |