# 小程序连接小店

本文档面向自研商家和 ISV 服务商，覆盖小程序连接小店的完整接入流程，包括关联账号、小程序组件、定制商品、礼物营销和事件通知。

# 开发前准备

• 功能了解：开发前建议先阅读以下运营文档了解完整业务流程
  • 微信小店「小程序连接小店」功能指引
  • 微信小店「关联账号」使用指南：介绍视频号、公众号、企业微信、小程序等各渠道的关联能力与操作方法
• 权限与凭证：商家自研可直接调用，使用小店 access_token；第三方服务商需获得商家对权限集 ID：131的授权，使用 authorizer_access_token
• 消息推送配置：需配置消息推送回调 URL，本模块涉及的事件：[事件] 订单通知 / cooperation_shop_order。详见 消息通知（回调）说明

# 接入流程

小程序连接小店的能力依赖关联关系。完整接入分为以下环节：先建立小程序与小店的关联关系，再按需接入小程序组件、小程序 API、定制商品、礼物营销和事件通知。

# 关联关系建立

小程序与微信小店之间需要先建立关联关系才能使用连接能力。关联关系由小店侧发起邀请，小程序侧接受后生效（status=1）；解绑后 status=2。

# 小程序组件接入

关联关系建立后，小程序可以直接使用以下原生组件展示小店内容：

# 小程序 API 接入

# 定制商品接入

适用于个性化印刷、定制刻字、3D 打印等定制商品场景。用户在小程序内完成定制操作后先上传文件获取 media_id，将 media_id 作为参数传入 <store-product> 商品卡；用户点击商品卡跳转到小店下单页完成下单；商家收到订单后通过小店服务端获取文件下载链接，完成定制发货。

两个接口均须在服务端调用，不可在小程序前端直接调用。上传资料权限集 ID：180，获取文件下载链接权限集 ID：131。

# 礼物营销接入

礼物营销分为采购模式（开发者自采自发）和商家配置模式（商家提供礼物、开发者发放），两种模式仅在获取活动 ID 的方式上不同，之后的 API 调用和前端收礼流程完全一致。小游戏送礼物可参考 小游戏开放能力 - 微信礼物。

# 角色说明

# 步骤1：创建礼物活动

采购模式和商家配置模式的活动创建方式不同

采购模式

1. 在 小程序后台 - 支付与交易 - 微信小店 - 礼物活动
2. 在「已购买的礼物」分类下点击「去购买」
3. 通过微信扫码后跳转至选礼物页面
4. 选择礼物份数并完成付款（单次购买生成一个活动，单活动最多 500 件，可分多次购买）
5. 购买后可在「微信 - 我 - 小店与卡包」查看付款订单
6. 返回 小程序后台 - 支付与交易 - 微信小店 - 礼物活动 - 「已购买的礼物」页面，查看已支付的礼物活动，获得活动 ID

商家配置模式

1. 商家进入 微信小店后台 - 推荐运营 - 礼物运营
2. 点击「创建活动」，选择推广渠道「小程序」
3. 在发放账号中选择需要发放的小程序
4. 选择要发放的礼物商品和份数（仅支持小店在售商品）

# 步骤2：调用 API 发放礼物

拿到活动 ID 后，通过服务端 API 完成礼物分配：

之后按模式调用：

采购模式

1. 调用 [API] 查询小店礼物活动列表 / list_present_activity 获取已购买的礼物活动列表，拿到活动 ID activity_id
2. 调用 [API] 查询礼物活动详情 / get_activity 确认活动信息，得到 present_order_id（礼物单 ID）
3. 调用 [API] 查询礼物订单详情 / get_present_order 查询子单列表，拿到子单 order_id
4. 调用 [API] 指定礼物收礼者 / set_present_receiver 传入子单 order_id 和用户 openid 完成分配。一个用户只能指定一个 order_id，指定多个会报错，开发者需自行实现「挑选一个空的订单分配」逻辑，指定后不可更改。同一活动库存中同一用户只能发一件，如需给同一用户发多件需在购买时拆单。

商家配置模式

