开发者社区
社区提问意见反馈
开发者钉组织
扫描二维码
加入支付宝开发者钉组织
文档中心
网页&移动应用 
支付产品
私域产品
公域产品
营销产品
支付券
商家券 2.0
接入指南
api 列表
活动创建
活动修改
活动停止
预算追加
活动发放
优惠券核销
活动查询
蚂蚁店铺
相关资料
商家会员卡
营销活动送红包
红包
棋盘密云
芝麻实力标
资金产品
会员产品
信用产品
安全产品
广告产品
其他通用产品
开发 > 服务端 > 营销产品 > 商家券 2.0 >  >  > 创建商家券活动接口
文档更新记录 >
收藏
订阅更新
我的文档
设置
接入检测
即可查看检测结果)
若有未通过的接入检测项,接口将无法调通
1.创建商家券活动接口同步返回创建请求受理结果,但并不代表创建成功,只有当接收异步通知(商家券活动创建通知)才表示活动创建成功。
2.当activity_base_info.code_mode=merchant_upload时,当接收到异步通知(商家券活动创建通知)后,还需要进行券码导入

公共请求参数

参数类型是否必选最大长度描述示例值
app_idstring必选32
支付宝分配给开发者的应用id
2014072300007148
methodstring必选128
接口名称
alipay.marketing.activity.ordervoucher.create
formatstring可选40
仅支持json
json
charsetstring必选10
请求使用的编码格式,如utf-8,gbk,gb2312等
utf-8
sign_typestring必选10
商户生成签名字符串所使用的签名算法类型,目前支持rsa2和rsa,推荐使用rsa2
rsa2
signstring必选344
商户请求参数的签名串,详见签名
详见示例
timestampstring必选19
发送请求的时间,格式"yyyy-mm-dd hh:mm:ss"
2014-07-24 03:07:50
versionstring必选3
调用的接口版本,固定为:1.0
1.0
app_auth_tokenstring可选40
biz_contentstring必选
请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

业务请求参数

