Stripe Checkout会话获取line_items返回null问题排查（Next.js环境）

问题原因 #

Stripe Webhook 的默认事件 payload 不会返回嵌套的关联对象，line_items 属于 Checkout 会话的关联字段，默认不会包含在 checkout.session.completed 事件的返回数据中，因此直接读取会得到 null 值。 #

解决方法 #

推荐通过主动调用 Stripe API 查询指定会话的 line_items，该方式稳定性最高，不受 webhook 配置变更影响，仅需要修改 checkout.session.completed 事件分支的代码即可：

} else if (event.type === "checkout.session.completed") {
  const checkout_session = event.data.object as Stripe.Checkout.Session;
  console.log(`💳 Session id: ${checkout_session.id}`);
  console.log(`Customer email: ${checkout_session.customer_details?.email}`);
  // 新增代码：主动查询当前会话的line_items
  const lineItems = await stripe.checkout.sessions.listLineItems(
    checkout_session.id,
    {
      limit: 100, // 可按需调整单页拉取上限，最高支持100个商品
      expand: ['data.price.product'] // 需要读取商品自定义属性、下载链接等信息时添加该参数
    }
  );
  // lineItems.data即为订单商品列表，可直接用于后续拼接下载链接、发送邮件逻辑
  console.log(`Order products: `, lineItems.data);
  console.log('-----------------------------------------------------');
}

可选替代方案（不推荐） #

如果不想额外发起API请求，也可以在 Stripe 后台的 Webhook 配置页，找到对应 webhook 的「Include values」配置项，添加 checkout.session.line_items 字段，配置后 webhook payload 会直接携带 line_items 数据。但该方式依赖后台配置，容易出现多环境配置不一致导致的问题，优先推荐主动查询的方案。 #

注意事项 #

• 调用 listLineItems 时添加 expand: ['data.price.product'] 参数可以直接展开关联的商品对象，不需要再次调用商品查询接口获取附加信息。
• 如果单会话商品数量超过100，需要通过 starting_after 参数处理分页拉取所有商品。

内容的提问来源于stack exchange，提问作者Lehan Musthafa