商户进件
特约商户进件
基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
支付即服务
点金计划
行业方案
平台收付通(商户进件)
平台收付通(普通支付)
平台收付通(合单支付)
平台收付通(分账)
平台收付通(补差)
平台收付通(退款)
平台收付通(余额查询)
平台收付通(商户提现)
平台收付通(注销申请)
平台收付通(注销后提现)
平台收付通(跨境付款)
平台收付通(下载账单)
智慧商圈
微信支付分停车服务
电子发票
营销工具
代金券
商家券
委托营销
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
分账
连锁品牌分账
风险合规
商户开户意愿确认
消费者投诉2.0
商户违规通知回调
其他能力
图片上传
视频上传
微信支付平台证书

查询商家券详情API

最新更新时间:2021.12.09 版本说明


商户可通过该接口查询已创建的商家券批次详情信息。

接口说明

适用对象: 服务商

请求URL:https://api.mch.weixin.qq.com/v3/marketing/busifavor/stocks/{stock_id}

请求方式:GET


path 指该参数为路径参数

query 指该参数需在请求URL传参

body 指该参数需在请求JSON传参


请求参数

参数名 变量 类型[长度限制] 必填 描述
批次号 stock_id string[1,20] path 微信为每个商家券批次分配的唯一ID
示例值:1212

请求示例


https://api.mch.weixin.qq.com/v3/marketing/busifavor/stocks/1212
    
{
JAVA示例代码
}
    

返回参数

