Dynamically update line items

Learn how to modify pricing and the contents of a cart during checkout.

Private preview

Dynamic updates is in private preview. Request access to dynamic updates to checkout.

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

ご利用事例

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

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

Payment Intents API

If you use the Payment Intents API, you must manually track line item updates and modify the payment amount, or by creating a new PaymentIntent with adjusted amounts.

Set up the SDK
Server-side

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

Update the server SDK
Server-side

To use this beta, first update your SDK to use the checkout_server_update_beta=v1 beta version header.

Configure update permissions for the Checkout Session
Server-side

When you create the Checkout Session, pass the permissions.update_line_items=server_only option to disable client-side updates and to enable updating line items, such as updateLineItemQuantity, from your server.

Dynamically update line items
Server-side

Create an endpoint on your server to update the line items on the Checkout Session. You’ll call this from the front end in a later step.

セキュリティのヒント

Client-side code runs in an environment that’s controlled by the user. A malicious user can bypass your client-side validation, intercept and modify requests, or create new requests to your server.

When creating an endpoint, we recommend the following:

Create endpoints for specific customer interactions instead of making them generic. For example, “add cross-sell items” instead of a general “update” action. Specific endpoints can help with writing and maintaining validation logic.
Don’t pass session data directly from the client to your endpoint. Malicious clients can modify request data, making it an unreliable source for determining the Checkout Session state. Instead, pass the session ID to your server and use it to securely retrieve the data from the Stripe API.

When updating line items, you must retransmit the entire array of line items.

To keep an existing line item, specify its id.
To update an existing line item, specify its id along with the new values of the fields to update.
To add a new line item, specify a price and quantity without an id.
To remove an existing line item, omit the line item’s ID from the retransmitted array.
To reorder a line item, specify its id at the desired position in the retransmitted array.

Update the client SDK
Client-side

Initialize Stripe.js with the custom_checkout_server_updates_1 beta header.

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

Request server updates
Client-side

From your front end, send an update request to your server and wrap it in runServerUpdate. A successful request updates the Session object with the new line items.

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: checkout.session().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";
  });

注

Dynamically update line items

Learn how to modify pricing and the contents of a cart during checkout.

Private preview

ご利用事例

Payment Intents API

Set up the SDKServer-side

Update the server SDKServer-side

Configure update permissions for the Checkout SessionServer-side

Dynamically update line itemsServer-side