订阅

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

端点

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

列出

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

响应：

{
  "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"
    }
  ]
}

创建——带宽订阅

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 批次首次下单后默认自动续费。要为已存在批次开启自动续费：

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 折。

修改

升级或降级：

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

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

ISP 数量变更：

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

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

暂停 / 取消

# 暂停——保留当前周期资源，不续费
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 管理 中描述的 7 天宽限期。

错误

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