参数名 变量 类型[长度限制] 必填 描述
商家券批次名称 stock_name string[1,21] 批次名称,字数上限为21个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:8月1日活动券
批次归属商户号 belong_merchant string[8,15] 批次归属于哪个商户。
示例值:10000022
批次备注 comment string[1,20] 仅配置商户可见,用于自定义信息。字数上限为20个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:活动使用
适用商品范围 goods_name string[1,15] 用来描述批次在哪些商品可用,会显示在微信卡包中。字数上限为15个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:xxx商品使用
批次类型 stock_type string[1,16] 批次类型
NORMAL:固定面额满减券批次
DISCOUNT:折扣券批次
EXCHANGE:换购券批次
示例值:NORMAL
+核销规则 coupon_use_rule object 券核销相关规则
参数名 变量 类型[长度限制] 必填 描述
+券可核销时间 coupon_available_time object 日期区间内可以使用优惠。
参数名 变量 类型[长度限制] 必填 描述
开始时间 available_begin_time string[1,32] 批次开始时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
注意:开始时间设置有效期最长为1年。
示例值:2015-05-20T13:29:35+08:00
结束时间 available_end_time string[1,32] 批次结束时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
注意:结束时间设置有效期最长为1年。
示例值:2015-05-20T13:29:35+08:00
生效后N天内有效 available_day_after_receive int 日期区间内,券生效后x天内有效。例如生效当天内有效填1,生效后2天内有效填2,以此类推。注意,用户在有效期开始前领取商家券,则从有效期第1天开始计算天数,用户在有效期内领取商家券,则从领取当天开始计算天数,无论用户何时领取商家券,商家券在活动有效期结束后均不可用。可配合wait_days_after_receive一同填写,也可单独填写。单独填写时,有效期内领券后立即生效,生效后x天内有效。
示例值:3
+ 固定周期有效时间段 available_week object 可以设置多个星期下的多个可用时间段,比如每周二10点到18点,用户自定义字段。
参数名 变量 类型[长度限制] 必填 描述
可用星期数 week_day array[int] 0代表周日,1代表周一,以此类推。
示例值:1, 2
+ 当天可用时间段 available_day_time array 可以填写多个时间段,最多不超过2个。
参数名 变量 类型[长度限制] 必填 描述
当天可用开始时间 begin_time int 当天可用开始时间,单位:秒,1代表当天0点0分1秒。
示例值:3600
当天可用结束时间 end_time int 当天可用结束时间,单位:秒,86399代表当天23点59分59秒。
示例值:86399
+ 无规律的有效时间段 irregulary_avaliable_time array 无规律的有效时间,多个无规律时间段,用户自定义字段。
参数名 变量 类型[长度限制] 必填 描述
开始时间 begin_time string[1,32] 开始时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35+08:00
结束时间 end_time string[1,32] 结束时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35+08:00
领取后N天开始生效 wait_days_after_receive int 日期区间内,用户领券后需等待x天开始生效。例如领券后当天开始生效则无需填写,领券后第2天开始生效填1,以此类推。用户在有效期开始前领取商家券,则从有效期第1天开始计算天数,用户在有效期内领取商家券,则从领取当天开始计算天数。无论用户何时领取商家券,商家券在活动有效期结束后均不可用。需配合available_day_after_receive一同填写,不可单独填写。
示例值:7
+固定面额满减券使用规则 fixed_normal_coupon object 三选一 stock_type为NORMAL时必填。
参数名 变量 类型[长度限制] 必填 描述
优惠金额 discount_amount int64 优惠金额,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:5
消费门槛 transaction_minimum int64 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
+折扣券使用规则 discount_coupon object stock_type为DISCOUNT时必填。
参数名 变量 类型[长度限制] 必填 描述
折扣比例 discount_percent int 折扣百分比,例如:86为八六折。
示例值:86
消费门槛 transaction_minimum int64 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
+换购券使用规则 exchange_coupon object stock_type为EXCHANGE时必填。
参数名 变量 类型[长度限制] 必填 描述
单品换购价 exchange_price int64 单品换购价,单位:分。
特殊规则:取值范围 0 ≤ value ≤ 10000000
示例值:100
消费门槛 transaction_minimum int64 消费门槛,单位:分。
特殊规则:取值范围 0 ≤ value ≤ 10000000
示例值:100
核销方式 use_method string[1,128] 枚举值:
OFF_LINE:线下滴码核销,点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS:线上小程序核销,点击券“立即使用”跳转至配置的商家小程序(需要添加小程序appid和path)。
PAYMENT_CODE:微信支付付款码核销,点击券“立即使用”跳转至微信支付钱包付款码。
SELF_CONSUME:用户自助核销,点击券“立即使用”跳转至用户自助操作核销界面(当前暂不支持用户自助核销)。
示例值:OFF_LINE
小程序appid mini_programs_appid string[1,32] 条件选填 核销方式为线上小程序核销才有效。
示例值:wx23232232323
小程序path mini_programs_path string[1,128] 条件选填 核销方式为线上小程序核销才有效。
示例值:/path/index/index
+发放规则 stock_send_rule object 券发放相关规则
参数名 变量 类型[长度限制] 必填 描述
批次总预算 max_amount int64 总预算金额,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 100000000000
示例值:100000
批次最大发放个数 max_coupons int 条件选填 当stock_type为DISCOUNT或EXCHANGE类型时,必须填写。
特殊规则:取值范围 1 ≤ value ≤ 1000000000
示例值:100
用户最大可领个数 max_coupons_per_user int 用户可领个数。
示例值:5
单天发放上限金额 max_amount_by_day int 单天发放上限金额,单位:分(stock_type为NORMAL时可传入此字段控制单天发放上限)。
特殊规则:取值范围 1 ≤ value ≤ 10000000000
示例值:1000
单天发放上限个数 max_coupons_by_day int 单天发放上限个数(stock_type为DISCOUNT或EXCHANGE时可传入此字段控制单天发放上限),每个用户最多100张券 。
特殊规则:取值范围 1 ≤ value ≤ 1000000000
示例值:100
是否开启自然人限制 natural_person_limit bool 不填默认否,枚举值:
true:是
false:否
注:自然人防刷即同证件号下的所有账户合并计算的限领次数(限领次数指的是参数字段“用户最大领取个数”填写的值)
示例值:false
可疑账号拦截 prevent_api_abuse bool 不填默认否,枚举值:
true:是
false:否
示例值:false
是否允许转赠 transferable bool 不填默认否,枚举值:
true:是
false:否
该字段暂未开放
示例值:false
是否允许分享链接 shareable bool 不填默认否,枚举值:
true:是
false:否
该字段暂未开放
示例值:false
+自定义入口 custom_entrance object 卡详情页面,可选择多种入口引导用户。
参数名 变量 类型[长度限制] 必填 描述
+小程序入口 mini_programs_info object

需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序,APPID、path、入口文案为必填,引导文案非必填。

appid要与归属商户号有M-A or M-m-suba关系。

