## 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.gocdn888.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 (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. Values: ["unpaid","paid"] |
| `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. |

```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 (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. Values: ["unpaid","paid"] |
| `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. Values: ["day","month","year"] |

```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). |
| `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 (read-only) |
| `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. 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. |
| `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. 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) |
