# 订阅

订阅是周期性订单——对应按月流量套餐（住宅 / 移动）与按月 ISP 续费。API 与 **控制台 → 账单 → 套餐** 中配置的内容一一对应。

## 端点

| 方法      | 路径                           | 用途             |
| ------- | ---------------------------- | -------------- |
| `GET`   | `/subscriptions`             | 列出活跃订阅         |
| `POST`  | `/subscriptions`             | 创建订阅           |
| `GET`   | `/subscriptions/{id}`        | 获取单个           |
| `PATCH` | `/subscriptions/{id}`        | 改数量、套餐档位、周期    |
| `POST`  | `/subscriptions/{id}/pause`  | 暂停续费（当前周期资源保留） |
| `POST`  | `/subscriptions/{id}/cancel` | 取消（周期结束生效）     |

## 列出

```bash
curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/subscriptions
```

响应：

```json
{
  "data": [
    {
      "id":           "sbn_01HX2K3PQ4M5",
      "product":      "residential",
      "plan":         "pro",
      "cycle":        "monthly",
      "gb_included":  500,
      "price_usd":    1500.00,
      "status":       "active",
      "renews_at":    "2026-06-01T00:00:00Z"
    },
    {
      "id":           "sbn_01HX2K4ABCD",
      "product":      "isp",
      "batch_id":     "bat_01HXabc",
      "cycle":        "annual",
      "quantity":     20,
      "price_usd":    1200.00,
      "status":       "active",
      "renews_at":    "2027-01-15T00:00:00Z"
    }
  ]
}
```

## 创建——带宽订阅

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "product": "residential",
       "plan":    "pro",
       "cycle":   "monthly"
     }' \
     https://api.helodata.com/v1/subscriptions
```

住宅档位：`starter`（50 GB）、`pro`（500 GB）、`business`（2000 GB）、`enterprise`（定制）。移动同名但 GB 上限更低。

## 创建——ISP 续费订阅

ISP 批次首次下单后默认自动续费。要为已存在批次开启自动续费：

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{
       "product":  "isp",
       "batch_id": "bat_01HXabc",
       "cycle":    "annual"           // 或 "monthly"
     }' \
     https://api.helodata.com/v1/subscriptions
```

年度周期相比同等月度享 9 折。

## 修改

升级或降级：

```bash
curl -X PATCH -H "Authorization: Bearer API_KEY" \
     -d '{"plan": "business"}' \
     https://api.helodata.com/v1/subscriptions/sbn_01HX2K3PQ4M5
```

升级在当前周期内**按比例**计费；降级在下个周期生效。

ISP 数量变更：

```bash
curl -X PATCH -H "Authorization: Bearer API_KEY" \
     -d '{"quantity": 30}' \
     https://api.helodata.com/v1/subscriptions/sbn_01HX2K4ABCD
```

数量**增加**立即交付新 IP 并按比例计费；减少（释放 IP）在下次续费时生效。

## 暂停 / 取消

```bash
# 暂停——保留当前周期资源，不续费
curl -X POST -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/subscriptions/sbn_01HX/pause

# 取消——同效，外加订阅归档
curl -X POST -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/subscriptions/sbn_01HX/cancel
```

取消后，ISP 批次进入 [IP 管理](https://docs.helodata.com/helodata-zh/api-can-kao/pages/cFgkUq9quVGUMTS4XWgf#续费) 中描述的 7 天宽限期。

## 错误

| 状态码   | code                    | 含义            |
| ----- | ----------------------- | ------------- |
| `409` | `downgrade_below_usage` | 降级会低于当前周期实际用量 |
| `409` | `already_subscribed`    | 该产品+档位的订阅已存在  |
| `422` | `unknown_plan`          | 该产品下不存在此档位    |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/helodata-zh/api-can-kao/subscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.