更新订阅

2026-04-15 03:20

订阅计划更新功能为买家提供灵活的订阅管理方式。您可根据买家的实际需求，随时进行套餐升级、降级、提前结束当期订阅或推迟当期订阅结束时间，同时支持更新订阅描述等信息。
该功能不受固定结算周期限制，所有更改均可即时生效，买家可立即体验新套餐带来的功能与权益。通过灵活调整订阅内容，满足不同阶段的使用需求，持续获得最佳用户体验，确保功能与服务始终与买家的实际需求保持一致。

调用 update 接口来完成订阅更新，您可以从以下几个维度来更新订阅。

注意：当周期扣款正在处理中时，如果同时调用 update 接口更新订阅，则返回 UPDATE_FORBIDDEN_DURING_PAYMENT 错误。收到该错误码后，建议稍后再重新调用接口。

订阅描述信息更新

注意：此操作仅更新订阅描述信息，不改变订阅金额、币种和订阅周期。

如果需要更新订阅描述信息，请传入以下参数：

字段	是否必传	字段描述
subscriptionId	是	原本的订阅单号。
subscriptionUpdateRequestId	是	商户为识别订阅更新请求而分配的专属 ID。
subscriptionDescription	否	需要变更的订阅描述。

请求示例参考：

copy
{
    "subscriptionUpdateRequestId": "subscription_update_20260313",

    "subscriptionDescription": "Description update",

    "subscriptionId": "202603131900000000000000E0000115288"

    }

订阅升级

如果需要升级订阅，请传入以下参数：

字段	是否必传	字段描述
subscriptionId	是	原本的订阅单号。
subscriptionUpdateRequestId	是	商户为识别订阅更新请求而分配的专属 ID。
paymentAmount	否	每期支付金额，用于下一期代扣请求。
prorationSettings.customAmount	否	差价金额，用于补齐差价金额。
prorationSettings.prorationMode	否	价差模式，在订阅升级场景下，请指定 prorationMode 的值为 `IMMEDIATE_PAY_CUSTOM_AMOUNT`。
orderInfo	否	订阅订单相关信息，用于 Antom 内部风控，或是账单展示，不用于实际支付。

以下示例展示买家从标准月会员（$30）升级至高级月会员（$50）的关键时间节点与相关参数来源。

注意：由于支付方式不同，创建订阅时所调用的接口也有所区别，具体说明如下：
APM 集成：调用 create 接口创建订阅；
卡、Apple Pay 及 Google Pay 集成：调用 pay（单笔支付） 接口创建订阅；
Payment Element 集成：调用 createPaymentSession（单笔支付） 接口创建订阅。

升级前订阅信息	示例	参数来源
升级前	标准月会员（$30）	-
计费周期	每月	创建订阅时传入的周期信息（`"periodRule":{"periodCount":1,"periodType":"MONTH"}`）。
订阅开始时间	2026-03-13T18:15:29+08:00	创建订阅时传入的 subscriptionStartTime 参数。
第一期订阅发起扣款时间和金额	2026-03-13T18:15:29+08:00 扣当期订阅费 $30	通过第一期订阅扣款异步通知返回。
第二期订阅开始时间	2026-04-13T18:15:29+08:00	通过第二期订阅扣款异步通知返回。
第二期订阅发起扣款时间和金额	2026-04-12T18:20:29+08:00 扣当期订阅费 $30	通过第二期订阅扣款异步通知返回。

升级后订阅信息	示例	参数来源
升级后	高级月会员（$50）	-
计费周期	每月	创建订阅时传入的周期信息（`"periodRule":{"periodCount":1,"periodType":"MONTH"}`）。
升级计划时间	2026.04.20T19:00:00+08:00	调用 update 接口成功的时间。
发起扣款时间和金额	2026.04.20T19:02:00+08:00 扣订阅差价 $20	通过第二期订阅扣款异步通知返回。
第三期订阅开始时间	2026-05-13T18:15:29+08:00	通过第三期订阅扣款异步通知返回。
第三期订阅发起扣款时间和金额	2026.05.12T18:20:29+08:00 扣当期订阅费 $50	通过第三期订阅扣款异步通知返回。

请求示例参考：

