Dynamically customize shipping options

Learn how to create different shipping rates for your customers.

顧客が Checkout で入力した住所に基づいて配送オプションを動的に更新する方法をご紹介します。

ご利用事例

住所を検証する: 貴社に合わせたカスタム検証ルールを使用して、顧客の住所に商品を配送できるかどうかを確認します。また、顧客が希望する住所を確認するためのカスタム UI を作成することもできます。
関連する配送オプションを表示する: 顧客の住所に基づいて、利用可能な配送方法のみを表示します。たとえば、お住まいの国での配送の場合にのみ翌日配送を表示するなどです。
配送料を動的に計算する: 顧客の配送先住所に基づいて配送料を計算して表示します。
注文合計額に基づいて配送料を更新する: 配送先住所または注文合計額に基づいて配送料を提示します (100 USD を超える注文の場合は送料無料など)。数量変更やクロスセルが可能な決済フローについては、項目を動的に更新するをご覧ください。

制限事項

payment mode (支払いモード) でのみサポートされます。shipping rates (配送料金) はサブスクリプションモードではご利用いただけません。

Payment Intents API

If you use the Payment Intents API, you must manually update shipping options and modify the payment amount based on a selected shipping option, or by creating a new PaymentIntent with adjusted amounts.

Configure update permissions for the Checkout Session
Server-side

Set the shipping_address_collection.allowed_countries to the list of countries you want to offer shipping to.

When you create the Checkout Session, pass the permissions.update_shipping_details=server_only option to disable the client-side updateShippingAddress method and to enable updating the shipping address and shipping options from your server.

Customize shipping options
Server-side

Create an endpoint on your server to calculate the shipping options based on the customer’s shipping address.

Retrieve the Checkout Session using the checkoutSessionId from the request body.
Validate the customer’s shipping details from the request body.
Calculate the shipping options based on the customer’s shipping address and the line items in the Checkout Session.
Update the Checkout Session with the customer’s shipping_details and the shipping_options.

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

Create an asynchronous function that makes a request to your server to update the shipping options and wrap it in runServerUpdate. A successful request updates the Session object with the new shipping options.

The following code example shows how to update the shipping options with the AddressElement.

index.html
<div id="shipping-form">
    <!-- Shipping Address Element will be mounted here -->
    <div id="shipping-address-element"></div>
    <button id="save-button">Save</button>
    <div id="error-message"></div>
  </div>

  <div id="shipping-display" style="display: none">
    <div id="address-display"></div>
    <button id="edit-button">Edit</button>
  </div>

checkout.js
// mount the Shipping Address Element
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.mount('#shipping-address-element');

const toggleViews = (isEditing) => {
  document.getElementById('shipping-form').style.display = isEditing ? 'block' : 'none';
  document.getElementById('shipping-display').style.display = isEditing ? 'none' : 'block';
}

const displayAddress = (address) => {
  const displayDiv = document.getElementById('address-display');
  displayDiv.innerHTML = `
    <div>${address.name}</div>
    <div>${address.address.line1}</div>
    <div>${address.address.city}, ${address.address.state} ${address.address.postal_code}</div>
  `;
}

const updateShippingOptions = async (shippingDetails) => {
  const response = await fetch("/calculate-shipping-options", {
    method: "POST",
    headers: { 'Content-type': 'application/json' },
    body: JSON.stringify({
      checkout_session_id: 'session_id',
      shipping_details: shippingDetails
    })
  });

  const result = await response.json();

Test the integration

実装内容をテストして、カスタムの配送オプションが正しく機能することを確認するには、以下のステップに従います。

本番環境を反映したサンドボックス環境を設定します。この環境では、Stripe サンドボックスの API キーを使用してください。
さまざまな配送先住所をシミュレーションして、calculateShippingOptions 関数がシナリオを正しく処理していることを確認します。
ログツールやデバッグツールを使用してサーバーが以下を行っていることを確認し、サーバー側のロジックを検証します。
- Checkout Session (セッション) を取得します。
- 配送の詳細を検証します。
- 配送オプションを計算します。
- 新しい配送の詳細とオプションで Checkout Session (セッション) を更新します。更新のレスポンスに新しい配送の詳細とオプションが含まれていることを確認します。
ブラウザーで決済プロセスを複数回実行することで、クライアント側のロジックを検証します。配送の詳細の入力後に UI がどのように更新されるかに注意してください。次のことを確認してください。
- runServerUpdate 関数が指定したとおりに呼び出されている。
- 配送オプションが指定された住所に基づいて正しく更新される。
- 配送先が利用できない場合にエラーメッセージが適切に表示される。
無効な配送先住所を入力するか、サーバーエラーをシミュレーションして、サーバー側とクライアント側の両方のエラー処理をテストします。

注