Orders orders
Orders created by recharges, deductions, online payments and package purchases; tenants see only their own, admins can see all tenants, and only the remark can be edited.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/ordersList orders
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
tenant_ids | string | Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403 |
type | string | Filter by order type (recharge/deduct/payment/package, etc.). |
pay_type | string | Filter by payment method (admin/balance/alipay/wxpay/usdt, etc.). |
status | string | Filter by status. |
currency | string | Filter by currency (ISO 4217); omitted = all currencies, amounts converted to the base currency at the order-time rate. |
start | string | Order time from (inclusive), RFC 3339. |
end | string | Order time until (exclusive), RFC 3339. |
/api/v2/orders/statsOrder amount statistics
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
tenant_ids | string | Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403 |
type | string | Filter by order type (recharge/deduct/payment/package, etc.). |
pay_type | string | Filter by payment method (admin/balance/alipay/wxpay/usdt, etc.). |
status | string | Filter by status. |
currency | string | Filter by currency (ISO 4217); omitted = all currencies, amounts converted to the base currency at the order-time rate. |
start | string | Order time from (inclusive), RFC 3339. |
end | string | Order time until (exclusive), RFC 3339. |
group_by | string | Aggregation granularity, default day. |
/api/v2/orders/{id}Get order
Authentication: User (some parameters admin only)
/api/v2/orders/{id}Update order remark
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
desRequired | string | Description |
Orders object
| Field | Type | Description |
|---|---|---|
amount_cents | integer | Amount in cents; negative for deductions. |
archived | boolean | Moved into the archive table by the archiving task (read-only). |
by_pay_type | OrderStatsPayType[] | Subtotals per payment method and direction (ascending by method, credit before debit; same type/status/time/tenant filters; same amount basis as items, so the total equals the items total); unpaid orders have an empty payment method. |
created_at | string | Created at |
currency | string | Currency of the amount (ISO 4217). |
data | object | Extra data (such as package purchase details); a top-up paying a shortfall carries intent (state pending/running/done/failed; code/reason explain a failure; user_package_id is the package fulfilled when done). |
des | string | Description |
group_by | string | Aggregation granularity: day, month or year. |
id | integer | Record ID |
items | OrderStatsItem[] | Items on this page |
ledger_id | integer | ID of the linked ledger entry; null if none. |
mch_order_no | string | Merchant order number (the gateway-side order number); null for non-online payments. |
paid_at | string | Payment time; null if unpaid. |
pay_type | string | admin/balance/alipay/wxpay, etc.; empty = unpaid. |
rate_to_base | string | Rate at order time: 1 unit of this currency = ? base currency (decimal string, 8 places); later rate changes do not affect it. |
status | string | Order status: unpaid or paid. |
tenant_id | integer | Owner tenant (user) ID |
transaction_id | string | Gateway-side transaction ID; empty if unpaid. |
type | string | recharge (admin recharge) / deduct (admin deduction) / payment (online payment) / package (package purchase), etc. |
updated_at | string | Updated at |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}