分页查询投放计划列表

更新时间:2026.03.16

分页查询投放计划列表

接口说明

支持商户:【品牌商户】

请求方式:【GET】/brand/marketing/delivery-plan/delivery-plans

请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

     【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看

接口限频:100/秒(品牌ID维度)

请求参数

Header  HTTP头参数

 Authorization  必填 string

请参考签名认证生成认证信息


 Accept  必填 string

请设置为application/json


 Wechatpay-Serial  必填 string

【微信支付公钥ID】  请传入brand_id对应的微信支付公钥ID,接口将会校验两者的关联关系,参考微信支付公钥产品简介及使用说明获取微信支付公钥ID和相关的介绍。以下两种场景将使用到微信支付公钥: 1、接收到接口的返回内容,需要使用微信支付公钥进行验签; 2、调用含有敏感信息参数(如姓名、身份证号码)的接口时,需要使用微信支付公钥加密敏感信息后再传输参数,加密指引请参考微信支付公钥加密敏感信息指引


query  查询参数

 page_size  选填   integer

【分页大小】 批量查询下每页的数量,最大不超过50。不填默认为10。


 offset  选填   integer

【offset】 该次请求资源的起始位置。第一页从0开始


 plan_state  选填   string

【投放计划状态】 不填写表示查询所有状态的投放计划,填写表示查询特定状态的投放计划。已终止、已过期是终态。

可选取值

  • CREATED:  创建成功

  • TERMINATED:  已终止

  • EXPIRED:  已过期

  • DELIVERING:  投放中

  • PAUSED:  已暂停


 audit_state  选填   string

【投放计划审核状态】 不填写表示查询所有审核状态的投放计划,填写则表示查询特定状态的投放计划。

可选取值

  • AUDIT_INITIAL:  待提审

  • AUDIT_PROCESSING:  审批中

  • AUDIT_PASSED:  审批通过

  • AUDIT_REJECTED:  审批拒绝


 plan_id  选填   string

【投放计划ID】 投放计划ID,如果填入该字段,则只返回该ID对应的投放计划

请求示例

curl
Java
Go

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/brand/marketing/delivery-plan/delivery-plans?page_size=5&offset=10&plan_state=CREATED&audit_state=AUDIT_INITIAL&plan_id=12000 \
3  -H "Authorization: WECHATPAY-BRAND-SHA256-RSA2048 brand_id=\"XXXX\",..." \
4  -H "Accept: application/json" \
5  -H "Wechatpay-Serial: PUB_KEY_ID_XXXX"  
6

应答参数
折叠全部参数

200 OK

 total_count  必填   integer

【资源总条数】 返回资源总条数


 plan_list  选填   array[object]

【投放计划列表】 投放计划列表,当有满足查询条件的投放计划时返回该字段

属性

 plan_id  必填   string(32)

【投放计划ID】 投放计划ID


 plan_name  必填   string(36)

【投放计划名称】 投放计划名称


 plan_state  必填   string

【投放计划状态】 投放计划状态,已终止、已过期是终态。

可选取值

  • CREATED:  创建成功

  • TERMINATED:  已终止

  • EXPIRED:  已过期

  • DELIVERING:  投放中

  • PAUSED:  已暂停


 delivery_start_time  必填   string

【投放开始时间】 投放开始时间,遵循 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秒。


 delivery_end_time  必填   string

【投放结束时间】 投放结束时间,遵循 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秒。


 product_coupon_id  必填   string(40)

【商品券ID】 商品券ID,通过请求创建商品券接口获得,具体可查看创建商品券


 usage_mode  必填   string

【使用模式】 商品券使用模式

可选取值

  • SINGLE:  单券,即用户只能使用一次,使用后券失效

  • PROGRESSIVE_BUNDLE:  多次优惠,由一组批次组成,每阶梯次序对应一个批次。用户按顺序使用,每次核销后发放下一张券,直到用完为止


 stock_id  选填   string(40)

【投放批次ID】 投放的商品券批次ID,通过请求创建商品券接口获得,具体可查看创建商品券 ,当且仅当 usage_mode 为 SINGLE 时必传。


 stock_bundle_id  选填   string

【投放批次组ID】 投放的批次组ID,通过请求创建商品券接口获得,具体可查看创建商品券 ,当且仅当 usage_mode 为 PROGRESSIVE_BUNDLE 时必填。


 recommend_word  选填   string(27)

【营销标签】 用于在优惠左上角展示的运营推荐语信息。自定义文案,不超过9个中文字符或18个英文字符。若创建时未设置则不返回。


 total_count  必填   integer

【投放总库存数量】 约定了投放计划的总投放库存。


 user_limit  必填   integer

【单用户限领】 约定了投放计划单用户维度的限领数量; 非必填,如创建时未填写,则修改时不支持填写。


 daily_limit  必填   integer

【单日限领】 用于约定投放计划单日可领取的最大数量,如创建时未填写,则修改时不支持填写。


 reuse_coupon_config  必填   boolean

【是否复用商品券和批次信息】 是:表示从商品券和批次获取信息自动填充plan_name、total_count、user_limit、daily_limit、delivery_start_time、delivery_end_time。当投放计划在投放中状态时,若商品券批次的库存发生变化,投放计划会自动更新最新库存。
注:
plan_name默认取投放商品券的name字段;
total_count默认取投放批次的max_count字段;
user_limit默认取投放批次的max_count_per_user字段;
daily_limit默认取投放批次的max_count_per_day字段;
delivery_start_time默认取商品券的available_begin_time字段;
delivery_end_time默认取批次的 available_end_time 字段并-1,若批次配置有 wait_days_after_receive和available_days信息,则delivery_end_time默认取值为 available_end_time - wait_days_after_receive - available_days -1。
否:表示自定义传入plan_name、total_count、user_limit、daily_limit、delivery_start_time、delivery_end_time,其中plan_name、total_count、delivery_start_time、delivery_end_time、user_limit、daily_limit必填


 brand_id  必填   string

【品牌ID】 品牌ID

应答示例

200 OK

1{
2  "total_count" : 1234,
3  "plan_list" : [
4    {
5      "plan_id" : "12000",
6      "plan_name" : "冬季优惠投放",
7      "plan_state" : "CREATED",
8      "delivery_start_time" : "2025-01-01T00:00:00+08:00",
9      "delivery_end_time" : "2025-01-01T00:00:00+08:00",
10      "product_coupon_id" : "1000000013",
11      "usage_mode" : "SINGLE",
12      "stock_id" : "123456789",
13      "stock_bundle_id" : "123456789",
14      "recommend_word" : "天天有惊喜",
15      "total_count" : 11000,
16      "user_limit" : 5,
17      "daily_limit" : 100,
18      "reuse_coupon_config" : false,
19      "brand_id" : "40016"
20    }
21  ]
22}
23

 

错误码

以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

 

元宝AI
反馈
目录
置顶