# 小程序会员

# 开发前准备

• 开通小程序会员功能：在 微信小店后台 - 用户运营 - 小程序会员 申请开通，当前仅限热招品牌商家。开通后功能处于「测试状态」，仅白名单用户可体验。关联限制：一个小店只能关联唯一一个小程序；一个小程序允许关联多个小店，每个关联都需要用户手动操作一次
• 配置测试白名单与页面路径：在 微信小店管理后台 设置测试白名单，并配置入会页路径（会员注册页面）和下单权益路径（会员权益选择页面），路径支持带参数格式，如 /path/to/page?with=query。配置时使用同一个 path 地址，用户跳到小程序后，商家根据用户身份引导去不同的页面
• 绑定开放平台账号：小店和小程序必须绑定到同一个微信开放平台账号，以便通过 UnionID 识别同一用户。
  • 为什么需要绑定：小程序会员体系内部使用小程序 openid 标识用户，但会员权益需要在小店侧场景中生效——下单时小店需识别用户是否为会员以展示优惠入口，售后时需通过订单中的小店 openid 关联到对应会员以回退权益。绑定同一开放平台后，小店 openid 和小程序 openid 可通过相同的 UnionID 互通，实现跨端用户关联
  • 获取 UnionID：开发者需自行通过 wx.login() 获取当前用户的 unionid
  • 自定义会员 ID：如果不希望使用 UnionID 区分用户，[API] 新增小程序会员信息 / adduserinfo 和 [API] 获取小程序会员信息 / getuserinfo 均支持 outer_userid 字段，用于填写商家自己体系的用户会员 ID
  • 参考文档：基本概念介绍、UnionID 机制说明
• 权限与凭证：
  • 小程序侧 API：使用小程序身份的 access_token 调用（如 [API] 新增小程序会员信息 / adduserinfo、[API] 获取小程序会员信息 / getuserinfo）
  • 小店侧 API：使用小店身份的 access_token 调用
  • 第三方服务商：需获得商家对应权限集的授权后使用 authorizer_access_token 调用——小程序侧 API 属于「小程序管理微信小店会员」（权限集 ID：185），小店侧 API 属于「微信小店会员」（权限集 ID：186）。详见 第三方调用说明。若接口返回 api unauthorized，请检查 access_token 来源与权限集授权是否正确
• 消息推送配置：需在 小程序后台 配置服务器地址接收事件通知，消息解密方式与小程序消息推送一致，需使用小程序的 EncodingAESKey 进行解密。本模块回调均为小程序侧回调，回调返回报文格式取决于小程序后台的消息推送配置（JSON 或 XML），需确保服务端返回格式与配置一致，若不一致将导致小店侧解析失败并报「网络异常，请重新选择」。详见 消息推送 | 微信开放文档
• 提交上线：测试通过后在 微信小店管理后台 提交上线申请，需小店管理员审批。上线前使用小程序体验版验证流程，上线后切换为小程序正式版

# 接入流程

# 阶段一：会员绑定流程

用户在微信小店触发会员关联时，小店向商家后台发起 [事件] 会员状态查询 / channels_ec_vip_user_info_get 回调，商家查询该用户是否已在品牌小程序入会并实时返回结果：

• 已入会（is_vip=true）：无需跳转小程序，直接在小店完成静默关联
• 未入会（is_vip=false）：跳转品牌小程序引导用户注册，完成后通过 [事件] 静默关联成功 / channels_ec_vip_user_auto_add 通知关联成功

路径一：用户已是小程序会员（静默关联）

路径二：用户未入会（跳转小程序注册）

注意事项：

• 不需要上传历史会员数据，会员关系需要用户手动授权关联，即使是历史会员也要手动操作
• 用户注销小程序会员时，调用 [API] 删除小程序会员信息 / deluserinfo 删除关联
• 小店会员等级与小程序会员完全一致，以小程序传回的为准

# 阶段二：下单优惠流程

会员用户在小店下单时，可享受品牌小程序提供的会员优惠。流程分为两步：用户进入下单页时，微信后台向品牌小程序发起回调获取默认权益；用户选择使用权益后，跳转小程序选权益并传回数据，微信后台再次回调确认优惠信息。

步骤一：获取默认权益

