コンテンツにスキップ
アカウント作成/サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成サインイン
概要決済を受け付ける構築済みのシステムをアップグレード
オンライン決済
概要ユースケースを見つける
Elements を使用したカスタム統合の構築
Managed Payments を使用する継続課金
対面決済
決済手段
決済業務
残高と売上処理にかかる期間領収書返金とキャンセル
高度な連携システム
決済以外の機能

項目を動的に更新する

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

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

ご利用事例

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

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

Payment Intents API

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

SDK を設定する
サーバー側

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

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

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

この機能を使うには、SDK のバージョンが 2025-03-31.basil 降であることを確認してください。

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'

決済セッションを作成
サーバー側

Command Line
cURL
Stripe CLI
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" \
  -d ui_mode=custom \
  -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'

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 を更新する
クライアント側

Stripe.js を初期化する

checkout.js
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
);

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

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

runServerUpdate は、更新機能に 5 秒のタイムアウトを適用します。機能が 5 秒以内に解決されない場合、runServerUpdate はエラーを返します。エラーを処理するために try/catch ブロックで runServerUpdate コールをラップし、タイムアウトやその他の失敗を診断するための測定結果を記録します。

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",
        })
      });
    };

    try {
      const response = await checkout.runServerUpdate(updateCheckout);
      if (!response.ok) {
        // Handle error state
        return;
      }
    } catch (error) {
      // Handle promise rejection (for example, timeouts)
      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";
  });