如何让Stripe从订阅生成的Charge继承订阅的Metadata？

Stripe默认不会自动把订阅的Metadata传递给其生成的Charge，但我们有两种可靠的实现方式，根据你的需求场景选择即可：

方法1：通过Webhook主动同步Metadata #

这是最灵活可控的方案，适合需要自定义同步逻辑或者后续会更新订阅Metadata的场景：

• 先在Stripe后台启用charge.succeeded或invoice.paid事件的Webhook端点
• 当事件触发时，按以下步骤操作：
  1. 从事件对象里取出Charge的ID和关联的Invoice ID
  2. 通过Invoice ID拉取对应的订阅ID
  3. 获取该订阅的Metadata内容
  4. 调用Stripe API把订阅的Metadata同步到对应的Charge上

示例代码（Node.js）：

// 处理Stripe Webhook的端点
app.post('/stripe-webhook', async (req, res) => {
  const event = req.body;
  // 监听Charge成功支付的事件
  if (event.type === 'charge.succeeded') {
    const charge = event.data.object;
    // 订阅生成的Charge都会关联Invoice，跳过非订阅的Charge
    if (!charge.invoice) return res.sendStatus(200);
    
    // 拉取Invoice和对应的订阅信息
    const invoice = await stripe.invoices.retrieve(charge.invoice);
    const subscription = await stripe.subscriptions.retrieve(invoice.subscription);
    
    // 把订阅的Metadata同步到Charge
    await stripe.charges.update(charge.id, {
      metadata: subscription.metadata
    });
  }
  res.sendStatus(200);
});

方法2：创建订阅时配置自动传递 #

如果你不需要自定义逻辑，只想让固定的Metadata自动流向Charge，可以在创建订阅时同时配置订阅和发票的Metadata：

• 创建订阅时，除了给订阅本身设置metadata，还要在invoice_data字段里设置完全相同的Metadata
• 后续该订阅生成的每一张发票都会继承这个Metadata，而发票支付后生成的Charge会自动包含发票的Metadata

示例代码（Node.js）：

// 定义要传递的Metadata
const subscriptionMeta = {
  user_id: 'user_1001',
  subscription_plan: 'annual_pro'
};

// 创建订阅时同时配置订阅和发票的Metadata
const subscription = await stripe.subscriptions.create({
  customer: 'cus_XXXXXX',
  items: [{ price: 'price_XXXXXX' }],
  metadata: subscriptionMeta,
  invoice_data: {
    metadata: subscriptionMeta
  }
});

注意事项 #

• 方法2中，如果后续更新了订阅的Metadata，需要同步更新invoice_data.metadata，否则新生成的发票还是会沿用旧的Metadata
• Webhook方式虽然需要额外开发，但能确保即使订阅Metadata后续变更，新生成的Charge也能获取到最新内容
• 务必做好Webhook的签名验证，避免恶意请求篡改数据

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