用户进入下单页时，微信后台向品牌小程序发起 [事件] 获取默认权益 / channels_ec_gen_order_info_init 回调，小程序需在 3 秒内实时返回默认权益信息，超时视为失败。

页面展示规则：

• 未关联会员的用户不会看到会员权益栏；已入会但当次下单没有会员权益或不使用会员权益时，会显示入口并展示「暂未使用会员权益」
• 付费会员、储值等逻辑可兼容，入会流程在小程序内完成，储值可作为会员优惠透传
• 暂无会员下单优惠时，可通过 微信小店后台 - 用户运营 - 小程序会员 - 会员配置中「下单权益」项选择「不使用下单权益」

步骤二：使用会员权益

用户点击使用权益后，跳转品牌小程序选择具体优惠。小程序选完后通过 wx.postMessageToReferrerPage 将权益信息传回小店，微信后台再发起 [事件] 使用会员权益 / channels_ec_order_use_vip_discount 回调确认，同样需 3 秒内实时返回。

小程序返回小店的代码示例：

wx.postMessageToReferrerPage({
  extraData: {
    vip_discounted_info: {
      vip_discounted_price: 100,  // 会员优惠总金额，单位分，等于各SKU优惠之和60加40
      product_infos: [            // 必填，每个商品的会员优惠信息
        {
          product_id: "12345",    // 商品ID
          sku_id: "23456",        // SKU ID
          vip_discounted_price: 60  // 该SKU的会员优惠金额，单位分
        },
        {
          product_id: "12346",
          sku_id: "23457",
          vip_discounted_price: 40
        }
      ],
      unuse_shop_discount: 0      // 是否叠加店铺优惠 0叠加 1不叠加
    }
  },
  success() {
    // Android在success回调中退出小程序
    wx.exitMiniProgram()
  }
})
// iOS若提示can only be invoked by user TAP gesture在同级调用
// wx.exitMiniProgram()

vip_discounted_info 参数说明：

优惠规则：

• 每个 SKU 会员优惠金额最低可优惠到 0.01 元（即 1 分），优惠金额以「分」为最小单位。最低总优惠金额 = 0.01 元 × SKU 种类数，例如购买 3 种商品最少优惠 0.03 元，同一 SKU 购买 10 件最少优惠 0.10 元
• 优惠后不能 0 元下单，最低需支付 0.01 元。例如 30 元商品，店铺优惠 10 元后为 20 元，会员优惠金额范围 0~19.99 元
• 会员优惠适用于达人带货

异常处理：

• 权益恢复：若品牌小程序内部已扣除权益，但微信后台侧因超时等原因判定失败，微信后台会主动推送 [事件] 取消使用权益 / channels_ec_order_unuse_vip_discount 通知取消，小程序需监听并恢复权益
• 数据匹配：取消使用权益回调中不包含商品信息，可通过 [事件] 使用会员权益 / channels_ec_order_use_vip_discount 回调中的商品信息进行匹配，或通过 order_session_id 与使用权益回调的数据关联
• 店铺优惠联动：店铺优惠发生变化时，小程序需重新生成会话 ID 并清空当前已选会员权益，避免权益信息错乱
• 会话参数获取：商家小程序通过 wx.getEnterOptionsSync() 即可拿到小店打开小程序时传递的 session_id 和 shop_appid，详见 wx.getEnterOptionsSync()
• 拆单说明：购物车跨店下单或群礼物下单会拆单，订单详情 API 和回调接口拿到的是拆单后的子单，unique_id 用于标识用户某次点击「提交订单」的操作，在跨店合并下单或群礼物下单场景下与订单 ID 不相等

# 阶段三：会员权益与成长数据更新

小程序会员的成长体系数据（积分、经验值等）由商家自行托管，下单时使用的优惠权益也需商家在自有体系内核销与回退。会员数据维护分为下单增长与售后回退两个方向，形成完整闭环：

下单增长：用户下单后，按订单金额累加积分、经验值等成长数据。

1. 监听 [事件] 订单下单 / channels_ec_order_new 等订单事件，实时感知用户下单
2. 收到事件后调用 [API] 获取订单详情 / getorder 获取订单完整数据
3. 通过订单中的 openid / unionid 匹配到对应会员账号
4. 根据订单金额、会员优惠等字段，按自有规则更新会员积分、经验值等成长数据

