# 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))、インラインのラインアイテムに代わり、すべてのアイテムが「価格」になります。 - 継続アイテムに商品画像をレンダリングする機能。 - 単一の項目の代わりに、再利用可能な商品と価格のカタログを作成します。 - *サブスクリプション* (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)および [1 回限りの支払い](https://docs.stripe.com/payments/checkout/taxes.md)に動的税率を適用します。 移行したくない場合、現在の組み込みを引き続き使用できますが、新機能はサポートされていません。既存の API コールの `plan` パラメーターで作成した新しいプランや継続価格を使用できます。 ## 商品と価格の概要 *価格* (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)は、サブスクリプション、*請求書* (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 とともに機能する Stripe 内の新しい中核的エンティティです。各価格は、1 つの*商品* (Products represent what your business sells—whether that's a good or a service)に関連付けられ、各商品には複数の価格を設定できます。物品やサービスレベルのそれぞれが商品に相当し、その商品の料金体系はそれぞれの価格によって示されます。 価格によって、基本価格、通貨が定義され、継続商品の場合には請求サイクルが定義されます。これにより、価格を変更したり追加したりする際に提供商品の詳細を変更する必要がなくなります。たとえば、「金」という商品に 10 USD/月、100 USD/年、9 EUR/月、90 EUR/年の価格を設定したり、20 USD と 15 EUR の価格でブルーの T シャツを設定したりできます。 ## 1 回限りの支払い 1 回限りの支払いの組み込みには以下の変更点があります。 - Checkout セッションの作成には、単発のラインアイテム (名前、金額、通貨の設定など) の代わりに、*商品* (Products represent what your business sells—whether that's a good or a service)と、通常は*価格* (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)できます。 | 価格なし | 価格あり | | ------------------------ | ----------------------------------------------------------------------------- | | `line_items.name` | `product.name` | | `line_items.description` | `product.description` | | `line_items.amount` | - `price.unit_amount` - `price_data.unit_amount` (Checkout セッション作成時に定義した場合) | | `line_items.currency` | - `price.currency` - `price_data.currency` (Checkout セッション作成時に定義した場合) | | `line_items.images` | `product.images` (提供されている最初の画像を表示) | ### インラインアイテムのサーバ側コード 以前は、単一の項目をインラインでのみ作成できました。価格を使用すると、引き続きアイテムをインラインで設定できますが、Checkout セッションを作成する際に [price_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data) を使用して価格を動的に定義することもできます。 `price_data` で Checkout セッションを作成する際には、[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 <>: \ -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" \ ``` ### 1 回限りの価格のサーバ側コード この新しいシステムでは、事前に[商品と価格のカタログを作成](https://docs.stripe.com/payments/accept-a-payment.md)できます。Checkout セッションを作成するたびに、金額、通貨、名前を定義する必要はありません。 商品と価格は、[Prices API](https://docs.stripe.com/api/prices.md) または[ダッシュボード](https://dashboard.stripe.com/products)で作成できます。Checkout Session を作成するには、価格 ID が必要です。次の例は、API を使用して商品と価格を作成する方法を示しています。 #### curl ```bash curl https://api.stripe.com/v1/products \ -u<>: \ -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<>: \ -d product="{{PRODUCT_ID}}" \ -d unit_amount=2000 \ -d currency=usd curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][quantity]"=1 \-d "line_items[0][price]"="{{PRICE_ID}}" \ -d mode=payment \ -d success_url="https://example.com/success" \ ``` ## サブスクリプション 継続支払いの組み込みには以下の変更点があります。 - アイテムはすべて、`subscription_data.items` ではなく、1 つの [line_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) フィールドに渡されます。 - [mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) は必須になりました。セッションに継続アイテムが含まれる場合は、`mode=subscription` を設定します。 クライアント側のコードは以前と同じです。継続価格が受け入れられる場所であればどこでも、既存のプランを使用できます。 ### プランを含むサーバ側コード 以下の例は、トライアル付きの Checkout セッションを作成する場合と、それと同じように価格を使用できる既存のプランを使用する場合の例を前後で示しています。プランは `subscription_data.items` ではなく `line_items` に渡されます。 #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \-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" \ ``` ### 設定手数料のある継続価格のサーバ側コード 1 回限りの設定手数料を伴う継続プランがある場合には、Checkout セッションを作成する前に、1 回限りの手数料を表す商品と価格を作成します。古い `line_items` フィールドが新しいシステムにどのようにマッピングされるかについては、[マッピングテーブル](https://docs.stripe.com/payments/checkout/migrating-prices.md#mapping-table-server-one-time)を参照してください。商品と価格は、[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 <>: \-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 オブジェクトは、`display_items`でアイテムをリストする代わりに、`line_items`を使用します。`line_items`フィールドは、`display_items`とは異なりデフォルトでは表示されませんが、Checkout Session を作成する際に[expand](https://docs.stripe.com/api/expanding_objects.md)を使用して含めることができます。 #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -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 Webhook を受信できます。次のように、新しい `line_items` エンドポイントでアイテムを取得できます。 #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \ -u <>: ``` 詳細については、[Checkout での注文のフルフィルメントの履行](https://docs.stripe.com/checkout/fulfillment.md) をご覧ください。