out_biz_no|外部业务单号必选string[0,64]
【描述】外部业务单号,用作幂等控制。
【注意事项】1.外部接入方需保证业务单号唯一。 2.参数不变的情况下,再次请求返回与上一次相同的结果。
【示例值】20170101000001654bb46ba
merchant_access_mode|商户接入模式必选string[0,32]
【描述】商户接入模式
【枚举值】
商户自接入模式: self_mode
服务商代接入模式: agency_mode
【注意事项】选择服务商代接入模式需配合 app_auth_token 代调用使用
【示例值】self_mode
activity_base_info|活动基础信息必选activitybaseinfo
【描述】活动基础信息
activity_name|活动名称必选string[1,20]
【描述】活动名称。 不对用户进行展示,仅供商家在后台管理活动使用。
【注意事项】限制:不允许传入空格。
【示例值】满10减1活动
code_mode|码模式必选string[1,32]
【描述】券码模式。
merchant_upload:商户建券时上传自定义券码,发券时系统随机选取上传的券码发放。
merchant_api:商户建券时不提前上传券码,发券时由商家指定券码发放。
【枚举值】
商户上传自定义code: merchant_upload
发奖时指定券码发奖: merchant_api
【注意事项】1、券码模式为merchant_api时,由于没有提前上传券码,只能由商户自己通过小程序领券插件指定券码发放优惠券。此模式的商家券无法在支付宝的公域投放(如支付结果页、商家群、消费券频道等),请确认后选择。
【示例值】merchant_upload
voucher_send_mode_info|券发放模式信息必选vouchersendmodeinfo
【描述】券发放方式
voucher_send_mode|券发放模式必选string[1,32]
【描述】券发放模式
【枚举值】
直领模式: direct_send_mode
【注意事项】当前仅支持直领模式
【示例值】direct_send_mode
voucher_send_rule_info|券发放规则必选vouchersendruleinfo
【描述】券发放规则
quantity|发行券的数量必选number[1,99999999]
【描述】总发券张数。
可以发放给用户的优惠券总数量。
【注意事项】1、码模式=merchant_upload时,数量必须设置为0,后续再调用同步券码接口上传券码,上传的券码数量为总发券张数。 2、码模式=merchant_api时,数值必须是大于0的整数。
【示例值】100
publish_start_time|券发放开始时间必选date
【描述】券发放开始时间, 格式:yyyy-mm-dd hh:mm:ss
【示例值】2017-01-01 00:00:01
publish_end_time|券发放结束时间必选date
【描述】券发放结束时间, 格式:yyyy-mm-dd hh:mm:ss
【注意事项】1.publish_end_time必须大于当前时间 2.publish_end_time必须大于publish_start_time 3.券发放结束时间publish_end_time 与 券发放开始时间publish_start_time 间隔必须小于等于180天
【示例值】2017-01-29 23:59:59
quantity_limit_per_user|每人领取限制可选number[0,999999999]
【描述】每人领取限制。
每个支付宝账号的可领券张数。
【注意事项】1、不填写或填入0表示不限制。
【示例值】1
natural_person_limit|是否做身份证号限制可选boolean
【描述】如用户使用同一身份证号注册或绑定多个支付宝账号,此用户只能通过一个支付宝账号完成领取
【示例值】false
phone_number_limit|是否开启电话号码领取限制可选boolean
【描述】如一个手机号注册或绑定多个支付宝账号,此用户仅能通过一个支付宝账号完成领取
【示例值】false
delivery_channel_list|推广渠道列表可选array[0,1000]
【描述】推广渠道列表
【枚举值】
消费券频道: consume_voucher
【示例值】["consume_voucher"]
voucher_deduct_info|券优惠抵扣信息必选voucherdeductinfo
【描述】券优惠信息
voucher_type|券类型必选string[1,32]
【描述】券类型
【枚举值】
满减券: fix_voucher
折扣券: discount_voucher
特价券: special_voucher
【示例值】fix_voucher
fix_voucher_info|满减券详情特殊可选fixvoucherinfo
【描述】满减券详情
【注意事项】voucher_type = fix_voucher必传
【必选条件】voucher_type = fix_voucher必传
amount|券面额必选price[0.10,3000.00]
【描述】面额,每张代金券可以抵扣的金额。
取值范围:
[0.1,3000]
限制:
1.币种为人民币,单位为元。
2.小数点以后最多保留两位。
【注意事项】币种为人民币,单位为元。小数点以后最多保留两位。 取值范围:0.1<=x<=3000
【示例值】50.00
floor_amount|门槛金额可选price[0.1,50000]
【描述】门槛金额。取值范围:
[0.1,50000]
【注意事项】1.该字段不填写,认为无门槛。 2.币种为人民币,单位为元。 3.小数点以后最多保留两位。
【示例值】1000.00
voucher_deduct_threshold_info|优惠门槛信息可选voucherdeductthresholdinfo
【描述】优惠门槛信息
voucher_goods_quantity_specification_info|商品规格信息可选vouchergoodsquantityspecificationinfo
【描述】商品规格信息,数量,尺寸,大小等
【注意事项】若需要填入规格信息,则directional_type,specification_quantity,specification_unit必填
directional_type|定向类型必选string[1,32]
【描述】定向类型用于规格设置,比如:fix 表示 固定满x件
【枚举值】
固定: fix
【示例值】fix
specification_quantity|数量必选number[1,999999999]
【描述】数量
【注意事项】大于0
【示例值】2
specification_unit|单位必选string[1,32]
【描述】单位
【枚举值】
件: count_number
单: order_number
【示例值】count_number
discount_voucher_info|折扣券详情特殊可选discountvoucherinfo
【描述】折扣券详情
【注意事项】voucher_type=discount_voucher时必传
【必选条件】voucher_type=discount_voucher时必传
discount|折扣率必选string[1,12]
【描述】折扣率,比如:6.5折填入6.5。取值范围:[0.1,9.9]
【注意事项】取值范围:0.1<=x<=9.9,比如:6.5折填入6.5;
【示例值】6.5
ceiling_amount|封顶金额必选price[0.10,15000.00]
【描述】封顶金额。取值范围:
[0.1,15000]
【注意事项】1.币种为人民币,单位为元。 2.小数点以后最多保留两位。
【示例值】50.00
floor_amount|门槛金额可选price[0.10,50000.00]
【描述】门槛金额。取值范围:
[0.1,50000]
【注意事项】1.该字段不填写,认为无门槛。 2.币种为人民币,单位为元。 3.小数点以后最多保留两位。
【示例值】1000.00
voucher_deduct_threshold_info|优惠门槛信息可选voucherdeductthresholdinfo
【描述】优惠门槛信息
voucher_goods_quantity_specification_info|商品规格信息可选vouchergoodsquantityspecificationinfo
【描述】商品规格信息,数量,尺寸,大小等
【注意事项】若需要填入规格信息,则directional_type,specification_quantity,specification_unit必填
directional_type|定向类型必选string[1,32]
【描述】定向类型用于规格设置,比如:fix 表示 固定满x件,appoint 表示指定第n件
【枚举值】
固定: fix
指定: appoint
【示例值】fix
specification_quantity|数量必选number[1,999999999]
【描述】数量
【注意事项】大于0
【示例值】2
specification_unit|单位必选string[1,32]
【描述】单位
【枚举值】
件: count_number
单: order_number
【示例值】count_number
special_voucher_info|特价券详情特殊可选specialvoucherinfo
【描述】特价券详情
【注意事项】1.voucher_type=special_voucher时必传 2.商品信息voucher_available_scope_info. voucher_available_goods_info必传
【必选条件】券类型 voucher_type 为特价券 special_voucher 时必传。
special_amount|特价必选price[0.00,999.00]
【描述】特价,即:原价-特价=优惠金额。
取值范围:
[0,999]
限制:
1.原价voucher_available_scope_info. voucher_available_goods_info.origin_amount必传。
2.商品名称voucher_available_scope_info. voucher_available_goods_info.goods_name必传。
3.原价必须大于特价,即:origin_amount>special_amount;
4.币种为人民币,单位为元。
5.小数点以后最多保留两位。
【注意事项】币种为人民币,单位为元。小数点以后最多保留两位; 取值范围:0<=x<=999; 原价必须大于特价,即:origin_amount>special_amount;
【示例值】10.00
floor_amount|门槛金额可选price[0.10,50000.00]
【描述】门槛金额。取值范围:
[0.1,50000]
【注意事项】1.该字段不填写,认为无门槛。 2.币种为人民币,单位为元。 3.小数点以后最多保留两位。
【示例值】1000.00
voucher_deduct_threshold_info|优惠门槛信息可选voucherdeductthresholdinfo
【描述】优惠门槛信息
voucher_express_info|邮费信息可选voucherexpressinfo
【描述】邮费信息
pay_express|邮费标识必选string[1,32]
【描述】邮费标识,属于券的服务,用于用户门槛信息展示
【枚举值】
付邮费: pay_for_express
免邮费: free_for_express
【注意事项】如果不涉及邮费信息,可以选择不填
【示例值】pay_for_express
voucher_goods_quantity_specification_info|商品规格信息可选vouchergoodsquantityspecificationinfo
【描述】商品规格信息,数量,尺寸,大小等
【注意事项】若需要填入规格信息,则directional_type,specification_quantity,specification_unit必填
directional_type|定向类型必选string[1,32]
【描述】定向类型用于规格设置,比如:fix 表示 固定满x件,appoint 表示指定第n件
【枚举值】
固定: fix
指定: appoint
【示例值】fix
specification_quantity|数量必选number[1,999999999]
【描述】数量
【注意事项】大于0
【示例值】2
specification_unit|单位必选string[1,32]
【描述】单位
【枚举值】
件: count_number
单: order_number
【示例值】count_number
exchange_voucher_info|兑换券详情可选exchangevoucherinfo
【描述】兑换券详情。
【注意事项】1、券类型为兑换券时必传。 2、指定小程序可用商品voucher_available_item_info时,不支持兑换券类型
exchange_goods_info|兑换商品信息必选voucherexchangegoodsinfo
【描述】兑换商品信息
exchange_goods_name|兑换商品名称必选string[1,16]
【描述】兑换商品名称
【示例值】荣耀耳机
amount|券的价值可选price[0.10,3000.00]
【描述】券的价值
【注意事项】币种为人民币,单位为元。小数点以后最多保留两位。 取值范围:0.1<=x<=3000
【示例值】100.00
floor_amount|门槛金额可选price[0.10,50000.00]
【描述】优惠门槛金额,表示只有当订单金额大于等于门槛金额时券才能使用。该字段为空时表示无门槛。 门槛金额的校验由服务商(商户)核销时自行校验,支付宝侧只做展示使用。
【注意事项】币种为人民币,单位为元。小数点以后最多保留两位。 设置门槛:取值范围:0.1<=x<= 50000。 如果设置了门槛金额,则必须大于等于0.1,不可以等于0
【示例值】1000.00
voucher_deduct_threshold_info|优惠门槛信息可选voucherdeductthresholdinfo
【描述】优惠门槛信息
voucher_express_info|邮费信息可选voucherexpressinfo
【描述】邮费信息
pay_express|邮费标识必选string[1,32]
【描述】邮费标识,属于券的服务,用于用户门槛信息展示
【枚举值】
付邮费: pay_for_express
免邮费: free_for_express
【注意事项】如果不涉及邮费信息,可以选择不填
【示例值】pay_for_express
voucher_goods_quantity_specification_info|商品规格信息可选vouchergoodsquantityspecificationinfo
【描述】商品规格信息,数量,尺寸,大小等
【注意事项】若需要填入规格信息,则directional_type,specification_quantity,specification_unit必填
directional_type|定向类型必选string[1,32]
【描述】定向类型用于规格设置,比如:fix 表示 固定满x件,appoint 表示指定第n件
【枚举值】
固定: fix
指定: appoint
【示例值】fix
specification_quantity|数量必选number[1,999999999]
【描述】数量
【注意事项】大于0
【示例值】2
specification_unit|单位必选string[1,32]
【描述】单位
【枚举值】
件: count_number
单: order_number
【示例值】count_number
voucher_available_scope_info|券可用范围必选voucheravailablescopeinfo
【描述】券可用范围
voucher_available_geography_scope_info|券可用地理位置必选voucheravailablegeographyscopeinfo
【描述】券可用地理位置
【注意事项】指定小程序可用商品voucher_available_item_info时,为线上核销,不支持传入可用地理位置信息
available_geography_scope_type|券可用地理位置类型必选string[1,32]
【描述】券可用地理位置类型(二选一)
可用门店: shop
可用城市: city_code
【枚举值】
可用门店: shop
可用城市: city_code
【示例值】shop
available_geography_shop_info|券可用门店特殊可选voucheravailablegeographyshopinfo
【描述】券可用门店
【注意事项】available_geography_scope_type=shop时必传
以下参数 二选一 传入必选
available_shop_ids|券可使用的门店列表array[0,1024]
【描述】券可使用的门店列表。取值来源:
列表中的门店id是通过调用接口返回的支付宝门店id 接口参数是列表类型。
【注意事项】1.available_shop_ids中的门店id必须是支付宝门店id。 2.available_shop_ids如果包含重复的门店id会自动进行去重操作。
【示例值】["2018051000502000000011111111","2018040200502000000011111111","2018062800502000000022271997"]
available_geography_all_shop|全部门店可用voucheravailablegeographyallshopinfo
【描述】全部门店可用
available_brand_id|全部门店可用的品牌id特殊可选string[1,84000]
【描述】全部门店可用的品牌id
提示:
1.目前只支持传入当前券归属商户的品牌id
2.品牌id可以在登录b.alipay.com-账户中心-品牌管理里查看。如果没有品牌,可以先创建品牌。sop:
注意事项
1.只支持传入单个品牌id
2.传入品牌id后,券的商户品牌和logo仍以voucher_display_pattern_info传入为准。
【注意事项】1、只允许入参当前调用接口pid创建的品牌,代运营模式取被代运营商户的品牌。 2、自动同步和更新品牌下的全部门店
【示例值】2022111600502042000001279859
merchant_ids|全部门店可用的商户id可选array[0,1]
【描述】全部门店可用的商户id
限制:
1.目前只支持传当前活动归属的商户id
2.目前只支持传入单个商户id
【注意事项】1.目前只支持传当前活动归属的商户id 2.目前只支持传入单个商户id
【示例值】["208805x000502"]
exclude_shop_ids|券不可使用的门店列表可选array[1,10000]
【描述】券不可使用的门店列表,指定商户全部门店可用时可通过该字段排除部分不可用门店。取值来源:
列表中的门店id是通过调用接口返回的支付宝门店id 接口参数是列表类型
【注意事项】1.exclude_shop_ids中的门店id必须是支付宝门店id。 2.exclude_shop_ids如果包含重复的门店id会自动进行去重操作。
【示例值】["2018051000502000000011111111","2018040200502000000011111111","2018062800502000000022271997"]
available_geography_city_info|券可用城市特殊可选voucheravailablegeographycityinfo
【描述】券可用城市
以下参数 二选一 传入必选
all_city|是否全国boolean
【描述】是否全国。枚举值:
true:是
false: 否
【注意事项】选择全国后,无须填写available_city_codes字段。系统默认填充全国全部城市信息。
【示例值】false
available_city_codes|城市编码array[1,10000]
【描述】城市编码。取值来源:, 请选择区域类型=3的地区码,比如:呼和浩特,150100。
【示例值】["150100"]
voucher_available_goods_info|券可用商品特殊可选voucheravailablegoodsinfo
【描述】券可用商品
【注意事项】1.voucher_deduct_info. voucher_type=fix_voucher/discount_voucher时,该对象不填则为全场可用,需要升级单品可用,则该对象必传。 2.voucher_deduct_info. voucher_type=special_voucher时必传
goods_name|商品名称必选string[1,12]
【描述】商品名称
【示例值】美味甜甜圈
origin_amount|原价特殊可选price[0.01,999999999]
【描述】商品原价
【注意事项】voucher_deduct_info. voucher_type=special_voucher\discount_voucher时必传
【示例值】100.00
voucher_use_rule_info|券核销限制必选voucheruseruleinfo
【描述】券核销限制
voucher_use_time_info|券核销时间必选voucherusetimeinfo
【描述】券核销时间
period_type|券有效期必选string[1,32]
【描述】券有效期
【枚举值】
绝对时间: absolute
相对时间: relative
【示例值】absolute
absolute_period_info|券绝对时间可用特殊可选voucherabsoluteperiodinfo
【描述】券绝对时间可用
【注意事项】period_type=absolute时必传
valid_begin_time|券可使用的开始时间必选date
【描述】券可使用的开始时间,格式:yyyy-mm-dd hh:mm:ss
【示例值】2017-01-10 00:00:00
valid_end_time|券可使用的结束时间必选date
【描述】券可使用的结束时间, 格式:yyyy-mm-dd hh:mm:ss
【注意事项】券可使用的结束时间valid_end_time 必须大于 券的发放结束时间 publish_end_time
【示例值】2017-01-13 23:59:59
time_restrict_info|核销时间限制可选timerestrictinfo
【描述】核销时间限制
usable_period_info|可用时间段可选array[1,1000]
【描述】可用时间段
rule_type|规则类型必选string[1,32]
【描述】规则类型
【枚举值】
周期类型: week
日期类型: date
法定节假日类型: holiday
【示例值】week
week_rule_info|周期规则特殊可选weekruleinfo
【描述】周期规则。当rule_type = week时,不能为空
week_day|星期数必选string[1,32]
【描述】星期数,以“,”连接多个星期数
【示例值】1,2
time_range_info|时间段必选timerangeinfo
【描述】时间段
begin_time|开始时间必选string[1,8]
【描述】开始时间 格式:hh:mm:ss
【示例值】00:00:00
end_time_info|结束时间必选endtimeinfo
【描述】结束时间,可设置当日或次日结束,例如:22:00-次日07:00
end_time_type|结束时间类型必选string[1,32]
【描述】结束时间类型
【枚举值】
当日: same_day
次日: next_day
【示例值】next_day
end_time|结束时间必选string[1,8]
【描述】结束时间 格式:hh:mm:ss
【示例值】23:59:59
disable_period_info|不可用时间段可选array[1,1000]
【描述】不可用时间段
rule_type|规则类型必选string[1,32]
【描述】规则类型
【枚举值】
周期类型: week
日期类型: date
法定节假日类型: holiday
【示例值】date
date_rule_info|日期规则特殊可选dateruleinfo
【描述】日期规则。当ruletype = date时,不能为空
date_range_info|日期范围必选daterangeinfo
【描述】日期范围
begin_date|开始日期必选string[1,12]
【描述】开始日期 格式:yyyy-mm-dd
【示例值】2023-02-01
end_date|结束日期必选string[1,12]
【描述】结束日期 格式:yyyy-mm-dd
【示例值】2023-03-31
time_range_info|时间段必选timerangeinfo
【描述】时间段
begin_time|开始时间必选string[1,8]
【描述】开始时间 格式:hh:mm:ss
【示例值】00:00:00
end_time_info|结束时间必选endtimeinfo
【描述】结束时间,可设置当日或次日结束,例如:22:00-次日07:00
end_time_type|结束时间类型必选string[1,32]
【描述】结束时间类型
【枚举值】
当日: same_day
次日: next_day
【示例值】next_day
end_time|结束时间必选string[1,8]
【描述】结束时间 格式:hh:mm:ss
【示例值】23:59:59
holiday_rule_info|节假日规则特殊可选holidayruleinfo
【描述】节假日规则。当ruletype = holiday时,不能为空
time_range_info|时间段必选timerangeinfo
【描述】时间段
begin_time|开始时间必选string[1,8]
【描述】开始时间 格式:hh:mm:ss
【示例值】00:00:00
end_time_info|结束时间必选endtimeinfo
【描述】结束时间,可设置当日或次日结束,例如:22:00-次日07:00
end_time_type|结束时间类型必选string[1,32]
【描述】结束时间类型
【枚举值】
当日: same_day
次日: next_day
【示例值】next_day
end_time|结束时间必选string[1,8]
【描述】结束时间 格式:hh:mm:ss
【示例值】23:59:59
relative_period_info|券相对时间特殊可选voucherrelativeperiodinfo
【描述】券相对时间
【注意事项】period_type=relative时必传
wait_days_after_receive|用户领券后需要等待 n 天生效必选number[0,999999999]
【描述】用户领券后需要等待n天,券才可以生效。
【注意事项】字段值为0表示用户领券后立刻生效
【示例值】1
valid_days_after_receive|券生效后 n 天内可以使用必选number[1,999999999]
【描述】券生效后n天内可以使用。 可以配合wait_days_after_receive字段使用。 比如:wait_days_after_receive=1,valid_days_after_receive=2,今天时1号0点0分0秒,那么2号0点0分0秒券生效可以开始使用,4号23点59分59秒,有效期到期不可用。
【注意事项】valid_days_after_receive必须大于0
【示例值】2
time_restrict_info|核销时间限制可选timerestrictinfo
【描述】核销时间限制
usable_period_info|可用时间段可选array[1,1000]
【描述】可用时间段
rule_type|规则类型必选string[1,32]
【描述】规则类型
【枚举值】
周期类型: week
日期类型: date
法定节假日类型: holiday
【示例值】week
week_rule_info|周期规则特殊可选weekruleinfo
【描述】周期规则。当rule_type = week时,不能为空
week_day|星期数必选string[1,32]
【描述】星期数,以“,”连接多个星期数
【示例值】1,2
time_range_info|时间段必选timerangeinfo
【描述】时间段
begin_time|开始时间必选string[1,8]
【描述】开始时间 格式:hh:mm:ss
【示例值】00:00:00
end_time_info|结束时间必选endtimeinfo
【描述】结束时间,可设置当日或次日结束,例如:22:00-次日07:00
end_time_type|结束时间类型必选string[1,32]
【描述】结束时间类型
【枚举值】
当日: same_day
次日: next_day
【示例值】next_day
end_time|结束时间必选string[1,8]
【描述】结束时间 格式:hh:mm:ss
【示例值】23:59:59
disable_period_info|不可用时间段可选array[1,1000]
【描述】不可用时间段
rule_type|规则类型必选string[1,32]
【描述】规则类型
【枚举值】
周期类型: week
日期类型: date
法定节假日类型: holiday
【示例值】date
date_rule_info|日期规则特殊可选dateruleinfo
【描述】日期规则。当ruletype = date时,不能为空
date_range_info|日期范围必选daterangeinfo
【描述】日期范围
begin_date|开始日期必选string[1,12]
【描述】开始日期 格式:yyyy-mm-dd
【示例值】2023-02-01
end_date|结束日期必选string[1,12]
【描述】结束日期 格式:yyyy-mm-dd
【示例值】2023-03-31
time_range_info|时间段必选timerangeinfo
【描述】时间段
begin_time|开始时间必选string[1,8]
【描述】开始时间 格式:hh:mm:ss
【示例值】00:00:00
end_time_info|结束时间必选endtimeinfo
【描述】结束时间,可设置当日或次日结束,例如:22:00-次日07:00
end_time_type|结束时间类型必选string[1,32]
【描述】结束时间类型
【枚举值】
当日: same_day
次日: next_day
【示例值】next_day
end_time|结束时间必选string[1,8]
【描述】结束时间 格式:hh:mm:ss
【示例值】23:59:59
holiday_rule_info|节假日规则特殊可选holidayruleinfo
【描述】节假日规则。当ruletype = holiday时,不能为空
time_range_info|时间段必选timerangeinfo
【描述】时间段
begin_time|开始时间必选string[1,8]
【描述】开始时间 格式:hh:mm:ss
【示例值】00:00:00
end_time_info|结束时间必选endtimeinfo
【描述】结束时间,可设置当日或次日结束,例如:22:00-次日07:00
end_time_type|结束时间类型必选string[1,32]
【描述】结束时间类型
【枚举值】
当日: same_day
次日: next_day
【示例值】next_day
end_time|结束时间必选string[1,8]
【描述】结束时间 格式:hh:mm:ss
【示例值】23:59:59
voucher_customer_guide_info|券引导详情必选vouchercustomerguideinfo
【描述】券引导详情
voucher_use_guide_info|券核销详情必选voucheruseguideinfo
【描述】指定小程序可用商品voucher_available_item_info时,不允许指定核销引导信息。
use_guide_mode|使用引导模式必选array[1,1000]
【描述】券核销引导,可以多选。offline_code:券码扫码核销,控制卡包是否可展示券码,填写则展示。mini_app:小程序线上核销,控制卡包是否可展示“去使用”小程序引导,填写则展示。
【枚举值】
券码扫码核销: offline_code
小程序线上核销: mini_app
【注意事项】1. 传入mini_app,则mini_app_use_guide_info必传。 2. 该字段为列表类型。
【示例值】["mini_app"]
mini_app_use_guide_info|小程序核销引导可选voucherminiappuseguideinfo
【描述】小程序核销引导
【注意事项】1. use_guide_mode包含mini_app时必传 2.mini_app_url和mini_app_service_codes只能二选一
以下参数 二选一 传入必选
mini_app_url|指定跳转到mini_app_id时的具体页面路径string[1,64]
【描述】小程序跳转链接
【注意事项】1、必须是支付宝小程序链接 ,小程序拼接规则:scheme介绍 2、小程序链接里的appid必须是当前账户或同公司其他账户(同mid)名下的小程序
【示例值】alipays://platformapi/startapp?appid=xxxx
mini_app_service_codes小程序服务编码array[0,16]
【描述】小程序服务编码。取值来源:通过接口创建服务后获取。
【注意事项】当前只支持一个服务code
【示例值】["2020030921000303380758"]
voucher_display_pattern_info|券展示信息必选voucherdisplaypatterninfo
【描述】券展示信息
brand_name|商户品牌名称必选string[1,12]
【描述】商户品牌名称。
【注意事项】服务商平台模式即belong_merchant_info.business_type为isv时必传
【示例值】肯德基
brand_logo|商家 logo必选string[1,128]
【描述】商家logo。取值来源:需要通过接口上传图片,指定file_key为promo_brand_logo,返回的resource_id即为该参数的值。
【注意事项】上传图片尺寸600*600,支持格式:png、jpg、jpeg、bmp,大小不超过200kb
【示例值】adedsktiqo-u5vjuqvbcqwaaacmaaqed
voucher_description|券详细使用说明必选string[1,1000]
【描述】券详细使用说明。
【示例值】1、本券不可兑换现金,不可找零。2、每个用户最多可以领取1张。3、如果订单发生退款,优惠券无法退还。
以下参数 二选一 传入必选
customer_service_mobile|客服电话string[1,20]
【描述】客服电话
【注意事项】客服电话和客服链接必须二选一
【示例值】0571-8888xxxx
customer_service_url|客服链接string[1,255]
【描述】客服链接
【注意事项】客服电话和客服链接必须二选一
【示例值】alipays://platformapi/startapp?appid=xxxx
voucher_name|对消费者展示的券(商品)名称特殊可选string[1,20]
【描述】券名称。
【注意事项】兑换券必填,其他类型不支持
【示例值】满10减1券
voucher_image|券封面图可选string[1,64]
【描述】券详情页封面图,用于展示在用户支付宝卡包券详情页。取值来源:需要通过接口上传图片,指定file_key为promo_voucher_image,接口返回的resource_id即为该参数的值。
【注意事项】1、上传图片尺寸600*600,支持格式:png、jpg、jpeg、bmp,大小不超过200kb 2、指定小程序可用商品voucher_available_item_info时,不支持传入详情页封面图
【示例值】adedsktiqo-u5vjuqvbcqwaaacmaaqed
voucher_detail_images|图片详情列表可选array[1,3]
【描述】券详细图列表,用于展示在用户支付宝卡包券详情页 需要通过 接口上传图片,指定file_key为promo_voucher_detail_image ,接口返回的resource_id即为该参数的值
【注意事项】1.上传图片尺寸600*600,支持格式:png、jpg、jpeg、bmp,大小不超过200kb。 2.voucher_image填入,该值才能填入。 3.最多3张。 4.指定小程序可用商品voucher_available_item_info时,不支持传入详细图列表
【示例值】["adedsktiqo-u5vjuqvbcqwaaacmaaqe1","adedsktiqo-u5vjuqvbcqwaaacmaaqe2","adedsktiqo-u5vjuqvbcqwaaacmaaqe3"]
常见请求示例
curl 'https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.marketing.activity.ordervoucher.create&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={
	"activity_base_info":{
		"activity_name":"五折优惠券",
		"code_mode":"merchant_upload"
	},
	"merchant_access_mode":"self_mode",
	"out_biz_no":"20170101000001654bb46ba",
	"voucher_available_scope_info":{
		"voucher_available_geography_scope_info":{
			"available_geography_city_info":{
				"all_city":true
			},
			"available_geography_scope_type":"city_code"
		}
	},
	"voucher_customer_guide_info":{
		"voucher_use_guide_info":{
			"mini_app_use_guide_info":{
				"mini_app_url":"alipays://platformapi/startapp?appid=xxxx"
			},
			"use_guide_mode":[
				"mini_app"
			]
		}
	},
	"voucher_deduct_info":{
		"discount_voucher_info":{
			"ceiling_amount":"1300",
			"discount":"5",
			"floor_amount":"500"
		},
		"voucher_type":"discount_voucher"
	},
	"voucher_display_pattern_info":{
		"brand_logo":"a*aa98qomzi4saaaaaaaaaaaaaarwnaq",
		"brand_name":"商家优惠",
		"voucher_description":"五折优惠券"
	},
	"voucher_send_mode_info":{
		"voucher_send_mode":"direct_send_mode",
		"voucher_send_rule_info":{
			"publish_end_time":"2023-09-30 23:59:59",
			"publish_start_time":"2023-09-11 00:00:00",
			"quantity":0,
			"quantity_limit_per_user":0
		}
	},
	"voucher_use_rule_info":{
		"voucher_use_time_info":{
			"absolute_period_info":{
				"valid_begin_time":"2023-09-12 00:00:00",
				"valid_end_time":"2023-09-30 23:59:59"
			},
			"period_type":"absolute"
		}
	}
}' 
说明:本示例仅供参考。

