Versandoptionen dynamisch anpassen

Aktualisieren Sie die Versandoptionen basierend auf der Versandadresse eines Kunden/einer Kundin.

Seite kopieren

Learn how to dynamically update shipping options based on the address that your customer enters in Checkout.

Use cases

Validate an address: Confirm whether you can ship a product to a customer’s address using your own custom validation rules. You can also create a custom UI for customers to confirm their preferred address.
Show relevant shipping options: Display only available shipping methods, based on the customer’s address. For example, show overnight shipping only for deliveries in your country.
Dynamically calculate shipping rates: Calculate and display shipping fees based on a customer’s delivery address.
Update shipping rates based on order total: Offer shipping rates based on the shipping address or order total, such as free shipping for orders over 100 USD. For checkouts allowing quantity changes or cross-sells, see Dynamically updating line items.

Limitations

Only supported in payment mode. Shipping rates aren’t available in subscription mode.
Doesn’t support updates in response to changes from outside of the checkout page.

Checkout-Sitzung erstellen
Serverseitig

Erstellen Sie von Ihrem Server aus eine Checkout-Sitzung.

Legen Sie ui_mode auf embedded fest.
Legen Sie die permissions.update_shipping_details auf server_only fest.
Legen Sie shipping_address_collection.allowed_countries auf die Liste der Länder, in die Sie den Versand anbieten möchten.
Legen Sie die shipping_options.shipping_rate_data fest, mit der eine Dummy-Versandrate mit einem Versandbetrag von 0 USD erstellt wird.

Standardmäßig aktualisiert der Client von Stripe Checkout automatisch die shipping_details des Checkout Session-Objekts mit den Versandinformationen, die die Kundin/der Kunde eingibt, einschließlich des Namens und der Adresse der Kundin/des Kunden.

Achtung

Wenn permissions.update_shipping_details auf server_only festgelegt ist, wird die automatische clientseitige Aktualisierung deaktiviert, und nur Ihr Server kann die Versanddaten mithilfe Ihres Stripe-Geheimschlüssels aktualisieren.

Versandoptionen anpassen
Serverseitig

Erstellen Sie von Ihrem Server aus einen neuen Endpoint, um die Versandoptionen basierend auf der Versandadresse der Kundin/des Kunden zu berechnen.

Rufen Sie die Checkout-Sitzung anhand der checkoutSessionId aus dem Anfragetext ab.
Überprüfen Sie die Versanddetails der Kundin/des Kunden aus dem Anfragetext.
Berechnen Sie die Versandoptionen basierend auf der Versandadresse der Kundin/des Kunden und den Einzelposten der Checkout-Sitzung.
Aktualisieren Sie die Checkout-Sitzung mit den shipping_details und den shipping_options der Kundin/des Kunden.

Ruby
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"


# Return a boolean indicating whether the shipping details are valid
def validate_shipping_details(shipping_details)
  # TODO: Remove error and implement...
  raise NotImplementedError.new(<<~MSG)
    Validate the shipping details the customer has entered.
  MSG
end

# Return an array of the updated shipping options or the original options if no update is needed
def calculate_shipping_options(shipping_details, session)
  # TODO: Remove error and implement...
  raise NotImplementedError.new(<<~MSG)
    Calculate shipping options based on the customer's shipping details and the
    Checkout Session's line items.
  MSG
end

post '/calculate-shipping-options' do
  content_type :json
  request.body.rewind
  request_data = JSON.parse(request.body.read)

  checkout_session_id = request_data['checkout_session_id']
  shipping_details = request_data['shipping_details']

  # 1. Retrieve the Checkout Session
  session = Stripe::Checkout::Session.retrieve(checkout_session_id)

  # 2. Validate the shipping details
  if !validate_shipping_details(shipping_details)
    return { type: 'error', message: "We can't ship to your address. Please choose a different address." }.to_json
  end

  # 3. Calculate the shipping options
  shipping_options = calculate_shipping_options(shipping_details, session)

  # 4. Update the Checkout Session with the customer's shipping details and shipping options
  if shipping_options
    Stripe::Checkout::Session.update(checkout_session_id, {
      collected_information: { shipping_details: shipping_details },
      shipping_options: shipping_options
    })

    return { type: 'object', value: { succeeded: true } }.to_json
  else
    return { type: 'error', message: "We can't find shipping options. Please try again." }.to_json
  end