参数名 变量 类型[长度限制] 必填 描述
商家小程序appid mini_programs_appid string[1,32] 商家小程序appid要与归属商户号有M-A or M-m-suba关系。
示例值:wx234545656765876
商家小程序path mini_programs_path string[1,128] 商家小程序path
示例值:/path/index/index
入口文案 entrance_words string[1,5] 入口文案,字数上限为5个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:欢迎选购
引导文案 guiding_words string[1,6] 小程序入口引导文案,用户自定义字段。字数上限为6个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:获取更多优惠
商户公众号appid appid string[1,32] 可配置商户公众号,从券详情可跳转至公众号,用户自定义字段。
注:若创建商家券接口未填写该参数,该参数默认返回微信支付的appid,用户点击进入微信支付公众号
示例值:wx324345hgfhfghfg
营销馆id hall_id string[1,64] 填写微信支付营销馆的馆id,用户自定义字段。 营销馆需在商户平台 创建。
示例值:233455656
可用门店id store_id string[1,64] 填写代金券可用门店id,用户自定义字段。
示例值:233554655
code展示模式 code_display_mode string[1,8] 枚举值:
NOT_SHOW:不展示code
BARCODE:一维码
QRCODE:二维码
示例值:BARCODE
+样式信息 display_pattern_info object 创建批次时的样式信息。
参数名 变量 类型[长度限制] 必填 描述
使用须知 description string[1,1000] 用于说明详细的活动规则,会展示在代金券详情页。
示例值:深圳南山区门店可用
商户logo merchant_logo_url string[1,128] 若券归属商户号有认证品牌,则系统将自动拉取对应品牌logo;若券归属商户号不在认证品牌下,需自定义上传logo,未上传时将展示兜底灰色logo样式,影响券详情页用户体验,请及时上传。
商户logo的URL地址, 可通过《图片上传API》获得图片URL地址。
1、商户logo大小需为120像素*120像素。
2、支持JPG/JPEG/PNG格式,且图片小于1M。
示例值:https://qpic.cn/xxx
商户名称 merchant_name string[1,16] 不支持商户自定义。若券归属商户号有认证品牌,系统将自动拉取认证品牌号下的品牌名称;若券归属商户号不在认证品牌下,则拉取本商户号的商户简称。展示上限12个字符。
示例值:微信支付
背景颜色 background_color string[1,15] 代金券的背景颜色,可设置10种颜色,色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。
示例值:Color020
券详情图片 coupon_image_url string[1,128] 券详情图片,1074像素(宽)*603像素(高),且图片大小不超过2M,支持JPG/PNG格式,可通过《图片上传API》获得图片URL地址。
示例值:https://qpic.cn/xxx
+ 视频号相关信息 finder_info object 视频号相关信息
参数名 变量 类型[长度限制] 必填 描述
视频号ID finder_id string[1,32] 关联视频号将展示在优惠券详情的顶部右侧,作为跳转去视频号的入口,请求参数请配置视频号ID,请前往视频号助手管理查看视频号ID
示例值:sph6Rngt2T4RlUf
视频号视频ID finder_video_id string[1,256] 券详情视频内容,支持配置关联视频号下的具体视频内容,请求参数请配置视频ID,请前往视频号助手管理后台复制具体视频ID
示例值:export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94
视频号封面图 finder_video_cover_image_url string[1,256] 截取的视频号图片将在券到期提醒消息、券详情中展示。
1.图片尺寸:1074像素(宽)*603像素(高),图片大小不超过2M,支持JPG/PNG格式。
2.仅支持通过《图片上传API》接口获取的图片URL地址。
示例值:https://wxpaylogo.qpic.cn/xxx
批次状态 stock_state string[1,128] 批次状态

  1. UNAUDIT:审核中
  2. RUNNING:运行中
  3. STOPED:已停止(暂未开放)
  4. PAUSED:暂停发放 (暂未开放)

示例值:RUNNING

券code模式 coupon_code_mode string[1,128] 枚举值:
WECHATPAY_MODE:系统分配券code。
MERCHANT_API:商户发放时接口指定券code。
MERCHANT_UPLOAD:商户上传自定义code,发券时系统随机选取上传的券code。
示例值:WECHATPAY_MODE
批次号 stock_id string[1,20] 微信为每个商家券批次分配的唯一ID。
示例值:1212
+券code数量 coupon_code_count object 当且仅当coupon_code_mode(券code模式)为MERCHANT_UPLOAD(商户上传自定义code)模式时,返回该字段,返回内容为商户上传code的数量信息。
参数名 变量 类型[长度限制] 必填 描述
该批次总共已上传的code总数 total_count uint64 该批次总共已上传的code总数。
示例值:100
该批次当前可用的code数 available_count uint64 该批次当前可用的code数。
注:该批次未发放的code数
示例值:50
+事件通知配置 notify_config object 事件回调通知商户的配置。
参数名 变量 类型[长度限制] 必填 描述
事件通知appid notify_appid string[1,64] 用于回调通知时,计算返回操作用户的openid(诸如领券用户),支持小程序or公众号的APPID;如该字段不填写,则回调通知中涉及到用户身份信息的openid与unionid都将为空。
示例值:wx23232232323
+批次发放情况 send_count_information object 批次发放情况
参数名 变量 类型[长度限制] 必填 描述
已发放券张数 total_send_num uint64 批次已发放的券数量,满减、折扣、换购类型会返回该字段
示例值:1
已发放券金额 total_send_amount uint64 批次已发放的预算金额,满减券类型会返回该字段
示例值:34
单天已发放券张数 today_send_num uint64 批次当天已发放的券数量,设置了单天发放上限的满减、折扣、换购类型返回该字段
示例值:1
单天已发放券金额 today_send_amount uint64 批次当天已发放的预算金额,设置了当天发放上限的满减券类型返回该字段
示例值:34