公共响应参数

参数类型是否必选最大长度描述示例值
codestring必选-
网关返回码,
40004
msgstring必选-
网关返回码描述,
business failed
sub_codestring可选-
业务返回码,参见具体的api接口文档
acq.trade_has_success
sub_msgstring可选-
业务返回码描述,参见具体的api接口文档
交易已被支付
signstring必选-
签名,
dzxh8eetuahoye3w1j poiphfdxoybfunn1lket/v7p4zjdyojwea6izs6hz0ydw5cp/viufub5i0/v5wens3oyr8zredqo6d futdlhdc efyckiqhbxizgngpdpdfp1pis7bdhhzrszhbrqb7o4k3dxc aanfauu4v6zdwczo=

业务响应参数

activity_id|活动id必选string(128)
【描述】活动id
【示例值】2016042700826004508401111111
voucher_available_scope_result_info|券可用范围结果可选voucheravailablescoperesultinfo
【描述】可用范围结果
voucher_available_geography_scope_result_info|可用地理位置可选voucheravailablegeographyscoperesultinfo
【描述】可用地理位置
available_geography_shop_result_info|可用门店结果可选voucheravailablegeographyshopresultinfo
【描述】可用门店结果
success_available_shop_ids|券可使用的门店列表可选string[](84000)
【描述】券可使用的门店列表
【注意事项】1. shop_ids 中的门店id必须是支付宝门店 id。 2. shop_ids 如果包含重复的门店id会自动进行去重操作。 3. shop_ids、real_shop_ids、order_voucher_merchant_all_shop 必须三选一。
【示例值】["2018051000502000000011111111","2018040200502000000011111111","2018062800502000000022271997"]
fail_available_shop_infos|失败的可用门店可选voucherfailshopinfo[]
【描述】失败的可用门店
fail_reasons|请求失败的原因必选string[](32)
【描述】请求失败的原因
【枚举值】
门店信息不全: shop_info_not_pass
门店不存在: shop_not_exist
门店与商户没有关联关系: merchant_shop_relation_not_exist
【示例值】["shop_not_exist"]
shop_id|门店 id可选string(32)
【描述】请求失败的支付门店id
【示例值】2018051000502000000011111111
fail_message|请求失败提示信息可选string(1000)
【描述】请求失败提示信息
【示例值】门店不存在
available_geography_all_shop_result_info|全部门店结果可选voucheravailablegeographyallshopresultinfo
【描述】全部门店结果
success_exclude_shop_ids|请求成功的不可用门店列表可选string[](84000)
【描述】请求成功的不可用门店列表。
【示例值】["2018051000502000000011111111","2018040200502000000011111111","2018062800502000000022271997"]
fail_exclude_shop_infos|请求失败的不可用门店详情可选voucherfailshopinfo[]
【描述】请求失败的不可用门店详情。
fail_reasons|请求失败的原因必选string[](32)
【描述】请求失败的原因
【枚举值】
门店信息不全: shop_info_not_pass
门店不存在: shop_not_exist
门店与商户没有关联关系: merchant_shop_relation_not_exist
【示例值】["shop_not_exist"]
shop_id|门店 id可选string(32)
【描述】请求失败的支付门店id
【示例值】2018051000502000000011111111
real_shop_id|物理门店id可选string(32)
【描述】请求失败的物理门店id
【示例值】1
fail_message|请求失败提示信息可选string(1000)
【描述】请求失败提示信息
【示例值】门店不存在
响应示例
{
    "alipay_marketing_activity_ordervoucher_create_response": {
        "code": "10000",
        "msg": "success",
        "activity_id": "2016042700826004508401111111",
        "voucher_available_scope_result_info": {
            "voucher_available_geography_scope_result_info": {
                "available_geography_shop_result_info": {
                    "success_available_shop_ids": [
                        "2018051000502000000011111111",
                        "2018040200502000000011111111",
                        "2018062800502000000022271997"
                    ],
                    "fail_available_shop_infos": [
                        {
                            "shop_id": "2018051000502000000011111111",
                            "fail_reasons": [
                                "shop_not_exist"
                            ],
                            "fail_message": "门店不存在"
                        }
                    ],
                    "available_geography_all_shop_result_info": {
                        "success_exclude_shop_ids": [
                            "2018051000502000000011111111",
                            "2018040200502000000011111111",
                            "2018062800502000000022271997"
                        ],
                        "fail_exclude_shop_infos": [
                            {
                                "shop_id": "2018051000502000000011111111",
                                "real_shop_id": "1",
                                "fail_reasons": [
                                    "shop_not_exist"
                                ],
                                "fail_message": "门店不存在"
                            }
                        ]
                    }
                }
            }
        }
    },
    "sign": "eritjkeijkjhkkkkkkkhjereeeeeeeeeee"
}
说明:本示例仅供参考。

