Checkout 价格迁移指南

Prices API 增加了新功能，提高了对客户收款的灵活性。此新的集成提供：

• 更一体化的 Checkout 项目模型——不再使用方案、SKU 和内联行项目，每个项目现在都是一个_price_（价格）。
• 能够为重复出现的项目呈现产品图片。
• 创建可重复使用的产品和价格目录，而非一次性行项目。
• 为订阅创建内联定价。
• 为订阅和一次性付款应用动态税率。

不想迁移？您可以继续使用当前的集成，但它不支持这些新功能。您可以在您现有的 API 调用的 plan 参数内使用您创建的任何新的方案或经常性价格。

产品和价格概览

Prices 是 Stripe 内一个新的核心实体，可以与订阅、账单及 Checkout 一起使用。每个价格都会绑定到一个产品，而每个产品可以有多个价格。不同的实物商品或服务等级都应该用产品来表示。此产品的定价应该用价格来表示。

Prices 定义了基准价格、货币以及计费周期（以定期购买的产品为例）。这样即可在不更改提供的商品或服务的情况下更改和添加价格。例如，您可能有个“黄金”产品，其价格为 10 美元/月、100 美元/年、9 欧元/月以及 90 欧元/年。或者，您可能有一款蓝色 T 恤，价格为 20 美元和 15 欧元。

一次性付款

一次性付款的集成有以下变化：

• 不再是临时的行项目（即设置名称、金额和货币），创建 Checkout Session 时要求创建 product，而且通常要创建 price。
• 现在要求使用 mode。

客户端代码保持不变。

映射表

不需要再定义 line_items 的每个字段，Checkout 会用相关的产品和价格对象来确定名称、描述、金额、货币和图片。您可以用 API 或管理平台来创建产品和价格。

内联项目的服务器端代码

以前，您可能只能创建一次性项目内联。有了 Prices，您可以继续配置您的项目内联，但在创建 Checkout Session 时，您也可以用 price_data 动态定义您的价格。

用 price_data 创建 Checkout Session 时，通过 price_data.product 引用现有产品的 ID，或用 price_data.product_data 动态定义您的产品详情。以下示例演示一次性项目的创建流程。

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][product_data][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][price_data][product_data][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][price_data][currency]"=usd \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

一次性价格的服务器端代码

通过这种新的集成，您可以事先创建一个产品和价格目录，而无需每次创建 Checkout Session 时都定义金额、货币和名称。

您既可以通过 Prices API，也可以通过管理平台来创建产品和价格。创建 Checkout Session 需要使用价格 ID。下例演示了如何通过 API 创建产品和价格。

curl https://api.stripe.com/v1/products \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d name=T-shirt \
  -d description="Comfortable cotton t-shirt" \
  -d "images[]"="https://example.com/t-shirt.png"

curl https://api.stripe.com/v1/prices \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d product="{{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

订阅

经常性付款的集成有以下变化：

• 所有项目都被传递到一个 line_items 字段，而非 subscription_data.items。
• 现在要求使用 mode。如果会话中包含任何经常性项目，则设置 mode=subscription。

客户端代码保持不变。在接受经常性价格时可以使用现有方案。

使用方案情况下的服务器端代码

这里是一个升级前后创建包含试用且使用现有方案（可以与 Price 互换使用）的 Checkout Session 的示例。该方案现已传递到 line_items 内，而非 subscription_data.items。

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "subscription_data[items][][plan]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d mode=subscription \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

有设置费的经常性价格的服务器端代码

如果您有收取一次性设置费的经常性方案，则先创建一个表示一次性费用的产品和价格，然后再创建 Checkout Session。查看映射表，了解 line_items 字段与新集成的映射关系。您既可以通过 Prices API，也可以通过 Stripe 管理平台来创建产品和价格。您也可以创建一次性项目内联。下面的示例使用的是现有的价格 ID：

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "subscription_data[items][][plan]"="{{PLAN_ID}}" \
  -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[1][price]"="{{ONE_TIME_PRICE_ID}}" \
  -d "line_items[1][quantity]"=1 \
  -d mode=subscription \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

响应对象的变化

Checkout Session 对象现在使用 line_items，而不再通过 display_items 列出项目。line_items 字段不会像 display_items 那样默认呈现，但是您可以在创建 Checkout Session 时用 expand 将它包含在内。

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method_types[]"="card" \
  -d "mode"="payment" \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "success_url"="https://example.com/success" \
  -d "cancel_url"="https://example.com/cancel" \
  -d "expand[]"="line_items"

Webhook 的变化

由于 line_items 可以包含在内，checkout.session.completed webhook 响应中将不再默认列出项目。响应对象变小以后，可以让您更快地接收 Checkout webhooks。您可以用新的 line_items 端点检索项目。

curl https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

更多详情，请查看通过 Checkout 履行订单。