# 小程序会员

开发前建议先阅读 [微信小店「小程序会员服务」配置指引](https://store.weixin.qq.com/chengzhang/webdoc/wiki/7639/4d802e40f8203c80/growth_center_manual_for_store/2) 了解完整业务流程。

## 开发前准备

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

## 接入流程

### 阶段一：会员绑定流程

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

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

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

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%%
flowchart LR
  A[用户点击会员入口] -->|触发回调| B
  B[事件 会员状态查询<br/>channels_ec_vip_user_info_get] -->|返回 is_vip=true| C
  C[静默关联完成]
  style A fill:#ffffff,stroke:#0ab8a6,color:#666666
  style C fill:#ffffff,stroke:#0ab8a6,color:#666666
```

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

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%%
flowchart LR
  A[用户点击会员入口] -->|触发回调| B
  B[事件 会员状态查询<br/>channels_ec_vip_user_info_get] -->|返回 is_vip=false| C
  C[跳转品牌小程序入会] --> D
  D[用户完成注册] --> E
  E[API 新增小程序会员信息<br/>adduserinfo] -->|关联成功通知| F
  F[事件 静默关联成功<br/>channels_ec_vip_user_auto_add] --> G
  G[静默关联完成]
  style A fill:#ffffff,stroke:#0ab8a6,color:#666666
  style C fill:#ffffff,stroke:#0ab8a6,color:#666666
  style D fill:#ffffff,stroke:#0ab8a6,color:#666666
  style G fill:#ffffff,stroke:#0ab8a6,color:#666666
```

注意事项：

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

### 阶段二：下单优惠流程

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

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%%
flowchart LR
  A[用户进入下单页] -->|触发回调| B
  B[事件 获取默认权益<br/>channels_ec_gen_order_info_init] -->|返回默认权益| C
  C[展示会员优惠选择] -->|用户点击使用权益| D
  D[跳转小程序选权益] -->|返回 vip_discounted_info| E
  E[事件 使用会员权益<br/>channels_ec_order_use_vip_discount] -->|验证通过| F
  F[下单成功]
  E -->|店铺优惠变化| G
  G[重新生成会话id] --> C
  style A fill:#ffffff,stroke:#0ab8a6,color:#666666
  style C fill:#ffffff,stroke:#0ab8a6,color:#666666
  style D fill:#ffffff,stroke:#0ab8a6,color:#666666
  style F fill:#ffffff,stroke:#0ab8a6,color:#666666
  style G fill:#ffffff,stroke:#0ab8a6,color:#666666
```

**步骤一：获取默认权益**

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

页面展示规则：

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

**步骤二：使用会员权益**

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

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

```javascript
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` 参数说明：

| 字段 | 类型 | 必填 | 说明 |
|------|------|-----|------|
| `vip_discounted_price` | number | 是 | 会员优惠总金额，单位：分 |
| `product_infos` | array | 是 | 每个商品的会员优惠信息，不传或传空数组会导致下单失败 |
| `product_infos[].product_id` | string | 是 | 商品 ID |
| `product_infos[].sku_id` | string | 是 | SKU ID |
| `product_infos[].vip_discounted_price` | number | 是 | 该 SKU 的会员优惠金额，单位：分。各 SKU 金额之和必须等于外层 `vip_discounted_price` |
| `unuse_shop_discount` | number | 是 | 是否叠加店铺优惠。0=叠加，1=不叠加。当前无小程序优惠时应传 0 且 `vip_discounted_price: 0`，不能传 1 且金额为 0，否则会直接抹掉店铺券 |

**优惠规则：**

- 每个 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](/doc/store/shop/notify/wxa_callback/channels_ec_order_unuse_vip_discount) 通知取消，小程序需监听并恢复权益
- **数据匹配**：取消使用权益回调中不包含商品信息，可通过 [事件] [使用会员权益 / channels_ec_order_use_vip_discount](/doc/store/shop/notify/wxa_callback/channels_ec_order_use_vip_discount) 回调中的商品信息进行匹配，或通过 `order_session_id` 与使用权益回调的数据关联
- **店铺优惠联动**：店铺优惠发生变化时，小程序需重新生成会话 ID 并清空当前已选会员权益，避免权益信息错乱
- **会话参数获取**：商家小程序通过 `wx.getEnterOptionsSync()` 即可拿到小店打开小程序时传递的 `session_id` 和 `shop_appid`，详见 [wx.getEnterOptionsSync()](/miniprogram/dev/api/base/app/life-cycle/wx.getEnterOptionsSync.md)
- **拆单说明**：购物车跨店下单或群礼物下单会拆单，订单详情 API 和回调接口拿到的是拆单后的子单，`unique_id` 用于标识用户某次点击「提交订单」的操作，在跨店合并下单或群礼物下单场景下与订单 ID 不相等

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

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

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

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

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

| 字段路径 | 说明 |
|----------|------|
| `order_detail.price_info.vip_discounted_price` | 订单维度会员优惠总金额（单位：分） |
| `order_detail.product_infos[].vip_discounted_price` | 商品维度会员优惠金额（单位：分） |
| `order_detail.ext_info.vip_order_session_id` | 会员权益 session_id，用于关联下单权益与订单 |

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

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

### 阶段四：配券指南

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

| promote_type | 含义 | 适用场景 |
|-------------|------|----------|
| 50 | 小程序会员券 | 小程序会员专属券 |
| 51 | 小程序会员开卡礼券 | 入会时自动领取 |

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

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

## 接口全览

### API 接口

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

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|----------|
| [新增小程序会员信息](/doc/store/shop/API/wxamember/wxa/api_v3_wxa_adduserinfo) / adduserinfo | `POST /wxa/vip/user/info/add` | 用户关联入会时设置会员信息 |
| [更新小程序会员信息](/doc/store/shop/API/wxamember/wxa/api_v3_wxa_updateuserinfo) / updateuserinfo | `POST /wxa/vip/user/info/update` | 同步会员信息更新（如等级变更） |
| [获取小程序会员信息](/doc/store/shop/API/wxamember/wxa/api_v3_wxa_getuserinfo) / getuserinfo | `POST /wxa/vip/user/info/get` | 获取小程序的会员信息 |
| [获取小程序会员列表](/doc/store/shop/API/wxamember/wxa/api_v3_wxa_getuserlist) / getuserlist | `POST /wxa/vip/user/list/get` | 获取小程序的会员列表 |
| [删除小程序会员信息](/doc/store/shop/API/wxamember/wxa/api_v3_wxa_deluserinfo) / deluserinfo | `POST /wxa/vip/user/info/delete` | 删除小程序在关联小店的会员信息 |
| [获取小程序已关联小店列表](/doc/store/shop/API/wxamember/wxa/api_v3_wxa_getshoplist) / getshoplist | `POST /wxa/vip/shop/list/get` | 获取小程序已关联的小店列表 |

**小店侧（使用小店 access_token）**

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|----------|
| [小店获取关联小程序信息](/doc/store/shop/API/wxamember/shop/api_v3_getwxainfo) / getwxainfo | `POST /channels/ec/vip/v3/wxa/info/get` | 获取关联的小程序信息 |
| [创建优惠券](/doc/store/shop/API/coupon/api_createcoupon) / createcoupon | `POST /channels/ec/coupon/create` | 创建优惠券，设置 promote_type 指定推广类型 |
| [更新优惠券内容](/doc/store/shop/API/coupon/api_updatecoupon) / updatecoupon | `POST /channels/ec/coupon/update` | 更新优惠券内容，可修改 promote_type |

### 事件通知

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

| 中文名 / 英文名 | 事件标识 | 功能说明 |
|----------------|---------|----------|
| [会员状态查询](/doc/store/shop/notify/wxa_callback/channels_ec_vip_user_info_get) / channels_ec_vip_user_info_get | `Event: channels_ec_vip_user_info_get` | 静默关联时查询用户是否已入会，需实时返回 |
| [静默关联成功](/doc/store/shop/notify/wxa_callback/channels_ec_vip_user_auto_add) / channels_ec_vip_user_auto_add | `Event: channels_ec_vip_user_auto_add` | 静默关联成功通知 |
| [获取默认权益](/doc/store/shop/notify/wxa_callback/channels_ec_gen_order_info_init) / channels_ec_gen_order_info_init | `Event: channels_ec_gen_order_info_init` | 用户进入下单页时获取默认会员优惠，需实时返回（超时 3 秒） |
| [使用会员权益](/doc/store/shop/notify/wxa_callback/channels_ec_order_use_vip_discount) / channels_ec_order_use_vip_discount | `Event: channels_ec_order_use_vip_discount` | 用户下单使用会员权益时确认优惠，需实时返回（超时 3 秒） |
| [取消使用权益](/doc/store/shop/notify/wxa_callback/channels_ec_order_unuse_vip_discount) / channels_ec_order_unuse_vip_discount | `Event: channels_ec_order_unuse_vip_discount` | 用户取消使用会员权益或超时兜底通知 |

## 常见问题 FAQ

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

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

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

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

**Q：小店打开小程序，可以隐藏左上角主页按钮吗？**
A：可以，小程序已有接口，详见 [wx.hideHomeButton()](/miniprogram/dev/api/ui/navigation-bar/wx.hideHomeButton.md)。

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

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

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

![](https://res8.wxqcloud.qq.com.cn/wxdoc/56617deb-b17d-4cf1-bccd-71d2c41ccc76.svg)文档变更日志（3条）
2026 年 06 月 24 日补充 会员权益与成长数据更新、FAQ 等
2026 年 06 月 17 日新增 小程序会员配券指南
2026 年 03 月 27 日优化开发指南