copy
{
    "subscriptionUpdateRequestId": "subscription_update_20250925_002",
    "paymentAmount": {
        "currency": "USD",
        "value": "5000"
    },
    "periodRule": {
        "periodType": "MONTH",
        "periodCount": 1
    },
    "subscriptionDescription": "Premium monthly Membership",
    "subscriptionId": "202603131900000000000000E0000115608",
    "orderInfo": {
        "orderAmount": {
            "currency": "USD",
            "value": "5000"
        }
    },
    "prorationSettings": {
        "prorationMode": "IMMEDIATE_PAY_CUSTOM_AMOUNT",
        "customAmount": {
            "currency": "USD",
            "value": "2000"
        }
    }
}

订阅降级

如果需要进行订阅降级，请传入以下参数：

字段	是否必传	字段描述
subscriptionId	是	原本的订阅单号。
subscriptionUpdateRequestId	是	商户为识别订阅更新请求而分配的专属 ID。
paymentAmount	否	每期支付金额，用于下一期代扣请求。
prorationSettings.customAmount	否	差价金额，用于补齐差价金额。
prorationSettings.prorationMode	否	价差模式，在订阅升级场景下，请指定 prorationMode 的值为 `IMMEDIATE_REFUND_CUSTOM_AMOUNT`。
orderInfo	否	订阅订单相关信息，用于 Antom 内部风控，或是账单展示，不用于实际支付。

以下示例展示买家从高级月会员（$50）降级至普通月会员（$30）的关键时间节点与相关参数来源。

注意：由于支付方式不同，创建订阅时所调用的接口也有所区别，具体说明如下：
APM 集成：调用 create 接口创建订阅；
卡、Apple Pay 及 Google Pay 集成：调用 pay（单笔支付） 接口创建订阅；
Payment Element 集成：调用 createPaymentSession（单笔支付） 接口创建订阅。

降级前订阅信息	示例	参数来源
降级前	高级月会员（$50）	-
计费周期	每月	创建订阅时传入的周期信息（`"periodRule":{"periodCount":1,"periodType":"MONTH"}`）。
订阅开始时间	2025-09-25T18:15:29+08:00	创建订阅时传入 subscriptionStartTime 参数。
第一期订阅发起扣款时间和金额	2025-09-25T18:15:29+08:00 扣当期订阅费 $50	通过第一期订阅扣款异步通知返回。
第二期订阅开始时间	2025-10-25T18:15:29+08:00	通过第二期订阅扣款异步通知返回。
第二期订阅发起扣款时间和金额	2025-10-24T18:20:29+08:00 扣当期订阅费 $50	通过第二期订阅扣款异步通知返回。

降级后订阅信息	示例	参数来源
降级后	普通月会员（$50）	-
计费周期	每月	创建订阅时传入的周期信息（`"periodRule":{"periodCount":1,"periodType":"MONTH"}`）。
降级计划时间	2025.10.30T19:00:00+08:00	调用 update 接口成功的时间。
退款时间和退款金额	2025.10.30T19:02:00+08:00 退订阅差价 $20	通过第二期订阅扣款异步通知返回。
第三期订阅开始时间	2025-11-25T18:15:29+08:00	通过第三期订阅扣款异步通知返回。
第三期订阅发起扣款时间和金额	22025.11.24T18:20:29+08:00 扣当期订阅费 $30	通过第三期订阅扣款异步通知返回。

请求示例参考：

copy
{
    "subscriptionUpdateRequestId": "subscription_update_20260313_002",
    "paymentAmount": {
        "currency": "USD",
        "value": "3000"
    },
    "periodRule": {
        "periodType": "MONTH",
        "periodCount": 1
    },
    "subscriptionDescription": "Normal monthly Membership",
    "subscriptionId": "202603131900000000000004E0000002358",
    "orderInfo": {
        "orderAmount": {
            "currency": "USD",
            "value": "3000"
        }
    },
"prorationSettings": {
        "prorationMode": "IMMEDIATE_REFUND_CUSTOM_AMOUNT",
        "customAmount": {
            "currency": "USD",
            "value": "2000"
        }
    }
}

周期类型变更

如果您需要变更订阅周期类型，请传入以下参数：

字段	是否必传	字段描述
subscriptionId	是	原本的订阅单号。
subscriptionUpdateRequestId	是	商户为识别订阅更新请求而分配的专属 ID。
periodRule.periodType	否	周期类型，目前支持`YEAR`、`MONTH`、`WEEK`、`DAY`四种周期类型。
periodRule.periodCount	否	一个订阅周期内周期类型的数量，通过指定该参数与 periodType 参数来定义一个完整的订阅周期。