其中第 4 步用到的会员优惠相关字段，在 getorder 返回结果中的路径如下：

售后回退：用户退款或取消订单后，商家需在自有会员体系内回退两类数据，避免权益被重复消耗、刷单套利——一是回退下单时使用的会员优惠权益（这部分优惠由小程序侧发放，退款后需退回小程序会员体系，不一定对应实际金额），二是扣减此前为该订单累加的积分、经验值等成长数据。

1. 监听 [事件] 售后单更新通知 / channels_ec_aftersale_update 感知退款、退货
2. 通过售后单关联到原订单与对应会员账号
3. 回退会员优惠权益：售后回调中的 AfterSaleDetails.wxa_vip_discounted_price 字段记录了小程序会员已优惠金额（单位：分），据此将优惠权益退回小程序会员体系
4. 扣减成长数据：按退款金额扣减相应的积分、经验值等成长数据

# 阶段四：配券指南

小程序会员场景下，通过 [API] 创建优惠券 / createcoupon 和 [API] 更新优惠券内容 / updatecoupon 创建会员专属券，核心参数为 promote_info.promote_type：

promote_type 9/10（会员营销）与 promote_type 50/51（小程序会员）互斥，混用会导致券无法触达目标用户。所有优惠券类型（商品券 type 1-4、店铺券 type 101-104）均支持 promote_type 50/51。

开卡礼券自动发放：用户通过 [API] 新增小程序会员信息 / adduserinfo 入会时，传入 receive_register_coupon: true，系统将自动发放已生效的开卡礼券（promote_type=51）。需确保：商家已创建生效中的开卡礼券、用户在领取时间范围内且未超出限领张数。

# 接口全览

# API 接口

小程序侧（使用小程序 access_token）

小店侧（使用小店 access_token）

# 事件通知

本模块所有事件通知均为小程序侧回调，回调格式取决于小程序后台的消息推送配置（JSON 或 XML），需确保服务端解析格式与配置一致。

# 常见问题 FAQ

Q：权限集错误怎么办？ A：需要先授权对应权限集：小程序 API 属于「小程序管理微信小店会员」（权限集 ID：185），小店 API 属于「微信小店会员」（权限集 ID：186）。

Q：初次关联绑定的会员的权益如何发放？中间步骤有失败怎么办？ A：在小程序里发放给用户，用户在小店下单时即可使用。如果中间某个步骤失败了，在小程序内重新发起即可。

Q：如果小程序支持切换登录手机号，会员 ID 变动该怎么处理？ A：微信只认 openid 和 unionid，不以手机号判断用户。商家可自行决定是否切换会员账号，如需更新小店侧会员信息，调用 [API] 更新小程序会员信息 / updateuserinfo 接口。

Q：session_id 有效期是多少？ A：session_id 有效期为 10 分钟，超时后需重新获取。

Q：小店打开小程序，可以隐藏左上角主页按钮吗？ A：可以，小程序已有接口，详见 wx.hideHomeButton()。

Q：我已经使用了会员营销，如何迁移？

A：之前的会员数据可批量导出后融入已有小程序会员：

• 导出用户数据：调用会员营销 API，包括：
  • [API] 获取用户列表 / getuserlist
  • [API] 获取用户信息 / getuserinfo
  • [API] 获取用户积分 / getvipuserscore
  • [API] 获取用户积分流水 / getuserscoreflowrecord
• 替换权益：用户券权益、积分权益替换成小程序内的券、积分
• 关闭会员营销：在 微信小店后台 - 用户营销 - 会员营销，先关「向用户展示会员」，再关「关闭会员营销功能」。注意：商家关闭功能后，系统会清除商家配置和所有用户数据，请务必迁移数据后再关闭。
• 开通小程序会员：关闭会员营销后到小程序会员功能生效前存在空档期（gap），期间用户下单无法享受会员权益，建议尽快完成切换

文档变更日志（3条）

2026 年 06 月 24 日

补充 会员权益与成长数据更新、FAQ 等

2026 年 06 月 17 日

新增 小程序会员配券指南

2026 年 03 月 27 日

优化开发指南