Merchant orders
Review a merchant's orders in the Dashboard — list and filter them, open one for its full detail, and issue a refund.
An order is the record of something bought: its line items, its customer, and the transactions that paid for it. These endpoints back the Dashboard's orders screen.
Orders are created by every purchase path — a direct API charge, a completed checkout session, or a subscription renewal — so this is the one place that shows commerce across all of them. Refunding here reverses captured funds through the same provider that took the payment.
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.
Endpoints
GET/api/v1/merchant/orders
Auth: Dashboard session (JWT bearer). Merchant membership required.
List orders for merchant.
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) |
subscription_id | string | No | Filter by subscription ID |
Example request
curl -G https://api.tokeflow.com/api/v1/merchant/orders \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "status=['active']" \
--data-urlencode "order_type=api"GET/api/v1/merchant/orders/:id
Auth: Dashboard session (JWT bearer). Merchant membership required.
Get order by ID.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
Example request
curl https://api.tokeflow.com/api/v1/merchant/orders/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"GET/api/v1/merchant/orders/:id/attempts/:attemptId/raw-response
Auth: Dashboard session (JWT bearer). Merchant 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/merchant/orders/obj_1a2b3c4d/attempts/123/raw-response \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"POST/api/v1/merchant/orders/:id/refund
Auth: Dashboard session (JWT bearer). Merchant 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/merchant/orders/obj_1a2b3c4d/refund \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
-H "Content-Type: application/json" \
-d '{
"amount": 15000,
"reason": "requested_by_customer"
}'GET/api/v1/merchant/orders/:id/refunds
Auth: Dashboard session (JWT bearer). Merchant 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/merchant/orders/obj_1a2b3c4d/refunds \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
--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. |