以下示例展示买家将周会员变更为月会员的关键时间节点与相关参数来源。

注意：由于支付方式不同，创建订阅时所调用的接口也有所区别，具体说明如下：
APM 集成：调用 create 接口创建订阅；
卡、Apple Pay 及 Google Pay 集成：调用 pay（单笔支付） 接口创建订阅；
Payment Element 集成：调用 createPaymentSession（单笔支付） 接口创建订阅。

变更前订阅信息	示例	参数来源
变更前	周会员	-
计费周期	每周	创建订阅时传入的周期信息（`"periodRule":{"periodCount":1,"periodType":"WEEK"}`）。
订阅开始时间	2026-03-16T08:18:54+08:00	创建订阅时传入的 subscriptionStartTime 参数。
第一期订阅发起扣款时间	2026-03-16T08:18:54+08:00	通过第一期订阅扣款异步通知返回。
第二期订阅开始时间	2026-03-23T08:18:54+08:00	通过第二期订阅扣款异步通知返回。

变更后订阅信息	示例	参数来源
变更后	月会员	-
计费周期	每月	通过 update 接口传入的周期信息：`"periodRule":{"periodCount":1,"periodType":"MONTH"}`。
变更计划时间	2026-03-24T12:18:54+08:00	调用 update 接口成功的时间。
第三期订阅开始时间	2026-03-30T08:18:54+08:00	通过第三期订阅扣款异步通知返回。
第四期订阅开始时间	2026-04-30T08:18:54+08:00	通过第四期订阅扣款异步通知返回。

请求示例参考：

copy
{
    "subscriptionUpdateRequestId": "subscription_update_20250316_001",

    "periodRule": {
        "periodType": "MONTH",
        "periodCount": 1
    },
    "subscriptionDescription": "Premium monthly Membership (change period)",
    "subscriptionId": "202603161900000000000000E0000117794"


}

订阅周期调整

您可以对订阅周期进行调整，例如提前结束或推迟结束当期订阅，您需要传入以下参数：

字段	是否必传	字段描述
subscriptionId	是	原本的订阅单号。
subscriptionUpdateRequestId	是	商户为识别订阅更新请求而分配的专属 ID。
nextSubscriptionDate	否	下期订阅开始时间，需要根据对应的提前/延后时间，反推出订阅开始时间的值。注意：nextSubscriptionDate 必须早于当前时间 + periodCount * periodType

以下示例展示买家提前结束当期订阅的关键时间节点与相关参数来源。

注意：由于支付方式不同，创建订阅时所调用的接口也有所区别，具体说明如下：
APM 集成：调用 create 接口创建订阅；
卡、Apple Pay 及 Google Pay 集成：调用 pay（单笔支付） 接口创建订阅；
Payment Element 集成：调用 createPaymentSession（单笔支付） 接口创建订阅。

调整前订阅信息	示例	参数来源
调整前	月会员	-
计费周期	每月	创建订阅时传入的周期信息（`"periodRule":{"periodCount":1,"periodType":"MONTH"}`）。
订阅开始时间	2026-03-13T16:00:29+08:00	创建订阅时传入 subscriptionStartTime 参数。
第一期订阅发起扣款时间	2025-03-13T16:00:29+08:00	通过第一期订阅扣款异步通知返回。
第二期订阅开始时间	2025-04-13T16:00:29+08:00	通过第二期订阅扣款异步通知返回。

调整后订阅信息	示例	参数来源
调整后	月会员	-
计费周期	每月	创建订阅时传入的周期信息（`"periodRule":{"periodCount":1,"periodType":"MONTH"}`）。
调整计划时间	2026-03-20T19:00:00+08:00	通过 update 接口指定 nextSubscriptionDate 参数的值为 `2026-04-10T00:00:02+08:00`。
第二期订阅开始时间	2026-04-10T00:00:02+08:00	通过第二期订阅扣款异步通知返回。
第三期订阅开始时间	2026-05-10T00:00:02+08:00	通过第三期订阅扣款异步通知返回。

请求示例参考：

copy
{
    "subscriptionUpdateRequestId": "subscription_update_20260313_007",


    "subscriptionDescription": "Advance the current subscription end date",
    "subscriptionId": "202603131900000000000000E0000117414",
  "nextSubscriptionDate": "2026-04-10T00:00:02+08:00"

}