Stripe Webhook事件中元数据及名称字段为空问题咨询

核心原因分析 #

• 发票行项目的字段快照逻辑：发票的line_item是关联Price/Product/SubscriptionItem生成的计费快照，仅保留核心计费数据，自定义元数据、Price昵称这类字段不会默认同步到line_item对象中。
• Webhook事件的默认载荷限制：invoice.payment_succeeded事件返回的invoice对象默认不包含line_item关联的完整Price/Product详情，因此无法直接看到已设置的metadata和nickname。

解决方案 #

1. 通过扩展字段获取关联对象详情 #

无论是创建Webhook端点还是主动查询发票API，都可以通过expand参数让Stripe返回line_item关联的price对象，进而获取Price的nickname和关联Product的metadata：

# 示例：创建Webhook时指定扩展字段（Python SDK）
stripe.WebhookEndpoint.create(
  url="https://your-webhook-url.com",
  enabled_events=["invoice.payment_succeeded"],
  expand=["invoice.line_items.data.price"]
)

# 示例：API查询发票时扩展字段
curl https://api.stripe.com/v1/invoices/in_123 \
  -u sk_test_your_key: \
  -d expand[]=line_items.data.price.product

2. 显式设置SubscriptionItem的元数据 #

如果需要元数据直接出现在line_item中，需在创建SubscriptionItem时显式配置metadata，而非仅设置Product/Price的metadata：

# 示例：创建SubscriptionItem时绑定元数据
stripe.SubscriptionItem.create(
  subscription="sub_123",
  price="price_123",
  metadata={"product_name": "Gold Account", "billing_cycle": "monthly"}
)

配置后生成的发票line_item会直接携带该元数据，在Webhook事件和API查询中均可直接读取。

3. 通过订阅ID关联查询完整信息 #

invoice.payment_succeeded事件的invoice对象包含subscription字段（订阅ID），可通过该ID查询订阅详情，进而获取关联Price/Product的所有字段：

# 示例：通过订阅ID获取关联对象详情
subscription = stripe.Subscription.retrieve("sub_123", expand=["items.data.price.product"])
price_nickname = subscription.items.data[0].price.nickname
product_metadata = subscription.items.data[0].price.product.metadata

关键注意事项 #

• Stripe控制台展示的是完整的Price/Product对象，但API和Webhook默认返回精简版数据，必须通过expand参数触发关联对象的详情返回。
• SubscriptionItem的元数据会直接继承到发票line_item，而Product/Price的元数据需通过扩展字段查询关联对象才能获取。

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