卡券背景颜色图

商家券详情信息样式图

返回示例


{
  "stock_name": "8月1日活动券",
  "belong_merchant": "10000022",
  "comment": "xxx店使用",
  "goods_name": "xxx商品使用",
  "stock_type": "NORMAL",
  "coupon_use_rule": {
    "coupon_available_time": {
      "available_begin_time": "2015-05-20T13:29:35+08:00",
      "available_end_time": "2015-05-20T13:29:35+08:00",
      "available_day_after_receive": 3,
      "available_week": {
        "week_day": [
          1,
          2
        ],
        "available_day_time": [
          {
            "begin_time": 3600,
            "end_time": 86399
          }
        ]
      },
      "irregulary_avaliable_time": [
        {
          "begin_time": "2015-05-20T13:29:35+08:00",
          "end_time": "2015-05-20T13:29:35+08:00"
        }
      ]
    },
    "fixed_normal_coupon": {
      "discount_amount": 5,
      "transaction_minimum": 100
    },
    "use_method": "OFF_LINE",
    "mini_programs_appid": "wx23232232323",
    "mini_programs_path": "/path/index/index"
  },
  "stock_send_rule": {
    "max_amount": 100000,
    "max_coupons": 100,
    "max_coupons_per_user": 5,
    "max_amount_by_day": 1000,
    "max_coupons_by_day": 100,
    "natural_person_limit": false,
    "prevent_api_abuse": false,
    "transferable": false,
    "shareable": false
  },
  "custom_entrance": {
    "mini_programs_info": {
      "mini_programs_appid": "wx234545656765876",
      "mini_programs_path": "/path/index/index",
      "entrance_words": "欢迎选购",
      "guiding_words": "获取更多优惠"
    },
    "appid": "wx324345hgfhfghfg",
    "hall_id": "233455656",
    "store_id": "233554655"
  },
  "display_pattern_info": {
    "description": "xxx门店可用",
    "merchant_logo_url": "https://xxx",
    "merchant_name": "微信支付",
    "background_color": "Color020",
    "coupon_image_url": "https://qpic.cn/xxx",
    "finder_info": {
          "finder_id": "sph6Rngt2T4RlUf",
          "finder_video_cover_image_url": "https://wxpaylogo.qpic.cn/xxx",
          "finder_video_id": "export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94"
        }
  },
  "stock_state": "RUNNING",
  "coupon_code_mode": "MERCHANT_UPLOAD",
  "stock_id": "1212",
  "coupon_code_count": {
    "total_count": 100,
    "available_count": 50
  }
}
                                

    http://2323weixin.qq.com
                                

错误码公共错误码

状态码 错误码 描述 解决方案
400 PARAM_ERROR 参数错误 查看具体错误信息,调整参数
400 SYSTEM_ERROR 系统错误 请使用相同参数稍后重新调用
400 RESOURCE_ALREADY_EXISTS 批次已存在 查看out_request_no字段是否重复使用
券已被其他订单核销 请通过查询券API确认券是否已被其他订单核销
404 RESOURCE_NOT_EXISTS 查询的资源不存在 请检查查询资源的对应id是否填写正确
403 NOAUTH 无权限 查看具体错误信息,确认是否有权限
400 APPID_MCHID_NOT_MATCH appid与请求方商户无关联关系 appid与请求方商户不匹配,请确认appid与请求方商户是否有关联关系
400 MCH_NOT_EXISTS 商户号不存在 请确认传入的商户号是否正确
404 USER_NOT_EXISTS openid不正确 请确认传入的openid是否正确
500 SYSTEM_ERROR 系统失败 多为网络超时引起,重试
429 FREQUENCY_LIMITED 频率限制 调用太频繁,请降低调用接口频率
403 RULELIMIT 券不在有效期 请确认券是否能在当前时间核销
400 INVALID_REQUEST 发券模式不合法 请更换支持预上传code的批次后重试
上传的自定义code已达上限 请更换一个新的批次后重试


技术咨询

文档反馈