> For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt.

# 订阅管理

:::note 适用范围
本页适用于 **Halo 商城版 2.27.0 及以上版本**，限 [Halo 商城版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC) 可用。
:::

订阅产品用于销售按周期提供的服务，例如 SaaS 套餐、会员服务或许可证。与一次性售卖的商品不同，订阅有自己的生命周期：试用、生效、续费、变更、取消与过期。

本页面向商家，介绍控制台配置和日常管理。接入方实现权益开通、订阅同步和交付回执时，请阅读[商城集成文档](https://docs.halo.run/developer-guide/shop/integration/overview.md)。

:::warning 手动续费模式
Halo **不保存客户的支付凭据，也不会自动扣款**。连续购买的订阅到期前会向客户发送提醒，客户需要在个人中心手动完成续费。
:::

## 创建订阅产品

登录 Halo 控制台，进入 **商店 -> 产品**，点击右上角的新建按钮，将产品类型选择为 **订阅**。

- 订阅产品表示一条产品线，创建后**不可修改产品类型**。
- 订阅产品不配置规格价格，价格与周期在订阅计划中配置。
- 创建保存后，在产品编辑页面进入 **订阅设置**，按 **添加档次 -> 添加计划** 的顺序完成配置；上架前请至少添加一个可售计划。

## 订阅档次

档次是产品线下的商业等级（例如基础版、专业版），是权益契约的归属单位。同一档次下的月付、年付、买断计划共享同一份权益。

每个档次可以配置：

- **名称**：档次的显示名称。
- **标识**：接入方识别用的稳定键，同一产品线下不可重复，例如 `professional`。
- **排序**：数字越小越靠前。档次排序同时决定变更方向：目标档次排序值更大为升级，相同为平移；**降级不被支持**。
- **接入契约**：给接入方系统读取的键值数据，支持字符串、数字、布尔三种类型。契约不会展示给客户，键名需与接入方约定。

## 订阅计划

计划是客户实际购买的套餐，由档次、计费模式和计费周期组成。

| 配置项     | 说明                                                  |
| ------- | --------------------------------------------------- |
| 档次      | 计划所属的档次。                                            |
| 计费模式    | 连续购买（到期前提醒，客户手动续费）、单期购买（到期自动停用，需要重新购买）、永久买断（一次性付费）。 |
| 计费周期    | 控制台可选择按月或按年，周期数固定为 1，暂不支持配置季付等多周期组合。                |
| 价格 / 原价 | 计划的实际价格与可选的划线价。                                     |
| 状态      | 草稿、已发布、已归档；只有已发布的计划可以被购买。                           |
| 启用试用    | 开启后可配置试用天数和试用价格，客户可按试用价开通。                          |
| 数量上下限   | 单个订阅允许购买的最小与最大数量。                                   |
| 宽限期（天）  | 仅连续购买有效：到期未续费后，订阅进入逾期状态的容忍天数，宽限期结束后订阅过期。            |

## 变更规则

变更规则决定客户的现有订阅可以切换到哪些计划：

- 只允许**同一计费周期内**的变更，且目标档次不得低于来源计划（升级或平移）；跨周期（月付 ↔ 年付）与降级都无法配置。
- 每个允许的变更方向都需要单独配置一条规则并启用，未配置规则的方向一律拒绝变更。
- 费用模式：
  - **按剩余价值折算**（推荐）：新一期全价减去当前计划未使用部分的价值。
  - **固定费用（按数量）**：按设置的单价 × 订阅数量收取一期费用。
  - **免费**：变更不收费。
- 变更支付完成后立即生效，并从生效时刻起开一期完整新周期；变更不修改订阅数量。

## 订阅策略

- **每客户仅允许一个订阅**：开启后（默认），客户同时只能持有一个生效订阅，重复购买会被拦下并引导去变更或续费；关闭后每次购买都会新建独立订阅，适用于许可证类产品。

## 管理订阅

进入 **商店 -> 订阅**（需要超级管理员权限），可以查看所有客户订阅：

- 列表支持关键词搜索，并可按状态（试用中、生效中、逾期、已取消、已过期）和产品线筛选。
- 订阅详情展示摘要、当前计划、有效权益、订阅周期与变更记录（新购、续费、变更、转正、取消、过期）。
- 可以对未终止的订阅执行 **立即取消**：订阅立即变为已取消，不会退款。

## 客户自助管理

客户登录后，可以在个人中心的 **订阅** 菜单中管理自己的订阅：

- 查看订阅状态、周期与变更记录。
- **立即续费**：按当前价格创建续费订单，支付后周期顺延；续费订单 24 小时未支付会自动过期。
- **立即转正**：试用中的订阅通过续费入口创建转正订单，支付首期后进入正式计费周期。
- **变更**：在变更页面选择目标计划并查看报价，确认支付后立即生效。
- **取消**：默认可选择到期取消（当前周期结束后取消，周期内仍可使用）；仅当订阅已逾期时才允许立即取消，立即取消不会退款。

## 续费提醒邮件

连续购买的订阅在到期前会向客户发送一次提醒邮件（试用中的订阅则提醒转正），已设置到期取消的订阅不发送。

提醒邮件依赖系统邮件通知配置，请先在 **设置 -> 通知设置** 中配置好[邮件通知](https://docs.halo.run/guide/use/settings.md#%E9%82%AE%E4%BB%B6%E9%80%9A%E7%9F%A5)，否则客户无法收到提醒。

:::info 单期购买不发提醒
只有连续购买的计划会发送到期提醒；单期购买的订阅到期后直接过期。
:::

## 相关设置

在 **商店 -> 设置** 中可以配置 **显示个人中心订阅菜单**：关闭后隐藏个人中心的订阅菜单并限制订阅列表页访问，不影响已有订阅。参见[商店设置](https://docs.halo.run/guide/shop/settings.md#%E8%AE%A2%E9%98%85%E8%8F%9C%E5%8D%95)。

## 限制

- 不支持自动扣款与自动续费，续费必须由客户手动发起。
- 不支持降级、跨计费周期变更与订阅暂停。
- 订阅产品要求客户登录后购买；即使开启[匿名购买](https://docs.halo.run/guide/shop/settings.md#%E5%85%81%E8%AE%B8%E5%8C%BF%E5%90%8D%E8%B4%AD%E4%B9%B0)，订阅产品也不支持游客结账。
- 订阅订单行不会在控制台手动发货，也不会自动发放卡密或数字资源，需要接入方系统对接交付，详见[商城订阅对接](https://docs.halo.run/developer-guide/shop/integration/overview.md)。

## 相关文档

- [商城订阅对接](https://docs.halo.run/developer-guide/shop/integration/overview.md)：面向接入方的 Webhook 与履约上报对接说明。
- [订阅生命周期](https://docs.halo.run/developer-guide/shop/integration/subscription-lifecycle.md)：订阅状态机与周期语义。
- [商城客户中心](https://docs.halo.run/guide/shop/customer-center.md)：客户在个人中心的其他自助能力。