如何通过Stripe API正确处理一次性价格产品的购买？

核心问题原因 #

Stripe的stripe.subscriptions.create接口中，items数组仅支持**定期类型（recurring）**的定价ID，一次性定价（无recurring属性）直接放入会触发参数错误，这是平台的规则限制。

两种正确处理方式 #

1. 合并账单：创建订阅时添加一次性费用

这种方式可以让一次性定价的费用和订阅首期账单合并，用户只需完成一次支付，且完全关联到目标产品与客户，是最推荐的方案。

代码示例（以Python为例）：

stripe.Subscription.create(
  customer="cus_xxxxxx",
  # 放入定期定价的ID
  items=[{"price": "price_monthly_xxxxxx"}],
  # 通过add_invoice_items参数添加一次性定价
  add_invoice_items=[{"price": "price_one_time_xxxxxx"}]
)

执行后，系统会自动生成包含订阅首期费用+一次性费用的发票，客户支付后订阅正常生效，一次性费用也会关联到该客户及对应产品的账单记录中。

2. 单独收费：创建关联产品的支付意向

如果业务场景需要将一次性费用与订阅分开收取，也可以通过支付意向（PaymentIntent）实现，且完全可以关联产品信息，并非“不关联产品”：

• 方式一：通过metadata绑定产品信息

stripe.PaymentIntent.create(
  amount=100000, # 金额单位为分，对应1000美元
  currency="usd",
  customer="cus_xxxxxx",
  # 存入产品、定价ID等关联信息
  metadata={"product_id": "prod_xxxxxx", "price_id": "price_one_time_xxxxxx"}
)

• 方式二：通过发票关联产品（更规范的账单记录）

# 先创建包含一次性定价的发票
invoice = stripe.Invoice.create(
  customer="cus_xxxxxx",
  collection_method="charge_automatically",
  items=[{"price": "price_one_time_xxxxxx"}]
)
# 触发发票支付
stripe.Invoice.pay(invoice.id)

关于定价类型判断的补充 #

你可以提前通过stripe.Price.retrieve("price_xxxxxx")获取定价详情，判断price.recurring是否存在，再自动选择对应处理逻辑，但这不是必须的——如果你的业务逻辑中已明确哪些定价是一次性/定期，直接调用对应接口即可。

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