接口说明
接口名称:alipay.trade.subscription.modify
支持第三方代理调用:本接口支持第三方开发者代用户发起调用。
适用场景
提供商户修改订阅信息的能力。
公共请求参数
参数 类型 是否必选 最大长度 描述 示例值 app_idString 必选 32 支付宝分配给开发者的应用 ID 2014072300007148methodString 必选 128 接口名称 alipay.trade.subscription.modifyformatString 可选 40 仅支持JSON JSONcharsetString 必选 10 请求使用的编码格式,如utf-8,gbk,gb2312等 utf-8sign_typeString 必选 10 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2signString 必选 344 商户请求参数的签名串,详见签名 详见示例timestampString 必选 19 发送请求的时间,格式”yyyy-MM-dd HH:mm
” 2014-07-24 03:07:50versionString 必选 3 调用的接口版本,固定为:1.0 1.0app_auth_tokenString 可选 40 详见应用授权概述 - biz_contentString 必选 - 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 -
业务请求参数
参数 类型 是否必选 最大长度 描述 注意事项/枚举值 示例值 extend_paramsString 可选 512 扩展参数,用于订阅特殊能力的传参,使用方式详见具体场景接入指南 - {"key":"value"}refund_amountNumber 可选 1000000000 取消并退款场景下使用: 不传: 系统按照时间规则计算残值作为退款金额; 自定义传入: 按商家指定的金额退款,0表示直接取消不退款; - 100modify_typeString 可选 64 UPGRADE:升级,DOWNGRADE:降级, 取消:CANCEL, 取消后恢复:REVERT_CANCEL,INCREASE_QUANTITY-席位商品数量扩容,DECREASE_QUANTITY-席位商品数量缩容,如若不传则视为UPGRADE,具体使用方式详见接入指南。 - UPGRADEpreserve_billing_cycleBoolean 可选 10 是否保持计费周期不变,当前仅用于升级场景 true:周期不变 false:重置周期,具体使用方式详见接入指南。 - truepay_amountNumber 可选 1000000000 支付金额,单位分; 仅用于商户自定义金额,若传了该值,用户实际支付金额会以该值为准,目前仅用于普通订阅升级场景,具体使用方式详见接入指南。 - 100itemsSubscriptionItem 可选 - 订阅项目信息 - - items.item_idString 可选 64 订阅生效后,查询接口(alipay.trade.subscription.query)或通知接口(alipay.trade.subscription.changed)返回的item_id,使用方式详见具体场景接入指南。 - 2026032012314items.price_idString 可选 64 价格创建接口(alipay.trade.price.create)返回的价格 ID,代表本次操作的目标价格信息,使用方式详见具体场景接入指南。 - 202603201234567889items.quantityString 可选 8 购买的商品数量,目前仅在席位商品的订阅创建(alipay.trade.subscription.create)场景按需传入该参数,使用方式详见具体场景接入指南。 - 10items.source_quantityString 可选 8 目前仅用于席位商品的订阅修改(alipay.trade.subscription.modify)场景下指定当前已生效的订阅项中商品的数量,使用方式详见具体场景接入指南。 - 10items.target_quantityString 可选 8 目前仅用于席位商品的订阅修改(alipay.trade.subscription.modify)场景下指定订阅项的目标商品数量,使用方式详见具体场景接入指南。 - 100items.coupon_idString 可选 40 营销创建接口(alipay.trade.promotion.coupon.create)返回的优惠id,使用方式详见具体场景接入指南 - 9WJ36SECcancel_at_period_endBoolean 可选 10 是否在周期结束时取消,仅用于取消/取消后恢复订阅,其他场景无需使用。 true:CANCEL场景下传true表示在当前计费周期结束后取消订阅; false:CANCEL场景传false表示立即取消并发起退款,REVERT_CANCEL场景下需传false;具体使用方式详见接入指南。 - truedescriptionString 可选 256 更新描述,若无特殊需求,无需使用该字段 - 升级订阅subscribe_titleString 可选 256 订单标题,若无特殊需求,无需使用该字段,默认使用商品名称 - 订阅月会员subscription_idString 必选 64 订阅id,订阅唯一标识 - 20260320123156789
常见请求示例
Java
package com.java.sdk.demo;
import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.domain.SubscriptionItem;
import com.alipay.api.response.AlipayTradeSubscriptionModifyResponse;
import com.alipay.api.domain.AlipayTradeSubscriptionModifyModel;
import com.alipay.api.request.AlipayTradeSubscriptionModifyRequest;
import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;
public class AlipayTradeSubscriptionModify {
public static void main ( String [] args ) throws AlipayApiException {
// 初始化SDK
AlipayClient alipayClient = new DefaultAlipayClient ( getAlipayConfig ());
// 构造请求参数以调用接口
AlipayTradeSubscriptionModifyRequest request = new AlipayTradeSubscriptionModifyRequest ();
AlipayTradeSubscriptionModifyModel model = new AlipayTradeSubscriptionModifyModel ();
// 设置扩展参数
model. setExtendParams ( "{ \" key \" : \" value \" }" );
// 设置自定义退款金额(单位:分)
model. setRefundAmount ( 100L );
// 设置更新类型
model. setModifyType ( "UPGRADE" );
// 设置是否保持计费周期不变
model. setPreserveBillingCycle ( true );
// 设置支付金额
model. setPayAmount ( 100L );
// 设置订阅项目信息
List< SubscriptionItem > items = new ArrayList< SubscriptionItem >();
SubscriptionItem items0 = new SubscriptionItem ();
items0. setQuantity ( "10" );
items0. setCouponId ( "9WJ36SEC" );
items0. setItemId ( "2026032012314" );
items0. setPriceId ( "202603201234567889" );
items0. setSourceQuantity ( "10" );
items0. setTargetQuantity ( "100" );
items. add (items0);
model. setItems (items);
// 设置是否在当前周期结束时取消订阅
model. setCancelAtPeriodEnd ( true );
// 设置更新描述
model. setDescription ( "升级订阅" );
// 设置订阅标题
model. setSubscribeTitle ( "订阅月会员" );
// 设置订阅id
model. setSubscriptionId ( "20260320123156789" );
request. setBizModel (model);
// 第三方代调用模式下请设置app_auth_token
// request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");
AlipayTradeSubscriptionModifyResponse response = alipayClient. execute (request);
System.out. println (response. getBody ());
if (response. isSuccess ()) {
System.out. println ( "调用成功" );
} else {
System.out. println ( "调用失败" );
// sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
// String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
// System.out.println(diagnosisUrl);
}
}
private static AlipayConfig getAlipayConfig () {
String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->" ;
String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->" ;
AlipayConfig alipayConfig = new AlipayConfig ();
alipayConfig. setServerUrl ( "https://openapi.alipay.com/gateway.do" );
alipayConfig. setAppId ( "<-- 请填写您的AppId,例如:2019091767145019 -->" );
alipayConfig. setPrivateKey (privateKey);
alipayConfig. setFormat ( "json" );
alipayConfig. setAlipayPublicKey (alipayPublicKey);
alipayConfig. setCharset ( "UTF-8" );
alipayConfig. setSignType ( "RSA2" );
return alipayConfig;
}
}
PHP
<? php
require_once '../aop/AopClient.php' ;
require_once '../aop/AopCertClient.php' ;
require_once '../aop/AopCertification.php' ;
require_once '../aop/AlipayConfig.php' ;
require_once '../aop/request/AlipayTradeSubscriptionModifyRequest.php' ;
// 初始化SDK
$alipayClient = new AopClient ( getAlipayConfig ());
// 构造请求参数以调用接口
$request = new AlipayTradeSubscriptionModifyRequest ();
$model = array ();
// 设置扩展参数
$model[ 'extend_params' ] = "{ \" key \" : \" value \" }" ;
// 设置自定义退款金额(单位:分)
$model[ 'refund_amount' ] = 100 ;
// 设置更新类型
$model[ 'modify_type' ] = "UPGRADE" ;
// 设置是否保持计费周期不变
$model[ 'preserve_billing_cycle' ] = true ;
// 设置支付金额
$model[ 'pay_amount' ] = 100 ;
// 设置订阅项目信息
$items = array ();
$items0 = array ();
$items0[ 'quantity' ] = "10" ;
$items0[ 'coupon_id' ] = "9WJ36SEC" ;
$items0[ 'item_id' ] = "2026032012314" ;
$items0[ 'price_id' ] = "202603201234567889" ;
$items0[ 'source_quantity' ] = "10" ;
$items0[ 'target_quantity' ] = "100" ;
$items[] = $items0;
$model[ 'items' ] = $items;
// 设置是否在当前周期结束时取消订阅
$model[ 'cancel_at_period_end' ] = true ;
// 设置更新描述
$model[ 'description' ] = "升级订阅" ;
// 设置订阅标题
$model[ 'subscribe_title' ] = "订阅月会员" ;
// 设置订阅id
$model[ 'subscription_id' ] = "20260320123156789" ;
$request -> setBizContent ( json_encode ($model, JSON_UNESCAPED_UNICODE ));
// 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌)
$responseResult = $alipayClient -> execute ($request, null , "<-- 请填写应用授权令牌 -->" , null );
$responseApiName = str_replace ( "." , "_" ,$request -> getApiMethodName ()) . "_response" ;
$response = $responseResult -> $responseApiName;
if ( ! empty ($response -> code) && $response -> code == 10000 ){
echo ( "调用成功" );
}
else {
echo ( "调用失败" );
}
function getAlipayConfig ()
{
$privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->' ;
$alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->' ;
$alipayConfig = new AlipayConfig ();
$alipayConfig -> setServerUrl ( 'https://openapi.alipay.com/gateway.do' );
$alipayConfig -> setAppId ( '<-- 请填写您的AppId,例如:2019091767145019 -->' );
$alipayConfig -> setPrivateKey ($privateKey);
$alipayConfig -> setFormat ( 'json' );
$alipayConfig -> setAlipayPublicKey ($alipayPublicKey);
$alipayConfig -> setCharset ( 'UTF-8' );
$alipayConfig -> setSignType ( 'RSA2' );
return $alipayConfig;
}
C#
using System ;
using System . Collections . Generic ;
using Aop . Api ;
using Aop . Api . Request ;
using Aop . Api . Response ;
using Aop . Api . Domain ;
using Aop . Api . Util ;
namespace SdkDemoTest
{
public class AlipayTradeSubscriptionModify
{
public static void Main ( string [] args )
{
// 初始化SDK
IAopClient alipayClient = new DefaultAopClient ( GetAlipayConfig ());
// 构造请求参数以调用接口
AlipayTradeSubscriptionModifyRequest request = new AlipayTradeSubscriptionModifyRequest ();
AlipayTradeSubscriptionModifyModel model = new AlipayTradeSubscriptionModifyModel ();
// 设置扩展参数
model.ExtendParams = "{ \" key \" : \" value \" }" ;
// 设置自定义退款金额(单位:分)
model.RefundAmount = 100 ;
// 设置更新类型
model.ModifyType = "UPGRADE" ;
// 设置是否保持计费周期不变
model.PreserveBillingCycle = true ;
// 设置支付金额
model.PayAmount = 100 ;
// 设置订阅项目信息
List < SubscriptionItem > items = new List < SubscriptionItem >();
SubscriptionItem items0 = new SubscriptionItem ();
items0.Quantity = "10" ;
items0.CouponId = "9WJ36SEC" ;
items0.ItemId = "2026032012314" ;
items0.PriceId = "202603201234567889" ;
items0.SourceQuantity = "10" ;
items0.TargetQuantity = "100" ;
items. Add (items0);
model.Items = items;
// 设置是否在当前周期结束时取消订阅
model.CancelAtPeriodEnd = true ;
// 设置更新描述
model.Description = "升级订阅" ;
// 设置订阅标题
model.SubscribeTitle = "订阅月会员" ;
// 设置订阅id
model.SubscriptionId = "20260320123156789" ;
request. SetBizModel (model);
// 第三方代调用模式下请设置app_auth_token
// request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");
AlipayTradeSubscriptionModifyResponse response = alipayClient. Execute (request);
if ( ! response.IsError)
{
Console. WriteLine ( "调用成功" );
}
else
{
Console. WriteLine ( "调用失败" );
}
}
private static AlipayConfig GetAlipayConfig ()
{
string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->" ;
string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->" ;
AlipayConfig alipayConfig = new AlipayConfig ();
alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do" ;
alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->" ;
alipayConfig.PrivateKey = privateKey;
alipayConfig.Format = "json" ;
alipayConfig.AlipayPublicKey = alipayPublicKey;
alipayConfig.Charset = "UTF-8" ;
alipayConfig.SignType = "RSA2" ;
return alipayConfig;
}
}
}
cURL
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×tamp=${now}' \
-F 'app_auth_token=${app_auth_token}' \
-F 'biz_content={
"extend_params":"{\"key\":\"value\"}",
"refund_amount":100,
"modify_type":"UPGRADE",
"preserve_billing_cycle":true,
"pay_amount":100,
"items":[
{
"quantity":"10",
"coupon_id":"9WJ36SEC",
"item_id":"2026032012314",
"price_id":"202603201234567889",
"source_quantity":"10",
"target_quantity":"100"
}
],
"cancel_at_period_end":true,
"description":"升级订阅",
"subscribe_title":"订阅月会员",
"subscription_id":"20260320123156789"
}'
公共响应参数
参数 类型 是否必选 描述 示例值 code String 必选 网关返回码,详见文档 40004 msg String 必选 网关返回码描述,详见文档 Business Failed sub_code String 可选 业务返回码,参见具体的 API 接口文档 - sub_msg String 可选 业务返回码描述,参见具体的 API 接口文档 - sign String 必选 签名,详见文档 DZXh8eeTuAHoYE3w1J…
业务响应参数
参数 类型 是否必选 最大长度 描述 注意事项/枚举值 示例值 promotion_infoString 可选 1000 订阅修改时若传入优惠,生成的优惠信息 - {"originAmount":"30.00","2026042802400000001":"{\"couponName\":\"新用户立减10元-前三次\",\"amountOff\":\"10.00\",\"couponId\":\"9WJ36SEC\"}","discountAmount":"10.00"}order_noString 可选 32 升级订阅时生成的支付请求单号 - 123456789alipay_jump_schemaString 可选 4096 长链,适用于跳转拉起支付宝端,升级/降级/取消后撤销场景会返回 - 升级:alipays://platformapi/startApp?appId=60000157&orderStr=XXXXXXXXXX;降级/取消后撤销:[https://render.alipay.com/XXXXXXXXXX](https://render.alipay.com/XXXXXXXXXX)pay_amountNumber 可选 1000000000 支付金额,单位分 - 100subscription_idString 可选 64 订阅id,订阅唯一标识 - 20260320123156789alipay_schemaString 可选 4096 短链,适用于生成二维码 升级/降级/取消后撤销场景会返回 - [https://basementurl.test.alipay.net/_1bQzQBRlIPjfo4eyx5SlMJ](https://basementurl.test.alipay.net/_1bQzQBRlIPjfo4eyx5SlMJ)refund_order_idString 可选 64 退款业务单号,取消并退款场景下生成 - 123456789refund_amountNumber 可选 1000000000 退款金额,单位分,取消并退款场景下生成 - 100
响应示例
正常示例
{
"alipay_trade_subscription_modify_response" :{
"code" : "10000" ,
"msg" : "Success" ,
"promotion_info" : "{ \\\" originAmount \\\" : \\\" 30.00 \\\" , \\\" 2026042802400000001 \\\" : \\\" { \\\\\\\" couponName \\\\\\\" : \\\\\\\" 新用户立减10元-前三次 \\\\\\\" , \\\\\\\" amountOff \\\\\\\" : \\\\\\\" 10.00 \\\\\\\" , \\\\\\\" couponId \\\\\\\" : \\\\\\\" 9WJ36SEC \\\\\\\" } \\\" , \\\" discountAmount \\\" : \\\" 10.00 \\\" }" ,
"order_no" : "123456789" ,
"alipay_jump_schema" : "升级:alipays://platformapi/startApp?appId=60000157&orderStr=XXXXXXXXXX;降级/取消后撤销:https://render.alipay.com/XXXXXXXXXX" ,
"pay_amount" : 100 ,
"subscription_id" : "20260320123156789" ,
"alipay_schema" : "https://basementurl.test.alipay.net/_1bQzQBRlIPjfo4eyx5SlMJ" ,
"refund_order_id" : "123456789" ,
"refund_amount" : 100
},
"sign" : "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
异常示例
{ "alipay_trade_subscription_modify_response" :{ "code" : "20000" , "msg" : "Service Currently Unavailable" , "sub_code" : "isp.unknow-error" , "sub_msg" : "系统繁忙" }, "sign" : "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" }
业务错误码
错误码 错误描述 解决方案 SYSTEM_ERROR系统繁忙 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 INVALID_PARAMETER参数有误 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试