上传自定义券码模式
接入支付宝门店（可选）
business_address.longitude（经度）及 business_address.latitude（纬度）且使用 高德经纬度查询 ，否则商家券无法在支付宝投放展示。产品接入核心模块
订阅消息
设置接收消息的应用网关地址
订阅消息接口
msg_method 参数判断消息类型。| 消息接口英文名 | 消息接口中文名 | 作用 |
|---|---|---|
| alipay.marketing.activity.message.created | 商家券活动创建通知 | 同步商家券活动创建结果。 |
| alipay.marketing.activity.message.appended | 商家券活动预算追加通知 | 同步商家券活动库存追加结果。 |
| alipay.marketing.activity.message.modified | 商家券活动修改通知 | 同步商家券活动修改结果。 |
| alipay.marketing.activity.message.stopped | 商家券活动停止通知 | 同步商家券领取停止结果。 |
| alipay.marketing.activity.message.received | 商家券领取通知 | 同步用户领取商家券及对应券码信息。 |
创建商家券活动
接口时序图
第一步：创建活动
activity_id（活动 ID）。不同券类型优惠规则说明可查看 商家券类型。示例代码
| 参数名称 | 参数说明 |
|---|---|
| out_biz_no | 商户创建券活动外部编号，确保唯一 |
| merchant_access_mode | 商户接入模式：商户自接入模式: SELF_MODE服务商代接入模式: AGENCY_MODE |
| activity_base_info | 活动基础信息， activity_base_info.code_mode=MERCHANT_UPLOAD表示上传自定义券码 |
| voucher_available_scope_info | 券可用范围 |
单品券：voucher_available_scope_info.voucher_available_goods_inofo.goods_name | |
全场券： 不传goods_name即为全场优惠券 | |
| voucher_deduct_info | 券优惠抵扣信息 |
voucher_type 券类型满减券: FIX_VOUCHER折扣 券: DISCOUNT_VOUCHER特价券: SPECIAL_VOUCHER兑换券: EXCHANGE_VOUCHER满减券（FIX_VOUCHER）、折扣券（DISCOUNT_VOUCHER）支持配置为 全场优惠券 或 单品优惠券。特价券（SPECIAL_VOUCHER）仅支持配置为 单品优惠券。 | |
| voucher_use_rule_info.voucher_use_time_info | 券核销限制，券核销时间 |
period_type券有效期类型period_type=ABSOLUTE 绝对时间 ; period_type=RELATIVE 相对时间券绝对时间和券相对时间二选一 | |
| voucher_use_rule_info.voucher_use_time_info.absolute_period_info | 若 period_type=ABSOLUTE 绝对时间，券可核销有效期以 [absolute_period_info.valid_begin_time,absolute_period_info.valid_end_time] 区间为准。 |
| voucher_use_rule_info.voucher_use_time_info.relative_period_info | 若 period_type=RELATIVE 相对时间，券可核销有效期以 alipay.marketing.activity.message.received（商家券领取通知接口）中 event_time（领券时间，精确到秒）加本接口设置的有效时间规则（精确到天）为准： [event_time + relative_period_info.wait_days_after_receive，event_time + relative_period_info.wait_days_after_receive +``relative_period_info.valid_days_after_receive]。 |
| voucher_customer_guide_info.voucher_use_guide_info | 券引导详情，券核销引导 |
| use_guide_mode=OFFLINE_CODE：线下扫码核销，商家券将在支付宝卡包中展示券码 | |
| use_guide_mode=MINI_APP：小程序核销，商家券将在支付宝卡包中展示 去使用 按钮，引导用户跳转至商家小程序页面（mini_app_use_guide_info.mini_app_url 小程序链接，mini_app_use_guide_info.mini_app_service_codes 小程序服务） |
展示效果
第二步：上传券码
第三步：提交库存
activity_base_info.code_mode=MERCHANT_UPLOAD，本接口 voucher_quantity 值需要与导入码的总数量保持一致。券活动消息通知
第一步：POST方式接收券活动创建通知
消息示例
ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"CREATED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"12342425435232423","out_biz_no":"abscd123341"
}
&msg_method=alipay.marketing.activity.message.created&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2¬ify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==第二步：验签
第三步：反馈消息接收结果
fail 或其它值，表示消息获取失败，支付宝会根据 投递重试策略 重新发送消息到应用网关地址。| 响应值 | 描述 | 是否重试 |
|---|---|---|
| fail | 消息获取失败 | 重试 |
| success | 消息获取成功 | 不重试 |
券活动库存数量上限修改通知
消息示例
ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"APPENDED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"1619338271","out_biz_no":"20210420cy2112xzyx010"
}
&msg_method=alipay.marketing.activity.message.appended&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2¬ify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==推广商家券
引流转化
私域营销
支付有礼
领取商家券
商家券领取通知
user_id（支付宝用户 ID）、voucher_code（优惠券码）等信息给商家/服务商。消息示例
ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"RECEIVED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"1619338271","voucher_code":"voucher_code","receive_user_id":"2088xxxxx"
}
&msg_method=alipay.marketing.activity.message.received&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2¬ify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==使用商家券
接口时序图
核销商家券
biz_dt（外部优惠券的核销时间）为准。管理商家券活动
修改活动
| 参数名称 | 参数说明 |
|---|---|
| voucher_available_scope_info.voucher_available_geography_scope_info.available_geography_shop_info | 券可用范围，券可用地理位置,有两种门店模式，创建指定模式后，修改时不可切换模式 |
available_shop_ids 券可用门店列表 | |
available_geography_all_shop.exclude_shop_ids 券不可使用的门店列表 | |
| voucher_available_scope_modify_type | 修改可用范围类型 |
voucher_available_scope_modify_type=MODIFY_ALL则代表覆盖修改全量门店，门店不可减少，传入本参数后支付宝将在已有门店列表基础上去重、新增，未传本参 数则保持不变 | |
voucher_available_scope_modify_type=ADD，则代表追加修改，原有门店数量不变，增量追加 | |
voucher_available_scope_modify_type=REMOVE，则代表减少修改，原有门店数量增量减少 | |
| voucher_send_mode_info.voucher_send_rule_info | 券发放模式信息详情,券发放规则 |
voucher_send_rule_info.publish_end_time券发放结束时间，仅支持延期，不支持提前结束。 |
券活动修改通知
消息示例
ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"MODIFIED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"1619338271","out_biz_no":"abscd123341"
}
&msg_method=alipay.marketing.activity.message.modified&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2¬ify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==追加库存
activity_id（活动 ID）、券码及库存信息进行操作。接口时序图
voucher_quantity 表示追加以后的券的总数量。例如，活动本来发放 200 张券，现需追加 100 张，总共发放 300 张券，则 voucher_quantity 应传入 300。商家券活动预算追加通知
消息示例
ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"APPENDED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"1619338271","out_biz_no":"20210420cy2112xzyx010"
}
&msg_method=alipay.marketing.activity.message.appended&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2¬ify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==停止发券
FINISHED（已停止）。券活动停止消息通知
消息示例
ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"STOPPED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"12342425435232423","out_biz_no":"abscd123341"
}
&msg_method=alipay.marketing.activity.message.stopped&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2¬ify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==