商家券
1.创建商家券活动接口同步返回创建请求受理结果,但并不代表创建成功,只有当接收异步通知(商家券活动创建通知)才表示活动创建成功。
2.当activity_base_info.code_mode=merchant_upload时,当接收到异步通知(商家券活动创建通知)后,还需要进行券码导入
2.当activity_base_info.code_mode=merchant_upload时,当接收到异步通知(商家券活动创建通知)后,还需要进行券码导入
创建商家券活动接口返回结果并不代表活动创建成功,必须等待消息回调后才能确保创建成功。
如果成功消息长时间未送达,请联系相关凯发app官方网站的技术支持协助排查。
历史接入商家券产品的用户可以查看旧版 (创建商家券活动)接口文档。
如果成功消息长时间未送达,请联系相关凯发app官方网站的技术支持协助排查。
历史接入商家券产品的用户可以查看旧版 (创建商家券活动)接口文档。
公共请求参数
业务请求参数
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:商户建券时不提前上传券码,发券时由商家指定券码发放。
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
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,3000]
限制:
1.币种为人民币,单位为元。
2.小数点以后最多保留两位。
【注意事项】币种为人民币,单位为元。小数点以后最多保留两位。 取值范围:0.1<=x<=3000
【示例值】50.00
floor_amount|门槛金额可选price[0.1,50000]
【描述】门槛金额。取值范围:
[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]
[0.1,15000]
【注意事项】1.币种为人民币,单位为元。
2.小数点以后最多保留两位。
【示例值】50.00
floor_amount|门槛金额可选price[0.10,50000.00]
【描述】门槛金额。取值范围:
[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件,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,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]
[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
可用城市: city_code
【示例值】shop
available_geography_shop_info|券可用门店特殊可选voucheravailablegeographyshopinfo
【描述】券可用门店
【注意事项】available_geography_scope_type=shop时必传
以下参数 二选一 传入必选
available_shop_ids|券可使用的门店列表array[0,1024]
【描述】券可使用的门店列表。取值来源:
列表中的门店id是通过调用接口返回的支付宝门店id 接口参数是列表类型。
列表中的门店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.目前只支持传入当前券归属商户的品牌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
【注意事项】1.目前只支持传当前活动归属的商户id
2.目前只支持传入单个商户id
【示例值】["208805x000502"]
exclude_shop_ids|券不可使用的门店列表可选array[1,10000]
【描述】券不可使用的门店列表,指定商户全部门店可用时可通过该字段排除部分不可用门店。取值来源:
列表中的门店id是通过调用接口返回的支付宝门店id 接口参数是列表类型
列表中的门店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: 否
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 '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"
}
}
}'
说明:本示例仅供参考。
公共响应参数
业务响应参数
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 | 最高优惠金额小于下限 | 请提高优惠金额后重新发起请求 |