コンテンツにスキップ
アカウント作成/サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成サインイン
概要構築済みのシステムをアップグレード
オンライン決済
概要ユースケースを見つけるManaged Payments を使用する
Elements を使用したカスタム統合の構築
対面決済
決済手段
決済シナリオ
決済以外の機能

項目を動的に更新する

決済中に価格設定とカートの内容を変更する方法をご紹介します。

プライベートプレビュー

動的更新はプライベートプレビューです。決済フローの動的更新へのアクセスをリクエストしてください。

Checkout Session (セッション) に含まれる項目を動的に追加、削除、更新する方法をご紹介します。

ご利用事例

このガイドでは、項目を更新してサブスクリプションをアップセルする方法を示しますが、以下を行うこともできます。

  • 在庫の確認:在庫チェックを実行し、顧客がアイテムの数量を変更しようとしたときに保留します。
  • 新しい商品を追加する:注文合計額が一定の金額を超えている場合に、補完商品を追加します。
  • 配送料金を更新する:注文合計額が変更された場合は、このガイドの購入時に配送オプションをカスタマイズするで説明されている方法を組み合わせて、配送料金を更新します。
  • 税率を更新する:Stripe Tax を使用していない場合は、入力された配送先住所に基づいて項目の税率を動的に更新できます。

Payment Intents API

Payment Intents API を使用する場合は、項目の更新を手動でトラッキングして決済金額を変更するか、金額を調整した新しい PaymentIntent を作成する必要があります。

SDK を設定する
サーバー側

Stripe の公式ライブラリを使用して、アプリケーションから Stripe API にアクセスします。

Command Line
Ruby
Python
PHP
Node.js
.NET
Go
Java
No results
gem install stripe -v 15.1.0-beta.2

サーバー SDK を更新する
サーバー側

このベータを使用するには、まず SDK を更新して、checkout_server_update_beta=v1 ベータ版ヘッダーを使用します。

Ruby
Python
PHP
Node
.NET
Go
Java
No results
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

Stripe.api_version = '2025-03-31.basil; checkout_server_update_beta=v1;'

Checkout Session の更新権限を設定する
サーバー側

Checkout Session を作成する際に、permissions.update_line_items=server_only オプションを渡し、クライアント側の更新を無効にし、サーバーから updateLineItemQuantity などの項目を更新できるようにします。

Command Line
cURL
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-03-31.basil; checkout_server_update_beta=v1;" \
  -d ui_mode=custom \
  -d "permissions[update_line_items]"=server_only \
  -d "line_items[0][price]"=
"{{PRICE_ID}}"
 \
  -d "line_items[0][quantity]"=1 \
  -d mode=subscription \
  --data-urlencode return_url="https://example.com/return"

項目を動的に更新する
サーバー側

サーバーでエンドポイントを作成し、Checkout Session の項目を更新します。これは、後のステップでフロントエンドから呼び出します。

セキュリティのヒント

クライアント側のコードは、ユーザーによって制御された環境で実行されます。悪意のあるユーザーは、クライアント側の検証を迂回し、リクエストを傍受して変更したり、サーバーへの新しいリクエストを作成したりすることができます。

エンドポイントを作成する際には、次のことを推奨します。

  • 汎用的にするのではなく、特定の顧客とのやり取りのためにエンドポイントを作成します。たとえば、一般的な「更新」アクションの代わりに「クロスセル項目を追加」します。特定のエンドポイントは、検証ロジックの作成と維持に役立ちます。
  • クライアントからエンドポイントに セッションデータ を直接渡さないでください。悪意のあるクライアントはリクエストデータを変更し、Checkout Session の状態を判別するための信頼できないソースにする可能性があります。代わりに、セッション ID をサーバーに渡して、それを使用して Stripe API からデータを安全に取得してください。
Ruby
Python
PHP
Node
.NET
Go
Java
No results
require 'sinatra'
require 'json'
require 'stripe'

set :port, 4242

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

Stripe.api_version = '2025-03-31.basil; checkout_server_update_beta=v1;'

MONTHLY_PRICE_ID = '{{MONTHLY_PRICE}}'
YEARLY_PRICE_ID = '{{YEARLY_PRICE}}'

post '/change-subscription-interval' do
  content_type :json
  request.body.rewind
  request_data = JSON.parse(request.body.read)

  checkout_session_id = request_data['checkout_session_id']
  interval = request_data['interval']

  if checkout_session_id.nil? || !['yearly', 'monthly'].include?(interval)
    status 400
    return {
      type: 'error',
      message: 'We couldn't process your request. Please try again later.'
    }.to_json
  end

  begin
    # 1. Create the new line items for the Checkout Session.
    new_price = interval == 'yearly' ? YEARLY_PRICE_ID : MONTHLY_PRICE_ID
    line_items = [{
      price: new_price,
      quantity: 1,
    }]

    # 2. Update the Checkout Session with the new line items.
    Stripe::Checkout::Session.update(checkout_session_id, {
      line_items: line_items,
    })

    # 3. Return a success response.
    { type: 'success' }.to_json
  rescue Stripe::StripeError
    # Handle Stripe errors with a generic error message
    status 400
    {
      type: 'error',
      message: 'We couldn't process your request. Please try again later.'
    }.to_json
  rescue StandardError
    # Handle unexpected errors
    status 500
    {
      type: 'error',
      message: 'Something went wrong on our end. Please try again later.'
    }.to_json
  end
end

項目を更新するときは、項目の配列全体を再送信する必要があります。

  • 既存の項目を維持するには、その id を指定します。
  • 既存の項目を更新するには、更新するフィールドの新しい値とともにその id を指定します。
  • 新しい項目を追加するには、id なしで price と quantity を指定します。
  • 既存の項目を削除するには、再送信された配列から項目の ID を省略します。
  • 項目の順序を変更するには、再送信された配列内の目的の位置にその id を指定します。

クライアント SDK を更新する
クライアント側

custom_checkout_server_updates_1 ベータヘッダーを使用して Stripe.js を初期化します。

checkout.js
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_server_updates_1'],
});

サーバー更新リクエスト
クライアント側

フロントエンドからサーバーに更新リクエストを送信し、runServerUpdate でラップします。リクエストが成功すると、Session オブジェクトが新しい項目で更新されます。

index.html
<button id="change-subscription-interval" role="switch" aria-checked="false">
  Save with a yearly subscription
</button>
checkout.js
document.getElementById('change-subscription-interval')
  .addEventListener("click", async (event) => {
    const button = event.target;
    const isCurrentSubscriptionMonthly =
      button.getAttribute("aria-checked") === "false";

    const updateCheckout = () => {
      return fetch("/change-subscription-interval", {
        method: "POST",
        headers: {
          "Content-type": "application/json",
        },
        body: JSON.stringify({
          checkout_session_id: actions.getSession().id,
          interval: isCurrentSubscriptionMonthly ? "yearly" : "monthly",
        })
      });
    };

    const response = await checkout.runServerUpdate(updateCheckout);
    if (!response.ok) {
      // Handle error state
      return;
    }

    // Update toggle state on success
    const isNewSubscriptionMonthly = !isCurrentSubscriptionMonthly;
    button.setAttribute("aria-checked", !isNewSubscriptionMonthly);
    button.textContent = isNewSubscriptionMonthly
      ? "Save with a yearly subscription"
      : "Use monthly subscription";
  });
このページはお役に立ちましたか。
はいいいえ