## 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.

Authentication: User (some parameters admin only) · Docs: https://www-demo.kuxitong.com/en/docs/api/orders

### GET `/api/v2/orders`

List orders · Authentication: User (some parameters admin only)

Query parameters:

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer |  | Page number, starting from 1 Default: 1 |
| `page_size` | integer |  | Items per page Default: 20 |
| `sort` | string |  | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
| `tenant_id` | integer |  | Admin only: filter by tenant. Ignored for tenant credentials, which only see their own tenant's data |
| `type` | string |  | Filter by order type (recharge/deduct/payment/package, etc.). |
| `status` | string |  | Filter by status. Values: ["unpaid","paid"] |
| `start` | string |  | Order time from (inclusive), RFC 3339. |
| `end` | string |  | Order time until (exclusive), RFC 3339. |

```sh
curl "https://panel.example.com/api/v2/orders" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/orders/stats`

Order amount statistics · Authentication: User (some parameters admin only)

Query parameters:

| Field | Type | Required | Description |
|---|---|---|---|
| `tenant_id` | integer |  | Admin only: filter by tenant. Ignored for tenant credentials, which only see their own tenant's data |
| `type` | string |  | Filter by order type (recharge/deduct/payment/package, etc.). |
| `status` | string |  | Filter by status. Values: ["unpaid","paid"] |
| `start` | string |  | Order time from (inclusive), RFC 3339. |
| `end` | string |  | Order time until (exclusive), RFC 3339. |
| `group_by` | string |  | Aggregation granularity, default day. Values: ["day","month","year"] |
| `utc_offset_minutes` | integer |  | Deprecated and kept only for compatibility with old callers (the range is still validated). Days, months and years are always split in the platform time zone (Asia/Shanghai), the same day boundary as today's traffic; this parameter no longer shifts them. |

```sh
curl "https://panel.example.com/api/v2/orders/stats" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/orders/{id}`

Get order · Authentication: User (some parameters admin only)

```sh
curl "https://panel.example.com/api/v2/orders/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/orders/{id}`

Update order remark · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `des` | string | Yes | Description |

```sh
curl -X PUT "https://panel.example.com/api/v2/orders/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"des":"线下转账已核对"}'
```

Orders object:

| Field | Type | Required | Description |
|---|---|---|---|
| `amount_cents` | integer |  | Amount in cents; negative for deductions. |
| `archived` | boolean |  | Moved into the archive table by the archiving task (read-only). |
| `created_at` | string |  | Created at (read-only) |
| `data` | object |  | Extra data (such as package purchase details). |
| `des` | string |  | Description |
| `group_by` | string |  | Aggregation granularity: day, month or year. Values: ["day","month","year"] |
| `id` | integer |  | Record ID (read-only) |
| `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. |
| `status` | string |  | Order status: unpaid or paid. Values: ["unpaid","paid"] |
| `tenant_id` | integer |  | Owner tenant (user) ID (read-only) |
| `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 (read-only) |