Merchant dashboard overview
The statistics endpoint behind the merchant dashboard home screen — order volumes, approval and failure rates, trend data, and recent orders for a date window.
The merchant dashboard's home screen is powered by a single statistics endpoint. Given a date window, it returns the aggregate numbers the dashboard renders as headline tiles (total orders, approval rate, failure rate), plus the datasets behind its charts: an order trend series, a status distribution breakdown, and the most recent orders.
All figures are computed over orders — the commercial record that groups one or more charge attempts — not over individual transactions. An order that failed on the first provider and succeeded on a fallback counts once, as a successful order. See Orders for how orders relate to transactions.
Dashboard endpoints power the Tokeflow Dashboard UI. They are session-authenticated: sign in to obtain a JWT and send it as a bearer token. They do not accept sk_ or pk_ API keys — for programmatic reporting, use the public API instead.
The statistics object
The response is a single statistics object (no envelope):
| 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 | Authorized orders / total, as a percentage with 1 decimal place. |
failure_rate | number | Failed orders / total, as a percentage with 1 decimal place. |
success_rate | number | Alias of approval_rate, kept for client compatibility. Always equals approval_rate. |
order_trend | array | Time series of order activity across the window — one OrderTrendPointDto per point. Feeds the dashboard's trend chart. |
status_distribution | array | Breakdown of orders by status — one StatusDistributionItemDto per status bucket. Feeds the dashboard's distribution chart. |
recent_orders | array | The latest orders in the window — one RecentOrderDto per order. Feeds the dashboard's recent-activity list. |
All eight fields are always present in the response.
An order counts as successful once it reaches authorization, even if it is later refunded or charged back — refunded, partially_refunded, and charged_back orders were still approved charges. approval_rate and failure_rate do not necessarily sum to 100: orders that are canceled or still in flight belong to neither bucket.
Endpoints
GET/api/v1/merchant/dashboard/stats
Auth: Dashboard session (JWT bearer). Merchant membership required.
Returns the merchant dashboard statistics for the requested date window.
Header parameters
| Field | Type | Required | Description |
|---|---|---|---|
x-merchant-id | string | Yes | The merchant to report on, prefixed mrc_. Selects the active merchant context when your account belongs to more than one merchant. |
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
date_from | string | Yes | Start of the reporting window (ISO 8601 timestamp, inclusive). |
date_to | string | Yes | End of the reporting window (ISO 8601 timestamp, inclusive). |
The dashboard UI requests common presets — last 7 days, last 30 days, month to date. When calling the endpoint yourself, keep the window as tight as your use case allows; the aggregates are computed over every order in the range.
Example request
curl -G https://api.tokeflow.com/api/v1/merchant/dashboard/stats \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
-H "x-merchant-id: mrc_123" \
--data-urlencode "date_from=2026-07-01T00:00:00Z" \
--data-urlencode "date_to=2026-07-31T23:59:59Z"Example response — 200 OK
{
"total_orders": 59,
"successful_orders": 42,
"approval_rate": 71.2,
"failure_rate": 8.5,
"success_rate": 71.2,
"order_trend": [],
"status_distribution": [],
"recent_orders": []
}The three arrays are shown empty above for brevity. In a real response, order_trend carries one point per interval in the window, status_distribution carries one bucket per order status present in the window, and recent_orders carries the latest orders — each item following the OrderTrendPointDto, StatusDistributionItemDto, and RecentOrderDto shapes respectively.
In this example, 42 of 59 orders reached authorization (42 / 59 = 71.2%) and 5 failed outright (5 / 59 = 8.5%); the remaining orders were canceled or still in flight, so they count toward neither rate.
Errors
| HTTP | Typical cause |
|---|---|
400 | Missing or invalid date_from / date_to. |
401 | Missing, invalid, or expired session token — sign in again. |
403 | The session's account is not a member of the merchant in x-merchant-id. |
See Errors for the error format used across the API.
Related
- Orders — the resource these statistics aggregate.
- Transactions — individual charge attempts behind each order.
- Organizations and merchants — how merchant membership works.
- Dashboard invitations — invite teammates to the dashboard.