# Checkout 价格迁移指南

了解如何升级您的集成来使用 Stripe Checkout 的价格功能。

[Prices API](https://docs.stripe.com/api/prices.md) 增加了新功能，提高了对客户收款的灵活性。此新的集成提供：

- 更一体化的 Checkout 项目模型——不再使用方案、*SKU* (SKUs (Stock Keeping Units) represent a specific Product variation, taking into account any combination of attributes and cost (for instance, size, color, currency, cost)) 和内联行项目，每个项目现在都是一个_price_（价格）。
- 能够为重复出现的项目呈现产品图片。
- 创建可重复使用的产品和价格目录，而非一次性行项目。
- 为*订阅* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis)创建内联定价。
- 为[订阅](https://docs.stripe.com/billing/taxes/collect-taxes.md?tax-calculation=tax-rates#adding-tax-rates-to-checkout)和[一次性付款](https://docs.stripe.com/payments/checkout/taxes.md)应用动态税率。

不想迁移？您可以继续使用当前的集成，但不支持新功能。您可以使用在现有 API 调用的 `plan` 参数中创建的任何新计划或定期价格。

## 产品和价格概览

*Prices* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions) 是 Stripe 内一个新的核心实体，可以与订阅、*账单* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice)及 Checkout 一起使用。每个价格都会绑定到一个*产品* (Products represent what your business sells—whether that's a good or a service)，而每个产品可以有多个价格。不同的实物商品或服务等级都应该用产品来表示。此产品的定价应该用价格来表示。

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

## 一次性付款

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

- 不再是临时的行项目（即设置名称、金额和货币），创建 Checkout Session 时要求创建 *product* (Products represent what your business sells—whether that's a good or a service)，而且通常要创建 *price* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions)。
- 现在要求使用 [mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode)。

客户端代码保持不变。

### 映射表

不需要再定义 `line_items` 的每个字段，Checkout 会用相关的产品和价格对象来确定名称、描述、金额、货币和图片。您可以用 API 或管理平台来[创建产品和价格](https://docs.stripe.com/payments/accept-a-payment.md)。

| 不使用 PRICES               | 使用 PRICES                                                                        |
| ------------------------ | -------------------------------------------------------------------------------- |
| `line_items.name`        | `product.name`                                                                   |
| `line_items.description` | `product.description`                                                            |
| `line_items.amount`      | - `price.unit_amount`
  - `price_data.unit_amount`（如果在创建 Checkout Session 时定义了它） |
| `line_items.currency`    | - `price.currency`
  - `price_data.unit_amount`（如果在创建 Checkout Session 时定义了它）    |
| `line_items.images`      | `product.images`（显示提供的第一张图片）                                                     |

### 内联项目的服务器端代码

以前，您可能只能创建一次性项目内联。有了 Prices，您可以继续配置您的项目内联，但在创建 Checkout Session 时，您也可以用 [price_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data) 动态定义您的价格。

用 `price_data` 创建 Checkout Session 时，通过 [price_data.product](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product) 引用现有产品的 ID，或用 [price_data.product_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product_data) 动态定义您的产品详情。以下示例演示一次性项目的创建流程。

#### curl

```bash
curl https://api.stripe.com/v1/checkout/sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -d "line_items[0][quantity]"=1 \-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" \
```

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

通过这种新的集成，您可以事先[创建一个产品和价格目录](https://docs.stripe.com/payments/accept-a-payment.md)，而无需每次创建 Checkout Session 时都定义金额、货币和名称。

您可以使用 [Prices API](https://docs.stripe.com/api/prices.md) 或通过[管理平台](https://dashboard.stripe.com/products)创建产品和价格。您需要价格 ID 来创建 Checkout Session。以下示例展示了如何通过 API 创建产品和价格：

#### curl

```bash
curl https://api.stripe.com/v1/products \
  -u<<YOUR_SECRET_KEY>>: \
  -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<<YOUR_SECRET_KEY>>: \
  -d product="{{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd

curl https://api.stripe.com/v1/checkout/sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -d "line_items[0][quantity]"=1 \-d "line_items[0][price]"="{{PRICE_ID}}" \
  -d mode=payment \
  -d success_url="https://example.com/success" \
```

## 订阅

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

- 所有项目都被传递到一个 [line_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) 字段，而非 `subscription_data.items`。
- 现在要求使用 [mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode)。如果会话中包含任何经常性项目，则设置 `mode=subscription`。

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

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

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

#### curl

```bash
curl https://api.stripe.com/v1/checkout/sessions \
  -u <<YOUR_SECRET_KEY>>: \-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" \
```

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

如果您有收取一次性设置费的经常性方案，则先创建一个表示一次性费用的产品和价格，然后再创建 Checkout Session。查看[映射表](https://docs.stripe.com/payments/checkout/migrating-prices.md#mapping-table-server-one-time)，了解 `line_items` 字段与新集成的映射关系。您既可以通过 [Prices API](https://docs.stripe.com/api/prices.md)，也可以通过 [Stripe 管理平台](https://dashboard.stripe.com/products)来创建产品和价格。您也可以[创建一次性项目内联](https://docs.stripe.com/payments/checkout/migrating-prices.md#server-side-code-for-inline-items)。下面的示例使用的是现有的价格 ID：

#### curl

```bash
curl https://api.stripe.com/v1/checkout/sessions \
  -u <<YOUR_SECRET_KEY>>: \-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" \
```

## 响应对象的变化

Checkout Session 对象使用 `line_items` 列出项目，不再使用 `display_items`。默认情况下，`line_items` 字段与 `display_items` 呈现方式不同，但您可以在创建 Checkout Session 时使用[扩展](https://docs.stripe.com/api/expanding_objects.md) 将其包含在内：

#### curl

```bash
curl https://api.stripe.com/v1/checkout/sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -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 "expand[]"="line_items"
```

## Webhook 的变化

由于 `line_items` 可以包含在内，`checkout.session.completed` *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 响应中将不再默认列出项目。响应对象变小以后，可以让您更快地接收 Checkout webhooks。您可以用新的 `line_items` 端点检索项目。

#### curl

```bash
curl https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \
  -u <<YOUR_SECRET_KEY>>:
```

更多详情，请查看[通过 Checkout 履行订单](https://docs.stripe.com/checkout/fulfillment.md)。