公共错误码

业务错误码

错误码错误描述凯发app官方网站的解决方案
system_error服务器异常
可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试
invalid_parameter参数有误
请根据接口返回的参数非法的具体错误信息,修改参数后进行重试
biz_error业务异常,门店无效。请检查门店是否存在,并且门店属于该商户pid
检查传入的门店id在支付宝体系中是否存在。同时门店id要归属于商户pid 或 pid所关联的smid。
biz_error业务异常,小程序无效。请检查小程序是否存在,并且小程序属于该商户pid
检查传入的小程序id在支付宝体系中是否存在。同时小程序id要归属于商户pid。
biz_error业务异常,缺少代运营关系
isv与商户进行代运营关系的授权
biz_error业务异常,活动存在正在进行中的其他操作
活动的创建、修改、追加等操作都是异步进行的。因此如在活动修改中时,发出追加操作,会提示活动存在正在进行中的其他操作。
business_has_risk请求存在风险
请检查参数传入是否正确
discount_amount_insufficient最高优惠金额小于下限
请提高优惠金额后重新发起请求
内容没有解决您的问题?您还可以前往 或 寻求帮助
凯发k8官方网娱乐官方 copyright © 支付宝(杭州)信息技术有限公司  | icp证浙b2-20160559
该文档对你是否有帮助?
当前页面目录
为开发者能享受更简单的协议处理逻辑、更丰富的开源工具配套、更低的接口响应时延,支付宝开放平台推出符合oas3.0规范的,助力开发体验。新版本文档请点击“查看v3版本”进行访问。
网站地图