Checkout 価格移行ガイド

Prices API により、顧客への請求方法に新機能と柔軟性が追加されます。この新しいシステムでは、次の機能が提供されます。

• Checkout アイテムのモデリングの統一性を向上。プラン、SKU、インラインのラインアイテムに代わり、すべてのアイテムが「価格」になります。
• 継続アイテムに商品画像をレンダリングする機能。
• 単一の項目の代わりに、再利用可能な商品と価格のカタログを作成します。
• サブスクリプションのインライン価格を作成します。
• サブスクリプションおよび 1 回限りの支払いに動的税率を適用します。

移行したくない場合、現在の組み込みを引き続き使用できますが、新機能はサポートされていません。既存の API コールの plan パラメーターで作成した新しいプランや継続価格を使用できます。

商品と価格の概要

価格は、サブスクリプション、請求書、Checkout とともに機能する Stripe 内の新しい中核的エンティティです。各価格は、1 つの商品に関連付けられ、各商品には複数の価格を設定できます。物品やサービスレベルのそれぞれが商品に相当し、その商品の料金体系はそれぞれの価格によって示されます。

価格によって、基本価格、通貨が定義され、継続商品の場合には請求サイクルが定義されます。これにより、価格を変更したり追加したりする際に提供商品の詳細を変更する必要がなくなります。たとえば、「金」という商品に 10 USD/月、100 USD/年、9 EUR/月、90 EUR/年の価格を設定したり、20 USD と 15 EUR の価格でブルーの T シャツを設定したりできます。

1 回限りの支払い

1 回限りの支払いの組み込みには以下の変更点があります。

• Checkout セッションの作成には、単発のラインアイテム (名前、金額、通貨の設定など) の代わりに、商品と、通常は価格の作成が必要です。
• mode が必須になりました。

クライアント側のコードは以前と同じです。

マッピングテーブル

line_items で各フィールドを定義する代わりに、Checkout は基本となる商品と価格のオブジェクトを使用して、名前、説明、金額、通貨、画像を判断します。API またはダッシュボードで商品および価格を作成できます。

インラインアイテムのサーバ側コード

以前は、単一の項目をインラインでのみ作成できました。価格を使用すると、引き続きアイテムをインラインで設定できますが、Checkout セッションを作成する際に price_data を使用して価格を動的に定義することもできます。

price_data で Checkout セッションを作成する際には、price_data.product で既存の商品 ID を参照するか、または price_data.product_data を使用して商品詳細を動的に定義します。次の例は、単一の項目の作成フローを示しています。

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

1 回限りの価格のサーバ側コード

この新しいシステムでは、事前に商品と価格のカタログを作成できます。Checkout セッションを作成するたびに、金額、通貨、名前を定義する必要はありません。

商品と価格は、Prices API またはダッシュボードで作成できます。Checkout セッションを作成するには、価格 ID が必要です。次の例は、API を使用して商品と価格を作成する方法を示しています。

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

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

サブスクリプション

継続支払いの組み込みには以下の変更点があります。

• アイテムはすべて、subscription_data.items ではなく、1 つの line_items フィールドに渡されます。
• mode は必須になりました。セッションに継続アイテムが含まれる場合は、mode=subscription を設定します。

クライアント側のコードは以前と同じです。継続価格が受け入れられる場所であればどこでも、既存のプランを使用できます。

プランを含むサーバ側コード

以下の例は、トライアル付きの Checkout セッションを作成する場合と、それと同じように価格を使用できる既存のプランを使用する場合の例を前後で示しています。プランは subscription_data.items ではなく line_items に渡されます。

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

設定手数料のある継続価格のサーバ側コード

1 回限りの設定手数料を伴う継続プランがある場合には、Checkout セッションを作成する前に、1 回限りの手数料を表す商品と価格を作成します。古い line_items フィールドが新しいシステムにどのようにマッピングされるかについては、マッピングテーブルを参照してください。商品と価格は、Prices API または Stripe ダッシュボードで作成できます。また、単一の項目をインラインで作成することもできます。以下の例では、既存の価格 ID を使用します。

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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 セッションオブジェクトは、display_items でアイテムをリストする代わりに、line_items を使用します。line_items フィールドは、display_items とは異なりデフォルトでは表示されませんが、Checkout セッションを作成する際に expand を使用して、以下のように含めることができます。

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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 Webhook を受信できます。次のように、新しい line_items エンドポイントでアイテムを取得できます。

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

詳細については、Checkout での注文のフルフィルメントの履行 をご覧ください。