update

2026-04-03 07:54

POST /v1/subscriptions/update

调用此接口来更新已经创建的订阅信息，例如升级订阅，降级订阅，更新订阅描述信息，变更订阅周期类型，以及调整订阅周期等。

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息，有关报文头的结构信息，请参阅：

注意：将每个字段（除数组外）的数据类型设置为字符串。这意味字段值必须使用双引号（" "）括起来。例如：
如果字段的数据类型为整数属性，且其值为 20，设置为 "20"。
如果字段的数据类型为布尔属性，且其值为 true，设置为 "true"。

入参

subscriptionUpdateRequestId String REQUIRED

商户为识别订阅更新请求而分配的专属 ID。

更多信息：

此为幂等字段。
最大长度：64 字符

subscriptionId String REQUIRED

Antom 为识别订阅而分配的订阅编号。

更多信息：

最大长度：64 字符

subscriptionDescription String

订阅的描述，用于显示用户消费记录和其他操作。

注意：如果您需要更新订阅描述信息，请指定此参数。

更多信息：

最大长度：256 字符

periodRule PeriodRule

订阅期规则，用于定义订阅的计费周期。

注意：如果您需要变更订阅周期类型，请指定此参数。

Show child parameters

paymentAmount Amount

每个订阅周期向用户收取的支付金额。

注意：如果您需要升级或者降级订阅，请指定此参数。

Show child parameters

subscriptionEndTime Datetime

订阅结束的日期和时间。

更多信息：

值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

orderInfo OrderInfo

订阅的订单信息。此字段用于不同目的：

在支付过程中，此字段主要用于 Antom 的风险控制或反洗钱。
支付完成后，此字段用于记录和报告，如采购追踪和监管报告。

注意：如果您需要升级或者降级订阅，请指定此参数。

Show child parameters

prorationSettings ProrationSettings

差价处理的规则与方法。

注意：当有差价处理需求时传入该参数。

Show child parameters

nextSubscriptionDate Datetime

由您指定的下次扣款时间。

注意：由于订阅产品会在履约时间 24 小时前开始尝试扣款，所以您指定的扣款时间至少要在当前时间的 24 小时之后。如您指定的下次扣款时间小于当前时间的 24 小时，订阅升级将失败并返回 PROCCESS_FAIL 错误码。

更多信息：

值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

出参

result Result REQUIRED

指示此接口是否成功调用。

Show child parameters

API Explorer

示例代码沙箱运行

请求

URL

Method

POST

请求体

响应

响应体

结果/错误码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功。	接口调用成功。
UPDATE_FORBIDDEN_DURING_PAYMENT	F	支付处理期间禁止更新操作。	请稍后重试。若错误依然存在，请联系 Antom 技术支持。
CURRENCY_NOT_SUPPORT	F	暂不支持该币种。	请联系 Antom 技术支持以获取详细原因。
PAYMENT_COUNT_EXCEED_LIMIT	F	支付笔数已超过该支付方式规定的上限。	请联系 Antom 技术支持以以了解具体限制。
REPEAT_REQ_INCONSISTENT	F	金额或币种与先前请求不一致。	请确保请求中的所有字段保持一致，或使用新的 paymentRequestId 重新发起支付。
PAYMENT_IN_PROCESS	F	支付正在处理中。	请联系 Antom 技术支持以获取详细原因。
USER_AMOUNT_EXCEED_LIMIT	F	支付金额超过用户限额，无法完成支付。	请使用小于或等于账户余额的金额创建新请求，或联系 Antom 技术支持。
RISK_REJECT	F	由于风控原因，当前交易无法完成。若用户已完成支付，该交易将进行退款。	如果用户两周内未收到退款，请联系 Antom 技术支持。
USER_NOT_EXIST	F	用户不存在。	请联系 Antom 技术支持以获取详细原因。
ORDER_NOT_EXIST	F	订单不存在。	请检查传入的 paymentId 是否正确。
ACCESS_DENIED	F	访问被拒绝。	请咨询 Antom 技术支持以获取详细原因。
UNKNOWN_CLIENT	F	客户端未知。	请咨询 Antom 技术支持以获取详细原因。
UNKNOWN_EXCEPTION	U	由于未知原因，接口调用失败。	再次调用接口解决问题。如果问题未解决，请联系 Antom 技术支持。
REQUEST_TRAFFIC_EXCEED_LIMIT	F	请求流量超过了限制。	再次调用接口解决问题。如果问题未解决，请联系 Antom 技术支持。
PROCESS_FAIL	F	发生了常见的业务失败。	获取 Antom 技术支持前请勿重试。
KEY_NOT_FOUND	F	未找到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom Dashboard 中上传私钥。
OAUTH_FAILED	F	OAuth 授权流程失败。	请咨询 Antom 技术支持以获取详细原因。
MERCHANT_NOT_REGISTERED	F	商户未注册。	请使用注册接口进行商户注册。如果调用注册接口失败，请联系 Antom 技术支持。
INVALID_SIGNATURE	F	签名验证失败。用于签署请求的私钥与 Antom Dashboard 的公钥不匹配。	检查用于签署请求的私钥是否与 Antom Dashboard 的公钥匹配。以下签名参考信息很有用：请求头中的签名字段如何生成签名
INVALID_API	F	调用的接口无效或未激活。	请咨询 Antom 技术支持以解决问题。
CLIENT_FORBIDDEN_ACCESS_API	F	客户端无权使用此接口。	请咨询 Antom 技术支持以获取详细原因。
SYSTEM_ERROR	F	发生系统错误。	详细原因请咨询 Antom 技术支持。
PARAM_ILLEGAL	F	缺少必需的参数，或者存在非法参数。例如，非数字输入，无效的日期，或者参数的长度和类型错误。	检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。