Organization orders
Review orders across the organization's merchants from the Dashboard — list and filter them and open one for full detail.
These endpoints roll up orders from every merchant in the organization into one place: filter by merchant, status, or time, and open an order to see its items and the transactions that paid for it.
It is the org-wide counterpart to the merchant orders screen — same order records, aggregated across merchants for reporting and support.
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.
Endpoints
GET/api/v1/org/orders
Auth: Dashboard session (JWT bearer). Organization membership required.
List orders for 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. |
status | array | No | Comma-separated list of order statuses |
order_type | string | No | Filter by order type |
recurrence | string | No | Filter by recurrence |
currency | string | No | Filter by currency (ISO 4217) |
search | string | No | Search by order ID, customer name, email, or external order ID |
start_date | string | No | Start date (ISO 8601) |
end_date | string | No | End date (ISO 8601) |
mode | string | No | live or test. Only orders whose most recent payment that reached a provider ran on a live (or test) connector. An order with no such payment matches neither. |
subscription_id | string | No | Filter by subscription ID |
Example request
curl -G https://api.tokeflow.com/api/v1/org/orders \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "status=['active']" \
--data-urlencode "order_type=api"GET/api/v1/org/orders/:id
Auth: Dashboard session (JWT bearer). Organization membership required.
Get order by ID.
The order detail includes the transactions that paid for it and each of their attempts. Each order and each transaction carries a mode (live, test, or null when no payment reached a provider), and each attempt carries is_test_mode. A failed attempt also shows decline_reason — Tokeflow's reason for the failure, the same value whichever provider answered — next to psp_decline_code and psp_error_type, the provider's own code and error class as it reported them.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
Example request
curl https://api.tokeflow.com/api/v1/org/orders/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"GET/api/v1/org/orders/:id/attempts/:attemptId/raw-response
Auth: Dashboard session (JWT bearer). Organization membership required.
Get raw PSP response for an attempt.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
attemptId | string | Yes | — |
Example request
curl https://api.tokeflow.com/api/v1/org/orders/obj_1a2b3c4d/attempts/123/raw-response \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"POST/api/v1/org/orders/:id/refund
Auth: Dashboard session (JWT bearer). Organization membership required.
Refund an order.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | No | Amount to refund in minor units (partial refund). Omit for full refund. |
reason | string | No | Reason for refund. One of duplicate, fraudulent, requested_by_customer. |
Example request
curl -X POST https://api.tokeflow.com/api/v1/org/orders/obj_1a2b3c4d/refund \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
-H "Content-Type: application/json" \
-d '{
"amount": 15000,
"reason": "requested_by_customer"
}'GET/api/v1/org/orders/:id/refunds
Auth: Dashboard session (JWT bearer). Organization membership required.
List refunds for an order.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
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/orders/obj_1a2b3c4d/refunds \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "page=1" \
--data-urlencode "limit=20"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. |