查询商家券详情API

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


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

接口说明

适用对象:直连商户 服务商 渠道商

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

请求方式:GET

接口规则:https://wechatpay-api.gitbook.io/wechatpay-api-v3


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秒。
示例值: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秒。
示例值: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 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 折扣百分比,例如:88为八八折。
示例值:88
消费门槛 transaction_minimum int64 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
+换购券使用规则 exchange_coupon object stock_type为EXCHANGE时必填。
参数名 变量 类型[长度限制] 必填 描述
单品换购价 exchange_price int64 单品换购价,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
消费门槛 transaction_minimum int64 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ 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] 可配置商户公众号,从券详情可跳转至公众号,用户自定义字段。
示例值: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的URL地址, 可通过《图片上传API》获得图片URL地址。
1、商户logo大小需为120像素*120像素。
2、支持JPG/JPEG/PNG格式,且图片小于1M。
示例值:https://qpic.cn/xxx
商户名称 merchant_name string[1,16] 商户名称,字数上限为16个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:微信支付
背景颜色 background_color string[1,15] 代金券的背景颜色,可设置10种颜色,色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。
示例值:Color020
券详情图片 coupon_image_url string[1,128] 券详情图片,850像素*350像素,且图片大小不超过2M,支持JPG/PNG格式,可通过《图片上传API》获得图片URL地址。
示例值:https://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数。
示例值:50
+事件通知配置 notify_config object query事件回调通知商户的配置。
参数名 变量 类型[长度限制] 必填 描述
事件通知appid notify_appid string[1,64] 用于回调通知时,计算返回操作用户的openid(诸如领券用户),支持小程序or公众号的APPID;如该字段不填写,则回调通知中涉及到用户身份信息的openid与unionid都将为空。
示例值:wx23232232323
+批次发放情况 send_count_information object query批次发放情况
参数名 变量 类型[长度限制] 必填 描述
已发放券张数 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
    },
    "discount_coupon": {
      "discount_percent": 88,
      "transaction_minimum": 100
    },
    "exchange_coupon": {
      "exchange_price": 100,
      "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": "xxxxx",
    "coupon_image_url": "图片cdn地址"
  },
  "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已达上限 请更换一个新的批次后重试

版本说明

关闭
V1.6
2020年07月24日
1.新增code展示模式字段code_display_mode
V1.5
2020年04月21日
1.接口名称将“查询商家券批次详情”的接口名称改成“查询商家券详情”
V1.4
2020年03月20日
1.stock_name的字段长度改为24、merchant_name字段长度改为16、核销方式枚举值:“USER_SELF”改为“SELF_CONSUME”
V1.3
2020年01月10日
1. 新增事件通知配置(notify_config)、批次发放情况(send_count_information)字段
V1.2
2020年01月08日
1. 核销方式(use_method)新增枚举值PAYMENT_CODE、修改批次类型枚举值

技术咨询

反馈有奖