如何为Stripe的invoice.payment_succeeded Webhook添加元数据？

你当前的问题是：在创建Stripe订阅Checkout Session时，已经给Session添加了userId元数据，checkout.session.completed事件能正常获取到，但后续的invoice.payment_succeeded事件里元数据为空。这是因为Checkout Session的元数据不会自动同步到生成的Subscription和对应的Invoice，需要显式配置传递逻辑。

解决方案：通过subscription_data.metadata传递元数据 #

在创建Checkout Session时，新增subscription_data字段，并在其中定义要传递到订阅的元数据。这样后续该订阅生成的所有Invoice都会继承这些元数据，invoice.payment_succeeded事件就能拿到对应的userId了。

修改后的Checkout Session创建代码如下：

export const createCheckoutSessionForSubscription = async (req, res, next) => {
  console.log(req.body, 'req.body in stripe subscription');

  const prices = await Stripe.prices.list({
    lookup_keys: [req.body.lookup_key],
    expand: ['data.product'],
  });

  const session = await Stripe.checkout.sessions.create({
    // 可选：保留Session自身的元数据（仅用于checkout.session.completed事件）
    metadata:{
      userId: req.body.userId,
    },
    // 关键：通过subscription_data将元数据传递到订阅及后续发票
    subscription_data: {
      metadata: {
        userId: req.body.userId
      }
    },
    billing_address_collection: 'auto',
    line_items: [
      {
        price: prices.data[0].id,
        quantity: 1,
      },
    ],
    mode: 'subscription',
    success_url: `${YOUR_DOMAIN}/productDisplay/?success=true&session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${YOUR_DOMAIN}?canceled=true`,
  });

  res.redirect(303, session.url);
}

原理说明 #

• 当你以订阅模式创建Checkout Session时，Stripe会自动生成对应的Subscription资源。
• subscription_data字段用于配置该Subscription的属性，其中的metadata会被绑定到Subscription上。
• 后续该Subscription生成的所有Invoice都会继承Subscription的元数据，因此invoice.payment_succeeded事件中的Invoice对象会包含你设置的userId。

验证方法 #

完成代码修改后，创建新的订阅订单，在Stripe后台查看对应的Subscription详情，确认metadata已存在；待后续生成Invoice并触发invoice.payment_succeeded事件时，即可在Webhook中获取到userId元数据。

内容的提问来源于stack exchange，提问作者Alen Aju