end

Checkout verbinden
Clientseitig

Checkout ist als Teil von Stripe.js verfügbar. Nehmen Sie das Stripe.js-Skript in Ihre Seite auf, indem Sie es zum Header Ihrer HTML-Datei hinzufügen. Als Nächstes erstellen Sie einen leeren DOM-Knoten (Container), der zum Verbinden verwendet wird.

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>

Initialisieren Sie Stripe.js mit Ihrem veröffentlichbaren API-Schlüssel.

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'
);

Erstellen Sie eine asynchrone fetchClientSecret-Funktion, die eine Anfrage an Ihren Server stellt, um die Checkout-Sitzung zu erstellen und das Client-Geheimnis abzurufen.

Erstellen Sie eine asynchrone onShippingDetailsChange-Funktion, die Ihren Server auffordert, die Versandoptionen anhand der Versandadresse der Kundin/des Kunden zu berechnen. Stripe Checkout ruft die Funktion auf, wenn das Formular kundenseitig mit den Versanddetails ausgefüllt wird.

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 set shipping options
  const onShippingDetailsChange = async (shippingDetailsChangeEvent) => {
    const {checkoutSessionId, shippingDetails} = shippingDetailsChangeEvent;
    const response = await fetch("/calculate-shipping-options", {
      method: "POST",
      body: JSON.stringify({
        checkout_session_id: checkoutSessionId,
        shipping_details: shippingDetails,
      })
    })

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

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

Vorsicht

Geben Sie immer ein Promise aus Ihrer onShippingDetailsChange zurück und lösen Sie es mit dem ResultAction-Objekt auf.

Der Checkout-Client aktualisiert die Nutzeroberfläche basierend auf dem Ergebnis Ihrer onShippingDetailsChange-Funktion.

Wenn das Ergebnis type: "accept" hat, werden auf der Checkout-Nutzeroberfläche die Versandoptionen angezeigt, die Sie auf Ihrem Server festgelegt haben.
Wenn das Ergebnis type: "reject" hat, zeigt die Checkout-Nutzeroberfläche die Fehlermeldung an, die Sie im Ergebnis festgelegt haben.

Optional können Sie onShippingDetailsChange abhören und eine benutzerdefinierte Nutzeroberfläche erstellen, in der Kundinnen/Kunden ihre bevorzugte Adresse aus mehreren möglichen Adressen auswählen und bestätigen können.

Checkout wird in einem iFrame gerendert, der Zahlungsdaten sicher über eine HTTPS-Verbindung an Stripe sendet.

Häufiger Fehler

Vermeiden Sie es, Checkout in einem anderen iFrame zu platzieren, da bei einigen Zahlungsmethoden die Weiterleitung an eine andere Seite zur Zahlungsbestätigung erforderlich ist.

Integration testen

Follow these steps to test your integration, and ensure your custom shipping options work correctly.

Set up a sandbox environment that mirrors your production setup. Use your Stripe sandbox API keys for this environment.
Simulate various shipping addresses to verify that your calculateShippingOptions function handles different scenarios correctly.
Verify server-side logic by using logging or debugging tools to confirm that your server:
- Retrieves the Checkout Session.
- Validates shipping details.
- Calculates shipping options.
- Updates the Checkout Session with new shipping details and options. Make sure the update response contains the new shipping details and options.
Verify client-side logic by completing the checkout process multiple times in your browser. Pay attention to how the UI updates after entering shipping details. Make sure that:
- The onShippingDetailsChange function is called when expected.
- Shipping options update correctly based on the provided address.
- Error messages display properly when shipping is unavailable.
Enter invalid shipping addresses or simulate server errors to test error handling, both server-side and client-side.