Organization dashboard overview
Read the organization's headline statistics — orders, approval rates, and the top merchants across every merchant in the org.
These read-only endpoints feed the organization's home dashboard: aggregate order and revenue figures, approval-rate trends, and leaderboards of the merchants that drive the most volume.
An organization spans every merchant it contains, so these numbers roll up across all of them. Use them for a bird's-eye view; drill into a single merchant through the merchant dashboard.
These endpoints power the Tokeflow Dashboard UI at the organization level. 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-organization-id header, and the signed-in user must be a member of that organization.
The dashboard stats object
Returned by the list and retrieve endpoints on this page.
| Field | Type | Description |
|---|---|---|
total_orders | number | Every order in the window, including rejected attempts. This is the denominator for approval_rate and failure_rate. |
successful_orders | number | Orders that reached authorization — authorized, refunded, partially_refunded, charged_back and refund_pending. Excludes failed and canceled attempts, and orders still in flight. |
approval_rate | number | Approval rate as a percentage (0-100). |
failure_rate | number | Failure rate as a percentage (0-100). |
order_trend | array | Order trend data for the last 7 days. |
status_distribution | array | Distribution of orders by status. |
top_merchants_by_orders | array | Top merchants by order count. |
top_merchants_by_approval | array | Top merchants by approval rate. |
Endpoints
GET/api/v1/org/dashboard/routing-overview
Auth: Dashboard session (JWT bearer). Organization membership required.
Get routing overview across all merchants in the organization.
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
page | number | No | Page number (1-indexed). Default 1, min 1. |
limit | number | No | Number of items per page. Default 20, min 1, max 100. |
Example request
curl -G https://api.tokeflow.com/api/v1/org/dashboard/routing-overview \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "page=1" \
--data-urlencode "limit=20"GET/api/v1/org/dashboard/stats
Auth: Dashboard session (JWT bearer). Organization membership required.
Get dashboard statistics for organization.
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
date_from | string | No | Start date for statistics (ISO 8601 format) |
date_to | string | No | End date for statistics (ISO 8601 format) |
Example request
curl -G https://api.tokeflow.com/api/v1/org/dashboard/stats \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "date_from=string" \
--data-urlencode "date_to=string"Example response — 200
{
"total_orders": 42,
"successful_orders": 1,
"approval_rate": 92.4,
"failure_rate": 92.4,
"order_trend": [
{
"date": "string",
"count": 42
}
],
"status_distribution": [
{
"status": "active",
"count": 42,
"percentage": 92.4
}
],
"top_merchants_by_orders": [
{
"merchant_id": "mrc_8a3f12d9",
"merchant_name": "Acme Store",
"order_count": 42
}
],
"top_merchants_by_approval": [
{
"merchant_id": "mrc_8a3f12d9",
"merchant_name": "Acme Store",
"approval_rate": 92.4,
"total_orders": 42
}
]
}GET/api/v1/org/dashboard/top-merchants/by-approval-rate
Auth: Dashboard session (JWT bearer). Organization membership required.
Top merchants by order approval rate for the organization.
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
date_from | string | No | Start date (ISO 8601). Defaults to 30 days ago. |
date_to | string | No | End date (ISO 8601). Defaults to now. |
limit | string | No | How many merchants to return (default 5, max 50) |
min_orders | string | No | Minimum order count for inclusion (default 10) |
Example request
curl -G https://api.tokeflow.com/api/v1/org/dashboard/top-merchants/by-approval-rate \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "date_from=string" \
--data-urlencode "date_to=string" \
--data-urlencode "limit=string" \
--data-urlencode "min_orders=string"Example response — 200
{
"data": [
{
"merchant_id": "mrc_8a3f12d9",
"merchant_name": "Acme Store",
"approval_rate": 92.4,
"total_orders": 42
}
]
}GET/api/v1/org/dashboard/top-merchants/by-orders
Auth: Dashboard session (JWT bearer). Organization membership required.
Top merchants by total order count for the organization.
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
date_from | string | No | Start date (ISO 8601). Defaults to 30 days ago. |
date_to | string | No | End date (ISO 8601). Defaults to now. |
limit | string | No | How many merchants to return (default 5, max 50) |
Example request
curl -G https://api.tokeflow.com/api/v1/org/dashboard/top-merchants/by-orders \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "date_from=string" \
--data-urlencode "date_to=string" \
--data-urlencode "limit=string"Example response — 200
{
"data": [
{
"merchant_id": "mrc_8a3f12d9",
"merchant_name": "Acme Store",
"order_count": 42
}
]
}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. |