跳到主要内容

POST /api/private/v1/subscriptions/activate

直接为任意客户激活或延长某个套餐。

该接口遵循统一的同组续费链规则，不会让同一套餐组（group）下多个套餐同时生效。

请求体​

{
  "customer": { "type": "email", "value": "user@example.com" },
  "plan": "pro",
  "duration": "P30D"
}
字段类型必填说明
customer.typestring是客户标识类型，最大 16 个字符
customer.valuestring是客户标识值，最大 128 个字符
planstring是套餐标识（slug）
durationstring否ISO-8601 时长字符串，可空

生效规则​

  • 同组同套餐 + 有限时：视为续费，直接延长
  • 同组升级：当前套餐立即结束，剩余价值按面值折算到新套餐
  • 同组降级购买：排队到当前链尾
  • 同组永久免费基础 + 限时高级：高级到期后会自动恢复基础计划
  • 同组永久高级后再购买低级：返回冲突错误
  • 跨组套餐：彼此独立，可以同时生效

成功响应​

HTTP 状态码 201：

{
  "ok": true,
  "requestId": "req_123",
  "data": {
    "id": 10,
    "customer": { "id": 1, "username": "customer_001" },
    "plan": { "id": 2, "slug": "pro", "name": "Pro" },
    "validFrom": "2026-03-21T00:00:00.000Z",
    "validTo": "2026-04-21T00:00:00.000Z",
    "status": "ACTIVE"
  }
}

可能错误​

  • 404 CUSTOMER_NOT_FOUND
  • 404 PLAN_NOT_FOUND
  • 409 REDUNDANT_PERMANENT_PURCHASE
  • 409 PERMANENT_TAIL_CONFLICT
  • 400 INVALID_PLAN_VALUE
  • 400 INVALID_SUBSCRIPTION_CHAIN