# 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))、インライン項目の代わりに、すべての項目が価格になります。 - 継続アイテムに商品画像をレンダリングする機能。 - 1 回限りの項目ではなく、再利用可能な商品と価格のカタログを作成できる機能。 - *サブスク* (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)から作成できます。[1 回限りの項目をインラインで作成](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) をご覧ください。