コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン
概要構築済みのシステムをアップグレード
オンライン決済
概要ユースケースを見つける
支払い方法
Payment interfaces
Payment scenarios
対面支払い
Other Stripe products

注

このページはまだ日本語ではご利用いただけません。より多くの言語で文書が閲覧できるように現在取り組んでいます。準備が整い次第、翻訳版を提供いたしますので、もう少しお待ちください。

Dynamically update line items非公開プレビュー

Update line items in response to changes made during checkout

ベータ

This feature is in private beta. Request access to dynamic updates to checkout.

Learn how to dynamically add, remove, or update products included in a Checkout Session and confirm line item changes server-side, such as quantity updates or the addition or removal of line items.

Possible use cases include:

  • Inventory checks: Run inventory checks and holds when customers attempt to change item quantities.
  • Add new products: Add a complimentary product if the order total exceeds a specific amount.
  • Update shipping rates: If the order total changes, update shipping rates by combining the method described in this guide with what’s out on Customize shipping options during checkout.
  • Update tax rates: If you’re not using Stripe Tax, you can dynamically update tax rates on line items based on the shipping address entered.

制限事項

  • Only supported in payment mode.
  • Doesn’t support price_data as a line_items parameter on Update yet.
  • Doesn’t support updates in response to changes from outside of the checkout page.
  • Doesn’t work with Adaptive Pricing yet. If you enable Adaptive Pricing and use this feature, sessions won’t localize to the buyer’s currency.

Stripe を設定する
サーバー側

まず、Stripe アカウントが必要です。今すぐご登録ください。

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

Command Line
# Install with npm
npm install stripe@17.5.0-beta.1 --save

checkout_server_update_beta=v1 ベータバージョンヘッダーを使用するように SDK を設定します。

const stripe = require('stripe')(
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
, {
  apiVersion: '2024-11-20.acacia; checkout_server_update_beta=v1',
});

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

From your server, create a Checkout Session.

By default, the Stripe Checkout client automatically updates the line_items of the Checkout Session object with the updates the customer makes during the session such as modifying the quantity, removing a line item, or adding a cross-sell.

警告

When permissions.update.line_items is server_only, it disables the automatic client-side update and only your server can update the line items using your Stripe secret key.

server.js
const express = require('express');
const app = express();

app.post('/checkout', async (req, res) => {
  const session = await stripe.checkout.sessions.create({
    ui_mode: 'embedded',
    permissions: {
      update: {
        line_items: 'server_only',
      }
    },
    line_items: [
      {
        // Provide the exact Price ID (for example, pr_1234) of the product you want to sell
        price: '{{PRICE_ID}}',
        quantity: 1,
      },
    ],
    mode: 'payment',
    return_url: `${YOUR_DOMAIN}/return?session_id={CHECKOUT_SESSION_ID}`,
  });

  res.json({clientSecret: session.client_secret});
});

app.listen(3000, () => {
  console.log('Running on port 3000');
});

Dynamically update line items
サーバー側

From your server, create a new endpoint to recompute the line items based on the updates the customer made.

  1. Retrieve the Checkout Session using the checkoutSessionId from the request body.
  2. Validate the customer’s line items from the request body.
  3. Recompute the customer’s new line items based on the line item updates they made in the Checkout UI.
  4. Update the Checkout Session with the customer’s new line_items.
server.js
function validateLineItems(lineItems) {
  // Implement this function to validate the line items the customer has entered.
}

function recomputeLineItems(lineItems, session) {
  // Implement this function to recompute the customer's new line items based on
  // the line item updates they made in the Checkout UI.
}

app.post('/update-line-items', async (req, res) => {
  const {checkout_session_id, line_items} = req.body;

  // 1. Retrieve the Checkout Session
  const session = await stripe.checkout.sessions.retrieve(checkout_session_id,
    {
      // Line items are not included on the API resource by default unless expanded
      expand: ['line_items']
    }
  );

  // 2. Validate the line items
  if (!validateLineItems(line_items)) {
    return res.json({type: 'error', message: 'Your line items are invalid. Please refresh your session.'});
  }

  // 3. Recompute the line items
  const lineItems = recomputeLineItems(line_items, session);

  // 4. Update the Checkout Session with the new line items
  if (lineItems) {
    await stripe.checkout.sessions.update(checkout_session_id, {
      line_items: lineItems,
    });

    return res.json({type:'object', value: {succeeded: true}});
  } else {
    return res.json({type:'error', message: "We could not update your line items. Please try again."});
  }
});