1. 调用 [API] 查询小店礼物活动列表 / list_present_activity 获取已授权的活动列表，拿到活动 ID activity_id
2. 调用 [API] 查询礼物活动详情 / get_activity 确认活动信息
3. 调用 [API] 创建并发送礼物 / create_present_order 传入活动 activity_id 和用户 openid 创建礼物单，返回 present_id

# 步骤3：前端拉起礼物组件

在小程序页面中引入 <store-gift> 组件（基础库 ≥ 3.8.10），传入步骤2返回的礼物订单 ID 和用户 openid：

<store-gift present-order-id="xxx" open-id="xxx" />

用户被指定为收礼者后，可通过以下方式领取礼物：

1. 在小程序内点击礼物卡片，显示「已抽中，待收下」，点击「收下礼物」填写收货地址
2. 或在微信「服务通知」中查看通知，点击「收下礼物」填写收货地址

# 步骤4：查询发货状态

通过 [API] 查询礼物订单详情 / get_present_order 查询礼物的领取状态和发货状态。

# 库存与发放规则

# 事件通知接入

配置消息推送后，当用户通过小程序进入小店下单成功，小店侧会向渠道小程序推送订单通知回调。

[事件] 订单通知 / cooperation_shop_order 推送至小程序侧配置的消息回调地址，存在两个 Event 值：

回调消息示例（解密后的明文 JSON）：

{
    "ToUserName": "gh_2defbb026678",
    "FromUserName": "OPENID",
    "CreateTime": 1706518830,
    "MsgType": "event",
    "Event": "cooperation_shop_order",
    "Data": {
        "order_id": "coiqBw3B****TdtdzIpQ",
        "shop_appid": "店铺appid"
    }
}

order_id 并非小店侧的订单 ID，仅供渠道小程序查询使用。

重试策略：0s / 0s / 10s / 1min / 5min / 30min / 60min / 60min / 60min，最多推送 10 次。

# 接口全览

# 第三方应用服务端接口

以下接口支持小程序、小游戏、微信小店、移动应用四种账号类型调用。

存在旧版接口 查询礼物订单列表（旧） 和 查询礼物订单详情（旧），推荐使用上方新版接口。

# 小店服务端接口

# 事件通知（推送至小程序侧）

# 小程序组件

# 小程序 API

# 常见问题 FAQ

Q：订单通知的 Event 有两个值，如何区分？ A：cooperation_shop_order 用于旧版关联账号，related_shop_order_submission 用于新版关联账号。两者消息结构相同，开发者需根据实际的关联关系类型处理对应的 Event 值。

Q：礼物 API 使用哪个 access_token 调用？ A：所有礼物接口均由第三方应用服务端调用，使用对应应用的 access_token，支持小程序、小游戏、微信小店、移动应用四种账号类型；上传资料（uploadec）仅小程序场景使用，由小程序服务端调用，使用小程序 access_token；获取文件下载链接（getdownloadurl）由小店服务端调用，使用小店 access_token。

Q：采购模式和商家配置模式如何选择？ A：采购模式适用于开发者自采自发的场景，开发者自行购买礼物后通过 API 分配给用户；商家配置模式适用于商家提供礼物、小程序负责发放的场景，商家在小店后台创建活动授权关联小程序，小程序通过 API 创建礼物订单发放。两种模式的 API 调用流程不同：采购模式通过查询活动详情获取已购买的礼物单后指定收礼者；商家配置模式通过创建礼物订单生成新的礼物单。

Q：采购模式中一个用户可以分配多个礼物吗？ A：不可以。一个用户只能指定一个 order_id，指定多个会报错。开发者需自行实现「挑选一个空的订单分配」逻辑。指定收礼者后不可更改。

Q：礼物活动创建后可以修改吗？ A：商家配置模式中，活动上线后内容（发放商品及件数等）不可修改。采购模式中，开发者购买的礼物在购买后 48 小时自动失效，请尽快发出。

Q：用户被指定为收礼者后多久内需要领取？ A：24 小时内未收下，礼物将自动失效。

文档变更日志（2条）

2026 年 06 月 23 日

补充 礼物营销 相关说明

2026 年 04 月 28 日

新增 小程序连接小店 开发指南