## 产品特色
团体订阅能力是支付宝专为企业或团体用户订阅模型服务提供的解决方案，支持团体用户购买同一订阅套餐的多个席位。

团体用户在购买订阅产品时，需设置席位数量后通过授权将商户账号和用户支付宝账号进行绑定，借助支付宝账号资金渠道，直接帮助商家完成周期性的自动扣款。后续可将订阅套餐的席位数量进行增减，支付宝侧会同步计算相应差价或设定下周期生效。

![](https://mdn.alipayobjects.com/afts/img/A*mkd6T4XDf9kAAAAAVlAAAAgAeq8wAA/original?bz=openpt_doc&t=mbjW54E1SMZMs7ELzNr8HXZXXl_HUCm-TgFaMD5_Su8DAAAAZAAAMK8AAAAA)

## 订阅商品与价格管理
提供商品价格管理后台，商家可直接登录支付宝商家平台进行可视化配置，维护自己的商品和服务信息，并关联多种计价模式、设置默认价格等。

支付宝提供商品价格增删改查的全套API接口，支持商家直接调用。此外，支持商家进通过简单配置，通过低代码接入自动生成的商品展示页面与收银台页面。

![](https://mdn.alipayobjects.com/afts/img/A*2bOoTqxw19kAAAAAVjAAAAgAeq8wAA/original?bz=openpt_doc&t=ZWjuePwJuIByhBMe0OyGk0NL2jtpghW9iksRnnlAy3oDAAAAZAAAMK8AAAAA)

商家可按如下指引调用接口，进行商品管理、价格管理 等操作。

```mermaid
sequenceDiagram
    participant 商户
    participant 支付宝

    商户->>支付宝: 1: 管理后台/api创建商品信息（alipay.trade.product.create）
    支付宝-->>商户: 1.1: 返回商品id

    商户->>支付宝: 2: 管理后台/api创建商户下的价格信息（alipay.trade.price.create），该接口具备同时创建新商品
    支付宝-->>商户: 2.1: 返回价格id

    商户->>支付宝: 3: 管理后台/api设置商品下默认金额（alipay.trade.product.modify）
    支付宝-->>商户: 3.1: 返回设置结果
```

#### 商品创建
商家可调用 [alipay.trade.product.create（商品创建接口）](https://opendocs.alipay.com/solution/615bfd8c_alipay.trade.product.create.md)，获取 商品id(product_id)。

注意:

+ 商品名称（name）后续将在用户的签约页面进行展示，请务必保证名称的准确
+ 单位别名（unit_label）在团体席位订阅场景下该字段必传，后续在用户的签约页面进行展示，请务必保证名称的准确。
+ 商品模型元数据（metadata）支持商户进行自定义传参，用于记录商户需要消费的个性信息。

重要参数说明

| 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| name | 商品名称 | String | 是 | [1,255] | Gold 会员 | 商品名称 |
| description | 商品描述 | String | 是 | [1,255] | 基础权益 | 商品描述 |
| metadata | 商品模型元数据 | String | 否 | [1,2000] | {"key":"value"} | 商户需要保存在商品模型中的元数据 |
| unit_label | 单位别名 | String | 是 | [1,100] | 席位 | 单位别名 |


请求示例

```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "name":"Gold 会员",
 "description":"基础权益",
 "metadata":"{\"key\":\"value\"}",
 "unit_label":"席位"
}'
```

#### 修改商品
商家可调用 [alipay.trade.product.modify（商品修改接口）](https://opendocs.alipay.com/solution/26d7e027_alipay.trade.product.modify.md)，修改商品或设置商品的默认价格（price_id）。

注意：每个商品仅能配置一个价格为默认价格。

重要参数说明

| 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| product_id | 商品id | String | 是 | [1,32] | 20260324001001 | 本次更新的商品id，商品创建接口（alipay.trade.product.create）返回的商品id。 |
| name | 商品名称 | String | 否 | [1,255] | Gold 会员 | 商品名称 |
| description | 商品描述 | String | 否 | [1,255] | 基础权益 | 商品描述 |
| default_price_id | 默认价格id | String | 否 | [1,32] | 20260324001001 | 该商品默认价格id |
| metadata | 商品元数据 | String | 否 | [1,1024] | {"key":"value"} | 商品元数据 |


请求示例

```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "product_id":"20260324001001",
 "name":"Gold 会员",
 "description":"基础权益",
 "default_price_id":"20260324001001",
 "metadata":"{\"key\":\"value\"}"
}'
```

#### 商品查询
商家可调用 [alipay.trade.product.query（商品查询接口）](https://opendocs.alipay.com/solution/26a3e2e7_alipay.trade.product.query.md)，查询已创建的商品信息。

重要参数说明

| 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| product_id | 商品id | String | 是 | [1,32] | 202603230010000006783 | 商品创建接口（alipay.trade.product.create）返回的商品id。 |
| query_options | 查询选项 | array | 否 | [1,10] | ["price"] | 查询选项，商户通过上送该参数来定制额外返回的信息字段,数组格式。枚举支持:price(默认价格信息) |


请求示例

```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "product_id":"202603230010000006783",
 "query_options":[
 "price"
 ]
}'
```

#### 价格创建
商家可调用 [alipay.trade.price.create（价格创建接口）](https://opendocs.alipay.com/solution/5a02644d_alipay.trade.price.create.md)创建价格信息，获取价格实例id（price_id）。

注意：

+ 循环计价模型（recurring）：订阅类商品（含团体席位订阅商品），必传。
    - 计价周期单位（interval）：与 interval_count组合使用，支持枚举值为 DAY和MONTH，分别代表周期的单位为「天」或「月」。
    - 计价周期间隔（interval_count）：计价周期间隔，和 interval 组合使用。例如 interval 为 MONTH，interval_count = 1，则扣款周期为 1 月：系统以首次购买日期为周期起始日，下一周期起始日按设定间隔顺延，若目标日期不存在则自动调整至当月最后一天。例如首次购买日为1月31日，则下一周期起始日为2月28日（或29日），再下一周期起始日恢复为3月31日。实际扣款将在周期起始日前1天发起，确保资金及时到账，服务无缝续期。

重要参数说明

| 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| product_id | 商品id | String | 是 | [1,32] | 202603230010000006783 | 商品创建接口（alipay.trade.product.create）返回的商品id。 |
| unit_amount | 单位金额 | Number | 是 | [1,1000000000] | 1000 | 单位金额，单位:分 |
| recurring | 循环计价模型 | Object | 是 | - | - | 循环计价配置，用于订阅等场景 |
| ┗ interval | 计价周期单位 | String | 是 | [1,32] | MONTH | 计价周期单位，和interval_count组合使用。枚举值:MONTH(月)、YEAR(年)、DAY(日) |
| ┗ interval_count | 计价周期间隔 | Number | 是 | [1,10000] | 1 | 计价周期间隔，和interval组合使用 |
| metadata | 价格信息元数据 | String | 否 | [1,2000] | {"key":"value"} | 商户需要保存在价格模型中的元数据 |


请求示例

```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.price.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "unit_amount":1000,
 "product_id":"202603230010000006783",
 "recurring":{
  "interval_count":1,
  "interval":"MONTH"
 },
 "metadata":"{\"key\":\"value\"}"
}'
```

#### 价格查询
商家可调用 [alipay.trade.price.query（价格查询接口）](https://opendocs.alipay.com/solution/97ecc2ab_alipay.trade.price.query.md)，查询已创建的价格信息

重要参数说明

| 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| price_id | 价格id | String | 是 | [1,32] | 202603240020000001001 | 价格id，价格创建接口（alipay.trade.price.create）返回的价格id。 |
| query_options | 查询选项 | array | 否 | [1,10] | ["product"] | 查询选项，商户通过上送该参数来定制额外返回的信息字段,数组格式。枚举支持:product(商品信息) |


请求示例

```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.price.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "price_id":"202603240020000001001",
 "query_options":[
  "product"
 ]
}'
```

## 订阅商品首次购买
企业用户挑选商品、明确席位数量进行购买，商家将用户购买的商品传给支付宝，将自动生成付款链接或二维码，用户可直跳转至支付宝APP或扫码唤起支付宝APP进行产品订阅的信息确认，完成订阅和支付。

![](https://mdn.alipayobjects.com/afts/img/A*MkApRKes_VgAAAAAUvAAAAgAeq8wAA/original?bz=openpt_doc&t=7WF2bpw3YEzjfHP6gZI3dbbUC4UVmwQ9z8AiXYBksSADAAAAZAAAMK8AAAAA)

商家可按如下指引调用接口，进行客户创建、发起团体席位订阅、获取团体席位订阅消息通知 等操作。

```mermaid
sequenceDiagram
    participant 用户
    participant 商户
    participant 支付宝

    用户->>商户: 1: 发起订阅

    商户->>支付宝: 1.1: 若未创建过，则先调用api创建客户（alipay.trade.customer.create）
    支付宝-->>商户: 1.2: 返回支付宝侧客户id

    商户->>支付宝: 1.3: 创建订阅（alipay.trade.subscription.create）
    支付宝-->>商户: 1.4: 返回订阅id以及支付链接

    商户->>商户: 1.5: 消费支付链接，如果是网页版，展示支付二维码
    商户-->>用户: 1.6: 二维码展示

    商户->>支付宝: 1.7: 消费支付链接，如果是app端，则唤起支付宝，与二维码选其一对客

    用户->>支付宝: 2: 二维码场景：用户扫码进行支付；app端：唤起支付宝进行支付
    支付宝-->>商户: 2.1: 支付完成发送订阅生效消息（alipay.trade.subscription.changed）
```

#### 创建客户
商家可调用 [alipay.trade.customer.create（客户创建接口）](https://opendocs.alipay.com/solution/3727f613_alipay.trade.customer.create.md)创建客户，获取客户id（customer_id），后续与支付宝侧交互时用户身份使用该customer_id进行用户标识。

重要参数说明

| 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| name | 客户名称 | String | 是 | [1,64] | 张三 | 客户名称 |
| description | 客户描述 | String | 否 | [1,255] | 业务客户 | 客户描述 |
| phone | 客户手机号 | String | 否 | [1,50] | 15011112222 | 客户手机号，和客户邮箱需至少传入1个 |
| email | 客户邮箱 | String | 否 | [1,255] | email@antgroup.com | 客户邮箱，和客户手机号需至少传入1个 |


请求示例

```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.customer.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "name":"张三",
 "description":"业务客户",
 "phone":"15011112222",
 "email":"email@antgroup.com"
}'
```

#### 发起订阅
商家可调用 [alipay.trade.subscription.create（订阅创建接口）](https://opendocs.alipay.com/solution/7a8012f1_alipay.trade.subscription.create.md)，获取订阅id（subscription_id）和对应的支付链接。

注意：

+ 发起团体席位订阅时，需要在订阅项目信息（items）中，传入用户所购买的商品对应的价格id（price_id）和团体席位的数量quantity，来确定此次订阅购买的商品单价（单个席位的价格）和数量。
+ 发起订阅后商户将获得适用于跳转支付宝端的长链接alipay_jump_schema或适用于生成二维码的短链接alipay_schema，商户可根据实际场景自主选择使用。

重要参数说明

| 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| items | 订阅项目信息 | String | 是 |  |  | 订阅项目信息。 |
| ┗ price_id | 价格id | String | 是 | [1,64] | 202603201234567889 | 价格创建接口（alipay.trade.price.create）返回的价格id，代表本次操作的目标价格信息。 |
| ┗ quantity | 数量 | String | 是 | [1,8] | 10 | 购买的团体席位数量。 |
| customer_id | 支付宝客户id | String | 是 | [1,64] | 208812345678 | 客户id，客户创建接口（alipay.trade.customer.create）返回的客户id。 |


注意：其它参数若有传参需要，请与支付宝技术支持沟通确认

请求示例

```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "items":[
 {
   "price_id":"202603201234567889",
   "quantity":"10"
 }
 ],
 "customer_id":"208812345678"
}'
```

#### 获取订阅消息通知
商家通过订阅 [alipay.trade.subscription.changed（订阅产品商户消息通知接口）](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)来获取订阅商品的购买结果。

注意：

+ 该接口为支付宝主动向商户发送的消息通知接口，商户需要配置应用网关地址以及订阅消息服务，详情查看[接入准备](https://opendocs.alipay.com/solution/repo-046zj4.md)
+ 商户收到消息后需要返回success表示处理成功，否则返回fail，支付宝会进行重试。
+ 投递重试策略：25小时内完成8次通知，间隔频率为：2m、10m、10m、1h、2h、6h、15h。
+ 商户获取消息通知后，需要使用支付宝公钥进行验签。
+ 用户购买成功后，发送的订阅产品商户消息通知中的 订阅变更类型（change_type）为 订阅已生效（active）。
+ 生效周期字段：subscription中的current_period_start和current_period_end代表本次订阅支付对应的生效周期的起止时间。

重要参数说明

| 参数名 | 类型 | 必选 | 最大长度 | 示例值 | 描述 |
| --- | --- | --- | --- | --- | --- |
| change_type | string | 必选 | 32 | active | 订阅变更类型，枚举值：active-团体席位订阅已生效，用户完成首次支付签约；period_extend-订阅续费成功，周期性自动扣款成功；item_update-订阅项目席位数量扩容成功；item_downgrade-订阅项目席位数量缩容成功；cancel-订阅已取消，用户取消订阅或到期未续费；cancel_at_period_end-订阅将在周期结束取消 |
| change_date | string | 可选 | 32 | 2026-03-22 21:00:00 | 订阅变更时间 |
| trade_no | string | 可选 | 64 | 2026022276001434360514767918 | 支付宝交易号 |
| pay_amount | string | 可选 | 16 | 1001 | 当前订阅的支付金额，单位分 |
| subscription | string | 可选 | 20000 | 参考：alipay.trade.subscription.query接口返回的字段 | 订阅信息大对象 |


通知示例

```json
curl -X POST 'NOTIFY_URL' \
--header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'charset=UTF-8' \
--data-urlencode 'biz_content={
 "change_type":"active",
 "change_date":"2026-03-22 21:00:00",
 "trade_no":"2026022276001434360514767918",
 "order_no":"2026042019600065895",
 "pay_amount":"1001",
 "subscription":"订阅信息大对象，参考alipay.trade.subscription.query"
}' \
--data-urlencode 'utc_timestamp=${now}' \
--data-urlencode 'sign=${sign}' \
--data-urlencode 'app_id=${appid}' \
--data-urlencode 'version=1.1' \
--data-urlencode 'sign_type=RSA2' \
--data-urlencode 'notify_id=${notify_id}' \
--data-urlencode 'msg_method=alipay.trade.subscription.changed'
```

通知应答

| 响应报文 | 描述 | 是否重试 | 是否区分大小写 |
| :--- | :--- | :--- | :--- |
| success | 消息处理成功 | 否 | 否 |
| fail | 消息处理失败 | 是 | 否 |


#### 查询订阅
商家通过[alipay.trade.subscription.query（订阅查询接口）](https://opendocs.alipay.com/solution/d6b6c14f_alipay.trade.subscription.query.md) 来查询具体的订阅相关信息。

注意：

+ 入参推荐按照subscription_id精准查询，传参只传入subscription_id即可。
+ 返回结果中subscription_status代表对应订阅id的状态，调用方可以根据当前状态做相关的业务逻辑处理。
+ 返回结果中current_period_start和current_period_end代表截止到查询时刻，最近的一次订阅支付（用户首次订阅支付或周期扣款支付）对应的生效周期的起止时间。
+ 返回结果中start_date代表订阅首次支付成功对应的生效开始时间。
+ 返回结果中cancel_at_period_end代表当前订阅是否会在周期结束后取消。当订阅取消时（商户调取消接口取消/用户主动在支付宝端内取消），订阅并不会立即失效，而是会已生效的周期结束后才真正取消，商户可以基于查询到的该字段来确认是否会在周期结束后取消。
+ 返回结果中的items和pending_items，当用户执行席位数量缩减操作时，已完成扣款的计费周期内，席位数量保持缩减前的原数量不变，待计费周期结束后，系统自动将席位数量更新为缩减后的数量。
    - items：当前周期内生效的订阅项信息，含席位数量quantity（缩减前的原数量）。
    - pending_items：待生效周期的订阅项信息，含席位数量quantity（缩减后的新数量）。

重要参数说明

| 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| customer_id | 支付宝客户id | String | 是 | [1,64] | 202603210030100000003 | 支付宝客户id |
| subscription_status | 订阅状态 | String | 否 | [0,64] | ACTIVE | 订阅状态，枚举值：INCOMPLETE(未完成支付)、ACTIVE(活跃)、CANCELED(已取消) |
| subscription_id | 订阅id | String | 否 | [0,64] | 20260320123156789 | 订阅id |


请求示例

```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "subscription_status":"ACTIVE",
 "subscription_id":"20260320123156789",
 "customer_id":"202603210030100000003"
}'
```

响应参数说明

| 参数 | 名称 | 参数类型 | 描述 |
| :--- | :--- | :--- | :--- |
| subscriptions | 订阅详情信息 | Array | 订阅详情信息列表 |
| ┗ subscription_id | 订阅id | String | 订阅id |
| ┗ customer_id | 客户id | String | 客户id |
| ┗ subscribe_title | 订阅标题 | String | 订阅标题 |
| ┗ subscription_status | 订阅状态 | String | 订阅状态：INCOMPLETE(未完成)、ACTIVE(活跃)、INCOMPLETE_EXPIRED(未完成已过期)、CANCELED(已取消) |
| ┗ current_period_start | 最近一个扣款周期开始时间 | String | 最近一个扣款周期开始时间 |
| ┗ current_period_end | 最近一个扣款周期结束时间 | String | 最近一个扣款周期结束时间 |
| ┗ cancel_at_period_end | 周期结束是否失效 | Boolean | true-周期结束状态生效；false-周期结束依旧生效 |
| ┗ start_date | 订阅开始日期 | String | 订阅开始日期 |
| ┗ canceled_date | 订阅取消时间 | String | 订阅取消时间 |
| ┗ created | 创建时间 | String | 创建时间 |
| ┗ metadata | 订阅元数据 | String | 订阅元数据，订阅创建时传入 |
| ┗ items | 订阅项目信息 | Array | 订阅项目信息列表，详见 [alipay.trade.subscription.query（订阅查询接口）](https://opendocs.alipay.com/solution/d6b6c14f_alipay.trade.subscription.query.md) |
| ┗ pending_items | 待生效的订阅项 | Array | 待生效的订阅项列表，详见 [alipay.trade.subscription.query（订阅查询接口）](https://opendocs.alipay.com/solution/d6b6c14f_alipay.trade.subscription.query.md) |


## 订阅续费扣款
### 自动续费
当用户订阅的产品到达续费周期后，将自动从用户账户扣款。扣款成功后，支付宝将通过系统消息通知商户继续提供相应产品或服务进行履约。

默认扣款逻辑：

+ 扣款预通知：在订阅产品到期日前的2天，支付宝会向用户发送扣款预通知，提醒用户即将扣款；
+ 执行扣款：在订阅产品到期日的前1天，支付宝会对用户进行扣款；
+ 扣款重试：如果扣款失败，在订阅产品到期前，支付宝会持续根据算法进行多次扣款，直到扣款成功；
+ 扣款失败：若订阅产品已到期，支付宝将不再进行扣款，并解约订阅产品，将用户订阅状态置为失效。

获取续费结果：

商家通过调用 [alipay.trade.subscription.changed（订阅产品商户消息通知接口）](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)来获取订阅的续费结果。

注意：

+ 该接口为支付宝主动向商户发送的消息通知接口，商户需要配置应用网关地址以及订阅消息服务，详情查看[接入准备](https://opendocs.alipay.com/solution/repo-046zj4.md)
+ 商户收到消息后需要返回success表示处理成功，否则返回fail，支付宝会进行重试。
+ 投递重试策略：25小时内完成8次通知，间隔频率为：2m、10m、10m、1h、2h、6h、15h。
+ 商户获取消息通知后，需要使用支付宝公钥进行验签。
+ 用户续费成功后，发送的商户消息通知中的 订阅变更类型（change_type）为 订阅续费成功（period_extend）。
+ 生效周期字段：subscription中的current_period_start和current_period_end代表本次订阅支付对应的生效周期的起止时间。
+ 到期后仍未扣款成功，发送的商户消息通知中的 订阅变更类型（change_type）为 订阅已取消（cancel）。

| 参数名 | 类型 | 必选 | 最大长度 | 示例值 | 描述 |
| --- | --- | --- | --- | --- | --- |
| change_type | string | 必选 | 32 | period_extend或cancel | 订阅变更类型，枚举值：active-团体席位订阅已生效，用户完成首次支付签约；period_extend-订阅续费成功，周期性自动扣款成功；item_update-订阅项目席位数量扩容成功；item_downgrade-订阅项目席位数量缩容成功；cancel-订阅已取消，用户取消订阅或到期未续费；cancel_at_period_end-订阅将在周期结束取消 |
| change_date | string | 可选 | 32 | 2026-03-22 21:00:00 | 订阅变更时间 |
| trade_no | string | 可选 | 64 | 2026022276001434360514767918 | 支付宝交易号 |
| pay_amount | string | 可选 | 16 | 1001 | 当前订阅的支付金额，单位分 |
| subscription | string | 可选 | 20000 | 参考：alipay.trade.subscription.query接口返回的字段 | 订阅信息大对象 |


通知示例

```json
curl -X POST 'NOTIFY_URL' \
--header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'charset=UTF-8' \
--data-urlencode 'biz_content={
 "change_type":"period_extend",
 "change_date":"2026-03-22 21:00:00",
 "trade_no":"2026022276001434360514767918",
 "pay_amount":"1001",
 "subscription":"订阅信息大对象，参考alipay.trade.subscription.query"
}' \
--data-urlencode 'utc_timestamp=${now}' \
--data-urlencode 'sign=${sign}' \
--data-urlencode 'app_id=${appid}' \
--data-urlencode 'version=1.1' \
--data-urlencode 'sign_type=RSA2' \
--data-urlencode 'notify_id=${notify_id}' \
--data-urlencode 'msg_method=alipay.trade.subscription.changed'
```

### 主动续费
团体订阅场景除了支持自动续费外，还支持主动续费能力。当扣款失败后，支付宝侧会提供主动支付的能力，向用户的支付宝账户维护的邮箱或手机推送待支付链接，由用户点击后唤起支付宝收银台，进行主动支付。

## 订阅席位数量增加
针对已生效的团体订阅指定需要增加的席位数量，支付宝侧会按照最新的席位数量根据已发生扣款的周期（首次支付和周期扣款）计算出用户补贴价的金额，生成对应的支付链接，来让用户进行差价支付，支付成功后，订阅的席位数量会立即更新。

![](https://mdn.alipayobjects.com/afts/img/A*i5m-S4QP9SQAAAAASiAAAAgAeq8wAA/original?bz=openpt_doc&t=3e_FAO3yqBnCL4HQlJsqGrXjdkhs5OoxqiMy-veA7eUDAAAAZAAAMK8AAAAA)

商家可按如下指引调用接口，进行团体商品席位数量的增加并感知席位增加的结果。

```mermaid
sequenceDiagram
    participant 用户
    participant 商户
    participant 支付宝

    用户->>商户: 1: 发起升级

    商户->>支付宝: 1.1: 订阅修改（alipay.trade.subscription.modify）
    支付宝->>支付宝: 1.1.1: 差价计算，计算用户需要实际支付的金额
    支付宝-->>商户: 1.1.2: 返回订阅id以及升级的支付链接

    商户->>商户: 1.2: 消费支付链接，如果是网页版，展示支付二维码
    商户-->>用户: 1.3: 二维码展示

    商户->>支付宝: 1.4: 消费支付链接，如果是app端，则唤起支付宝，与二维码选其一对客

    支付宝-->>商户: 1.5: 支付完成后发送订阅更新结果消息（alipay.trade.subscription.changed）

```

#### 发起订阅商品席位数量增加
商家可通过订阅修改接口 [alipay.trade.subscription.modify（订阅修改接口）](https://opendocs.alipay.com/solution/6cd02c10_alipay.trade.subscription.modify.md)实现席位增加的申请请求，引导用户确认支付后生效。

注意：

+ 席位增加需要用户确认并完成支付后才会增加席位数量，该接口会返回支付宝的支付链接供用户确认支付。
+ modify_type设置为INCREASE_QUANTITY代表本次操作为团体席位数量增加。
+ 通过preserve_billing_cycle参数控制是否保持计费周期不变。preserve_billing_cycle的传参会影响席位增加后的订阅周期的时间变化和当前用户针对席位增加操作需要支付的金额。
    - 订阅周期的时间：例如用户已生效周期为20260501<sub>20260531，如果用户在20260515操作席位数量增加，preserve_billing_cycle=true代表席位增加后，生效时间依旧是20260501</sub>20260531。
    - 支付金额：preserve_billing_cycle=true会按照当前周期剩余时间的比例（单位天）按比例支付增加的数量对应的差价。
+ item_id代表已生效的订阅项id，通过订阅查询接口alipay.trade.subscription.query或通知接口alipay.trade.subscription.changed中返回的item_id。注意，每次团体席位的扩容成功或者缩容成功，item_id都会发生变化，调用方需要拿最新生效的item_id作为入参进行席位的数量调整请求的入参。

订阅席位增加参数说明

| 参数名 | 必选 | 类型 | 长度/范围 | 示例值 | 描述 |
| :--- | --- | --- | --- | --- | --- |
| subscription_id | 必选 | string | [1,64] | 20260320123156789 | 订阅 ID |
| modify_type | 必选 | string | [1,64] | INCREASE_QUANTITY | 更新类型，枚举值：INCREASE_QUANTITY-坐席扩容 |
| preserve_billing_cycle | 必选 | boolean | - | true | 是否保持计费周期不变，订阅扩容场景下仅支持true |
| items | 必选 | array | [0,100] | - | 订阅项目信息 |
| ┗ item_id | 必选 | string | [1,64] | 2026032012314 | 升级的源订阅项id，用户支付成功后，通过alipay.trade.subscription.query或通知接口alipay.trade.subscription.changed中返回的item_id。 |
| ┗ sourceQuantity | 必选 | string | [1,8] | 80 | 订阅的原始坐席数量 |
| ┗ targetQuantity | 必选 | string | [1,8] | 100 | 订阅的目标坐席数量 |


席位增加请求示例

```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "subscription_id":"20260320123156789",
 "modify_type":"INCREASE_QUANTITY",
 "preserve_billing_cycle":true,
 "items":[
  {
   "item_id":"2026032012314",
   "sourceQuantity":"10",
   "targetQuantity":"20"
  }
 ]
}'
```

#### 获取订阅席位增加成功消息通知
商家通过订阅 [alipay.trade.subscription.changed（订阅产品商户消息通知接口）](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)来获取订阅商品的购买结果。

注意：

+ 该接口为支付宝主动向商户发送的消息通知接口，商户需要配置应用网关地址以及订阅消息服务，详情查看[接入准备](https://opendocs.alipay.com/solution/repo-046zj4.md)
+ 商户收到消息后需要返回success表示处理成功，否则返回fail，支付宝会进行重试。
+ 投递重试策略：25小时内完成8次通知，间隔频率为：2m、10m、10m、1h、2h、6h、15h。
+ 商户获取消息通知后，需要使用支付宝公钥进行验签。
+ 用户购买成功后，发送的订阅产品商户消息通知中的 订阅变更类型（change_type）为 订阅已生效（item_update）。
+ 生效周期字段：subscription中的current_period_start和current_period_end代表本次订阅支付对应的生效周期的起止时间。
+ 席位数量字段：在subscription中的items中的quantity代表扩容后的席位数量。

| 参数名 | 类型 | 必选 | 最大长度 | 示例值 | 描述 |
| --- | --- | --- | --- | --- | --- |
| change_type | string | 必选 | 32 | item_update | 订阅变更类型，枚举值：active-团体席位订阅已生效，用户完成首次支付签约；period_extend-订阅续费成功，周期性自动扣款成功；item_update-订阅项目席位数量扩容成功；item_downgrade-订阅项目席位数量缩容成功；cancel-订阅已取消，用户取消订阅或到期未续费；cancel_at_period_end-订阅将在周期结束取消 |
| change_date | string | 可选 | 32 | 2026-03-22 21:00:00 | 订阅变更时间 |
| trade_no | string | 可选 | 64 | 2026022276001434360514767918 | 支付宝交易号 |
| pay_amount | string | 可选 | 16 | 1001 | 当前订阅的支付金额，单位分 |
| subscription | string | 可选 | 20000 | 参考：alipay.trade.subscription.query接口返回的字段 | 订阅信息大对象 |


通知示例

```json
curl -X POST 'NOTIFY_URL' \
--header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'charset=UTF-8' \
--data-urlencode 'biz_content={
 "change_type":"item_update",
 "change_date":"2026-03-22 21:00:00",
 "trade_no":"2026022276001434360514767918",
 "pay_amount":"1001",
 "subscription":"订阅信息大对象，参考alipay.trade.subscription.query"
}' \
--data-urlencode 'utc_timestamp=${now}' \
--data-urlencode 'sign=${sign}' \
--data-urlencode 'app_id=${appid}' \
--data-urlencode 'version=1.1' \
--data-urlencode 'sign_type=RSA2' \
--data-urlencode 'notify_id=${notify_id}' \
--data-urlencode 'msg_method=alipay.trade.subscription.changed'
```

## 订阅席位数量减少
针对已生效的团体订阅可以指定需要减少的席位数量，支付宝侧会返回席位数量缩减后的签约链接，让用户重新确认并签约后续的扣款协议。

注意：

+ 针对已按照缩容前的席位数量发生了扣款的订阅周期依旧保持缩容前的席位数量，在周期结束后，才会按照缩减后的席位数量进行扣款收费。

![](https://mdn.alipayobjects.com/afts/img/A*WYilRa3BaD0AAAAASyAAAAgAeq8wAA/original?bz=openpt_doc&t=mQJcLYbUyZJ_V_VNRqYnNKXNd6qbB3bT5J2KWYEXjR4DAAAAZAAAMK8AAAAA)

商家可按如下指引调用接口，进行订阅席位数量减少并感知降级结果：

```mermaid
sequenceDiagram
    participant 用户
    participant 商户
    participant 支付宝

    用户->>商户: 1: 发起降级

    商户->>支付宝: 1.1: 订阅修改（alipay.trade.subscription.modify）
    支付宝-->>商户: 1.2: 返回订阅id以及降级的链接

    商户->>商户: 1.3: 消费降级链接，如果是网页版，展示支付二维码
    商户-->>用户: 1.4: 二维码展示

    商户->>支付宝: 1.5: 消费降级链接，如果是app端，则唤起支付宝，与二维码选其一对客

    支付宝-->>商户: 1.6: 降级完成后发送订阅更新结果消息（alipay.trade.subscription.changed）
```

#### 发起订阅席位数量减少
商家可通过订阅修改接口 [alipay.trade.subscription.modify（订阅修改接口）](https://opendocs.alipay.com/solution/6cd02c10_alipay.trade.subscription.modify.md)实现席位缩减的申请请求，引导用户在支付宝端内确认并成功签署协议后才会生效。

注意：

+ 针对已按照缩容前的席位数量发生了扣款的订阅周期依旧保持缩容前的席位数量，在周期结束后，才会按照缩减后的席位数量进行扣款收费。
+ 席位减少需要用户确认并完成支付，因此该接口会返回支付宝的协议确认链接供用户确认。
+ modify_type设置为DECREASE_QUANTITY代表席位数量减少操作。
+ item_id代表已生效的订阅项id，通过订阅查询接口alipay.trade.subscription.query或通知接口alipay.trade.subscription.changed中返回的item_id。注意，每次团体席位的扩容成功或者缩容成功，item_id都会发生变化，调用方需要拿最新生效的item_id作为入参进行席位的数量调整请求的入参。

订阅席位减少参数说明

| 参数名 | 必选 | 类型 | 长度/范围 | 示例值 | 描述 |
| --- | --- | --- | --- | --- | --- |
| subscription_id | 必选 | string | [1,64] | 20260320123156789 | 订阅 ID |
| modify_type | 必选 | string | [1,64] | DECREASE_QUANTITY | 更新类型，枚举值：DECREASE_QUANTITY-坐席缩容减少 |
| items | 必选 | array | [0,100] | - | 订阅项目信息 |
| ┗ item_id | 必选 | string | [1,64] | 2026032012314 | 升级的源订阅项id，用户支付成功后，通过alipay.trade.subscription.query或通知接口alipay.trade.subscription.changed中返回的item_id |
| ┗ sourceQuantity | 必选 | string | [1,8] | 100 | 订阅的原始坐席数量 |
| ┗ targetQuantity | 必选 | string | [1,8] | 80 | 订阅的目标坐席数量 |


订阅升级请求示例

```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "subscription_id":"20260320123156789",
 "modify_type":"DECREASE_QUANTITY",
 "items":[
  {
   "item_id":"2026032012314",
   "sourceQuantity":"100",
   "targetQuantity":"80"
  }
 ]
}'
```

#### 获取订阅席位减少成功消息通知
商家通过订阅 [alipay.trade.subscription.changed（订阅产品商户消息通知接口）](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)来获取订阅席位减少成功的结果。

注意：

+ 该接口为支付宝主动向商户发送的消息通知接口，商户需要配置应用网关地址以及订阅消息服务，详情查看[接入准备](https://opendocs.alipay.com/solution/repo-046zj4.md)
+ 商户收到消息后需要返回success表示处理成功，否则返回fail，支付宝会进行重试。
+ 投递重试策略：25小时内完成8次通知，间隔频率为：2m、10m、10m、1h、2h、6h、15h。
+ 商户获取消息通知后，需要使用支付宝公钥进行验签。
+ 用户购买成功后，发送的订阅产品商户消息通知中的 订阅变更类型（change_type）为 订阅已生效（item_downgrade）。
+ 席位数量字段：在subscription中的items中的quantity代表扩容后的席位数量。

| 参数名 | 类型 | 必选 | 最大长度 | 示例值 | 描述 |
| --- | --- | --- | --- | --- | --- |
| change_type | string | 必选 | 32 | item_downgrade | 订阅变更类型，枚举值：active-团体席位订阅已生效，用户完成首次支付签约；period_extend-订阅续费成功，周期性自动扣款成功；item_update-订阅项目席位数量扩容成功；item_downgrade-订阅项目席位数量缩容成功；cancel-订阅已取消，用户取消订阅或到期未续费；cancel_at_period_end-订阅将在周期结束取消 |
| change_date | string | 可选 | 32 | 2026-03-22 21:00:00 | 订阅变更时间 |
| trade_no | string | 可选 | 64 | 2026022276001434360514767918 | 支付宝交易号 |
| subscription | string | 可选 | 20000 | 参考：alipay.trade.subscription.query接口返回的字段 | 订阅信息大对象 |


通知示例

```json
curl -X POST 'NOTIFY_URL' \
--header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'charset=UTF-8' \
--data-urlencode 'biz_content={
 "change_type":"item_update",
 "change_date":"2026-03-22 21:00:00",
 "trade_no":"2026022276001434360514767918",
 "subscription":"订阅信息大对象，参考alipay.trade.subscription.query"
}' \
--data-urlencode 'utc_timestamp=${now}' \
--data-urlencode 'sign=${sign}' \
--data-urlencode 'app_id=${appid}' \
--data-urlencode 'version=1.1' \
--data-urlencode 'sign_type=RSA2' \
--data-urlencode 'notify_id=${notify_id}' \
--data-urlencode 'msg_method=alipay.trade.subscription.changed'
```

## 订阅取消
针对团体席位的订阅，可以通过两种形式进行取消：

+ 周期结束后取消：设置 `cancel_at_period_end=true`
+ 立即取消：设置 `cancel_at_period_end=false`

立即取消会触发退款，退款金额可自定义退款金额 或 系统自动计算残值，若商户自定义金额为0，即为立即取消但不退款

取消结果将通过订阅变更通知接口推送给商户

#### 发起订阅取消
商家可通过订阅修改接口 [alipay.trade.subscription.modify（订阅修改接口）](https://opendocs.alipay.com/solution/6cd02c10_alipay.trade.subscription.modify.md)实现订阅取消和取消后恢复功能，并接收相应的通知

重要参数说明

| 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
| :--- | --- | --- | --- | --- | --- | --- |
| subscription_id | 订阅id | String | 是 | [1,64] | 20260320123156789 | 需要取消的订阅id |
| modify_type | 更新类型 | String | 是 | [1,64] | CANCEL | 固定设置为 `CANCEL`，表示订阅取消操作 |
| cancel_at_period_end | 是否在当前周期结束时取消订阅 | Boolean | 是 | - | true | true：表示在当前计费周期结束后取消订阅； false：表示立即取消 |
| refund_amount | 自定义退款金额 | Number | 否 | [0,1000000000] | 100 | 不传：系统按照时间规则计算残值作为退款金额；自定义传入：按商家指定的金额退款，0表示直接取消不退款 |


```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "subscription_id":"20260320123156789",
 "modify_type":"CANCEL",
 "cancel_at_period_end":true
}'
```

#### 订阅取消结果通知
支付宝通过订阅变更通知接口 [alipay.trade.subscription.changed（订阅产品商户消息通知接口）](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)向商户发送订阅取消结果通知

注意：

+ 该接口为支付宝主动向商户发送的消息通知接口，商户需要配置应用网关地址以及订阅消息服务，详情查看[接入准备](https://opendocs.alipay.com/solution/repo-046zj4.md)
+ 商户收到消息后需要返回success表示处理成功，否则返回fail，支付宝会进行重试。
+ 投递重试策略：25小时内完成8次通知，间隔频率为：2m、10m、10m、1h、2h、6h、15h。
+ 商户获取消息通知后，需要使用支付宝公钥进行验签。
+ 取消成功后，立即会通知change_type=cancel_at_period_end的消息；在用户已生效的订阅周期结束后会再次通知change_type=cancel的消息。
+ 周期结束取消的通知会设置subscription中的cancel_at_period_end=true，代表周期结束后取消。
+ 商户收到通知后需返回success，否则支付宝会重试通知。

取消通知参数

| 参数名 | 类型 | 必选 | 最大长度 | 示例值 | 描述 |
| --- | --- | --- | --- | --- | --- |
| change_type | string | 必选 | 32 | cancel_at_period_end或cancel | 订阅变更类型，枚举值：active-团体席位订阅已生效，用户完成首次支付签约；period_extend-订阅续费成功，周期性自动扣款成功；item_update-订阅项目席位数量扩容成功；item_downgrade-订阅项目席位数量缩容成功；cancel_at_period_end-订阅会在周期结束后取消；cancel-订阅已取消，用户取消订阅或到期未续费 |
| change_date | string | 可选 | 32 | 2026-03-22 21:00:00 | 订阅变更时间 |
| trade_no | string | 可选 | 64 | 2026022276001434360514767918 | 支付宝交易号 |
| subscription | string | 可选 | 20000 | 参考：alipay.trade.subscription.query接口返回的字段 | 订阅信息大对象 |


通知示例

```json
curl -X POST 'NOTIFY_URL' \
--header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'charset=UTF-8' \
--data-urlencode 'biz_content={
 "change_type":"item_update",
 "change_date":"2026-03-22 21:00:00",
 "trade_no":"2026022276001434360514767918",
 "subscription":"订阅信息大对象，参考alipay.trade.subscription.query"
}' \
--data-urlencode 'utc_timestamp=${now}' \
--data-urlencode 'sign=${sign}' \
--data-urlencode 'app_id=${appid}' \
--data-urlencode 'version=1.1' \
--data-urlencode 'sign_type=RSA2' \
--data-urlencode 'notify_id=${notify_id}' \
--data-urlencode 'msg_method=alipay.trade.subscription.changed'
```

#### 取消后恢复
如果用户在周期结束前想恢复订阅，可以使用取消后恢复功能

恢复参数说明

| 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
| --- | :---: | :---: | :---: | :---: | :---: | --- |
| subscription_id | 订阅id | String | 是 | [1,64] | 20260320123156789 | 需要恢复的订阅id |
| modify_type | 更新类型 | String | 是 | [1,64] | REVERT_CANCEL | 固定设置为 `REVERT_CANCEL`，表示取消后恢复操作 |
| description | 恢复描述 | String | 否 | [0,256] | 恢复订阅 | 恢复描述，记录恢复原因或备注 |


恢复请求示例

```json
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
 "subscription_id":"20260320123156789",
 "modify_type":"REVERT_CANCEL",
 "description":"用户申请恢复订阅"
}'
```

恢复响应参数

| 参数 | 名称 | 参数类型 | 描述 |
| --- | :---: | :---: | --- |
| subscription_id | 订阅id | String | 订阅id |
| alipay_jump_schema | 支付宝长链跳端schema | String | 长链，适用于跳转拉起支付宝客户端，用户需通过此链接确认恢复 |
| alipay_schema | 支付宝跳转的schema | String | 短链，适用于生成二维码，用户扫码确认恢复 |


恢复结果通知

恢复成功后，支付宝会发送订阅变更通知：

+ `subscription_status` 会变为 `ACTIVE`
+ `cancel_at_period_end` 会变为 `false`
+ `canceled_date` 会被清除