更新时间：2025-06-09 14:54:38配置项检测工具收藏订阅更新我的文档设置接入检测（即可查看检测结果）若有未通过的接入检测项，接口将无法调通去登录返回文档完成 后，商家/服务商可根据本文指引快速接入商家券 上传自定义券码模式。 说明：●商家券 产品支持自研商家/服务商通过 自研、代调用 模式调用 api 接入，各模式配置详情可查看 接入准备。●上传自定义券码模式 创建的商家券活动，在商家小程序进行 券活动运营（券活动领取引导）、发券、券运营（已领券核销引导），最终完成 核销。○支持通过 引流转化（原“日常推广-优惠券”） 推广到支付宝多个公域渠道等公域流量场景。○支持通过 私域营销 推广至商家小程序等私域流量场景。○支持通过 支付有礼 推广至私域流量场景。接入支付宝门店（可选）支付宝提供了 蚂蚁门店管理 产品，商家/服务商可通过接口创建支付宝门店获取门店 id（shop_id）并进行门店管理，后续可支持商家券在指定的门店进行核销。注意：●服务商需引导商家完成产品开通。●商家券场景下创建门店时，必须传入 business_address.longitude（经度）及 business_address.latitude（纬度）且使用 ，否则商家券无法在支付宝投放展示。产品接入核心模块订阅消息设置接收消息的应用网关地址商家/服务商 创建、修改及用户领取商家券等场景的消息，支付宝会通过 from 蚂蚁消息服务 向商家自研应用或第三方应用设置的 应用网关 地址，post 方式推送异步通知消息。若商家/服务商 网络环境比较复杂，如：通过统一网关间连互联网，推荐使用网络兼容性更好的标准 http(s) 协议进行对接。订阅消息接口商家/服务商 需根据 订阅消息 指引，为接入商家券的 自研应用 或 第三方应用 订阅如下消息接口。注意：●仅完成订阅后才会收到支付宝发送的对应异步通知消息。●商家/服务商 可通过消息通知中 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）。不同券类型优惠规则说明可查看 的使用说明。示例代码完整的 json 数据可复制 请求重要入参说明：参数名称参数说明out_biz_no商户创建券活动外部编号，确保唯一merchant_access_mode商户接入模式：商户自接入模式: self_mode服务商代接入模式: agency_modeactivity_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 相对时间，券可核销有效期以 中 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 小程序服务）特价券满减券折扣券展示效果alipay.marketing.activity.ordervoucher.create（创建商家券活动接口）对应参数展示效果如下图所示。第二步：上传券码创建商家券活动成功后，商家/服务商 可调用 将商家/服务商 系统自定义的优惠券码上传至支付宝。用户领券时，支付宝将从中随机选取券码给用户。注意：●本接口单次仅能导入 1000 个券码，支持循环或者并发导入券码，券码总量不能超过 500 万。●上传券码后，商家/服务商可通过，查询有效券码数量是否符合预期。●创建商家券活动成功后，以 为准（可查看上文 第一步：创建活动）才可上传券码。第三步：提交库存商家/服务商需调用 修改商家券活动券库存数量上限信息，提交并通过后商家券活动才会生效。注意：●若创建商家券时 activity_base_info.code_mode=merchant_upload，本接口 voucher_quantity 值需要与导入码的总数量保持一致。●本接口仅提交修改上限申请，结果需以为准，可查看下文 券活动消息通知 > 券活动库存数量上限修改通知。券活动消息通知第一步：post方式接收券活动创建通知商家/服务商发起的商家券创建完成后，支付宝将通过 发送活动创建成功时间等信息给商家/服务商。消息示例第二步：验签商家/服务商可使用支付宝 sdk 可根据 数据验签 指引，使用应用密钥信息验证异步通知消息来源是否为支付宝。第三步：反馈消息接收结果收到异步通知完成验签后，商家/服务商 需返回 success 这 7 个字符给支付宝，表示消息获取成功，支付宝就会停止发送异步通知。如果返回 fail 或其它值，表示消息获取失败，支付宝会根据 投递重试策略 重新发送消息到应用网关地址。说明：完成异步通知验签时，如果验签成功返回 success 这 7 个字符，验签失败返回 fail，重新接收异步进行处理。响应值描述是否重试fail消息获取失败重试success消息获取成功不重试券活动库存数量上限修改通知商家/服务商 发起的商家券库存数量上限修改完成后，支付宝将通过发送通过时间等信息给商家/服务商。消息示例注意：消息处理可查看 券活动消息通知。推广商家券引流转化商家/服务商接入并验收商家券能力后，可通过 引流转化 将商家券推广到支付宝多个公域渠道，用户在公域渠道领取商家券并自动放入卡包。私域营销商家/服务商接入并验收商家券能力后，可通过 私域营销 在商家小程序中进行营销推广。支付有礼商家/服务商接入并验收商家券能力后，可通过 支付有礼 将商家券推广至自己的收单账号收款的 支付成功页，用户在支付成功页可直接领取商家券并自动放入卡包。领取商家券本流程简单描述三种推广领取商家券的方式，商家可以根据自身需要选择其中一种或者三种都可以，具体的推广方式可以到 引流转化、 私域营销、支付有礼 接入指南查看。商家券领取通知用户在支付宝推广渠道领取商家券时，支付宝将通过发送领券用户 receive_user_id（receive_open_id）（支付宝用户 id）、voucher_code（优惠券码）等信息给商家/服务商。消息示例注意：消息处理可查看 券活动消息通知。使用商家券用户领取商家券后，支付宝将通过异步通知发送券码等信息给商家/服务商。商家/服务商可按如下指引调用接口，接入商家券核销等操作。接口时序图核销商家券用户使用商家券进行支付后，商家/服务商 需在自身系统核销优惠券，同时调用通知支付宝核销优惠券。接口将同步返回核销结果，支付宝同步切换用户卡包中优惠券状态为 已核销。注意：●优惠券核销时间以 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券发放结束时间，仅支持延期，不支持提前结束。券活动修改通知商家/服务商发起的商家券活动修改完成后，支付宝将通过 发送活动修改成功时间等信息给商家/服务商。消息示例注意：消息处理可查看 券活动消息通知。追加库存若商家/服务商创建商家券成功后还希望增加商家券码数量，可通过上文 上传券码（活动时上传自定义券码模式 必选）、提交库存 指引，传入需要追加库存的商家券 activity_id（活动 id）、券码及库存信息进行操作。接口时序图注意：●仅支持 创建成功（即接收到 通知）、未过期、未停止 的活动追加商家券发券上限，以此追加活动预算。●本接口 voucher_quantity 表示追加以后的券的总数量。例如，活动本来发放 200 张券，现需追加 100 张，总共发放 300 张券，则 voucher_quantity 应传入 300。●追加券码后，商家/服务商可通过，查询有效券码数量是否符合预期。●追加商家券码后还需通过 提交库存 完成追加预算操作。商家券活动预算追加通知商家/服务商发起的商家券库存数量上限修改完成后，支付宝将通过发送通过时间等信息给商家/服务商。消息示例注意：消息处理可查看 券活动消息通知。停止发券若商家券活动开始后，商家需提前停止活动。商家/服务商可调用 停止发券，支付宝将同步在各领券展示渠道隐藏对应券信息，并切换商家券活动状态为 finished（已停止）。注意：停止发券后用户不能再领券，已停止的活动不能重新激活。券活动停止消息通知商家/服务商发起的停止发券完成后，支付宝将通过 发送停止发券时间等信息给商家/服务商。消息示例注意：消息处理可查看 券活动消息通知。退回商家券若用户使用优惠券完成支付后发起退款操作，商家/服务商可调用在退款时进行退券，接口将同步返回退券结果。注意：●仅支持 已核销 的券进行退券操作。●如果优惠券过期后，发起退券操作，该接口返回成功，优惠券退回后仍不可用。●如果优惠券在支付宝卡包已删除，发起退券操作，该接口返回成功，优惠券在支付宝卡包仍然是删除状态。