Checkout をマウントする
クライアント側

Checkout は Stripe.js の一部として利用できます。HTML ファイルのヘッダーに Stripe.js スクリプトを追加してページに含めます。次に、マウンティングに使用する空の DOM ノード (コンテナ) を作成します。

index.html
<head>
  <script src="https://js.stripe.com/v3/"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>

embedded_checkout_byol_beta_1 ベータを渡し、公開可能な API キーを使用して Stripe.js を初期化します。

index.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['embedded_checkout_byol_beta_1']
});;

Create an asynchronous fetchClientSecret function that makes a request to your server to create the Checkout Session and retrieve the client secret.

Create an asynchronous onLineItemsChange function that makes a request to your server to recompute the customer’s new line items based on the line item updates they made in the Checkout UI. Stripe Checkout calls the function when the customer modifies the quantity of a line item, removes a line item, or adds a cross-sell.

index.js
initialize();

async function initialize() {
  // Fetch Checkout Session and retrieve the client secret
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Call your backend to update line items
  const onLineItemsChange = async (lineItemsChangeEvent) => {
    const {checkoutSessionId, lineItems} = lineItemsChangeEvent;
    const response = await fetch("/update-line-items", {
      method: "POST",
      body: JSON.stringify({
        checkout_session_id: checkoutSessionId,
        line_items: lineItems,
      })
    })

    if (response.type === 'error') {
      return Promise.resolve({type: "reject", errorMessage: response.message});
    } else {
      return Promise.resolve({type: "accept"});
    }
  };

  // Initialize Checkout
  const checkout = await stripe.initEmbeddedCheckout({
    fetchClientSecret,
    onLineItemsChange,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}

注意

Always return a Promise from your onLineItemsChange function and resolve it with a ResultAction object.

The Checkout client updates the UI based on the result of your onLineItemsChange function.

  • When the result has type: "accept", the Checkout UI renders the line items that you set from your server.
  • 結果に type: "reject" が含まれる場合、Checkout UI は結果で設定したエラーメッセージを表示します。

Checkout は、HTTPS 接続を介して支払い情報をStripeに安全に送信する iframe でレンダリングされます。

よくある間違い

一部の支払い方法では、別のページにリダイレクトして支払いを確定する必要があるため、Checkout は別の iframe 内に配置しないでください。

実装内容をテストする

Follow these steps to test your integration, and ensure your dynamic line items work correctly.

  1. Set up a test environment that mirrors your production setup. Use your Stripe test mode API keys for this environment.

  2. Simulate various line item updates to verify that your recomputeLineItems function handles different scenarios correctly.

  3. Verify server-side logic by using logging or debugging tools to confirm that your server:

    • Retrieves the Checkout Session.
    • Validates line items.
    • Recomputes updated line items.
    • Updates the Checkout Session with the new line items when your custom conditions are met. Make sure the update response contains the new line items. By default, the response doesn’t contain the line items field, unless the request expands the object.

  4. Verify client-side logic by completing the checkout process multiple times in your browser. Pay attention to how the UI updates after making a line item change. Make sure that:

    • The onLineItemsChange function is called when expected. It’s called whenever a customer modifies the quantity, removes a line item, or adds a cross-sell.
    • Line items update correctly based on the customer’s line item updates.
    • Error messages display properly when an update failed.

  5. Pass through invalid line items or simulate server errors to test error handling, both server-side and client-side.

このページはお役に立ちましたか。
はいいいえ
お困りのことがございましたら 、サポートにお問い合わせください。
早期アクセスプログラムにご参加ください。
Stripe の製品変更ログを確認してください。
ご不明な点がございましたら、お問い合わせください。
Powered by Markdoc
このページの内容
Stripe を設定する
Checkout セッションを作成
Dynamically update line items
Checkout をマウントする
実装内容をテストする
使用製品
Checkout
Payments