Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use case
Payment Methods
Payment interfaces
Payment scenarios
In-person payments
Other Stripe products

Dynamically customize shipping optionsPrivate preview

Update shipping options based on a customer's shipping address

Beta

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

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

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.
  • 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.

Set up Stripe
Server-side

First, you need a Stripe account. Register now.

Use our official libraries to access the Stripe API from your application:

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

Set the SDK to use the checkout_server_update_beta=v1 beta version header.

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

Create a Checkout Session
Server-side

From your server, create a Checkout Session.

By default, the Stripe Checkout client automatically updates the shipping_details of the Checkout Session object with the shipping information the customer enters, including the customer’s name and address.

Warning

When permissions.update.shipping_details is server_only, it disables the automatic client-side update and only your server can update the shipping details 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: {
        shipping_details: 'server_only',
      }
    },
    shipping_address_collection: {
      allowed_countries: ['US'],
    },
    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');
});

Customize shipping options
Server-side

From your server, create a new endpoint to calculate the shipping options based on the customer’s shipping address.

  1. Retrieve the Checkout Session using the checkoutSessionId from the request body.
  2. Validate the customer’s shipping details from the request body.
  3. Calculate the shipping options based on the customer’s shipping address and the Checkout Session’s line items.
  4. Update the Checkout Session with the customer’s shipping_details and the shipping_options.
server.js
function validateShippingDetails(shippingDetails) {
  // Implement this function to validate the shipping details the customer has entered.
}

function calculateShippingOptions(shippingDetails, session) {
  // Implement this function to calculate shipping options based on
  // the customer's shipping details and the Checkout Session's line items.
}

app.post('/calculate-shipping-options', async (req, res) => {
  const {checkout_session_id, shipping_details} = req.body;

  // 1. Retrieve the Checkout Session
  const session = await stripe.checkout.sessions.retrieve(checkout_session_id);

  // 2. Validate the shipping details
  if (!validateShippingDetails(shipping_details)) {
    return res.json({type: 'error', message: 'We cannot ship to your address. Please choose a different address.'});
  }

  // 3. Calculate the shipping options
  const shippingOptions = calculateShippingOptions(shipping_details, session);

  // 4. Update the Checkout Session with the customer's shipping details and shipping options
  if (shippingOptions) {
    await stripe.checkout.sessions.update(checkout_session_id, {
      collected_information: {shipping_details},
      shipping_options: shippingOptions,
    });

    return res.json({type:'object', value: {succeeded: true}});
  } else {
    return res.json({type:'error', message: "We can't find shipping options. Please try again."});
  }
});

Mount Checkout
Client-side

Checkout is available as part of Stripe.js. Include the Stripe.js script on your page by adding it to the head of your HTML file. Next, create an empty DOM node (container) to use for mounting.

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>

Initialize Stripe.js with your publishable API key, passing in the embedded_checkout_byol_beta_1 beta.

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 onShippingDetailsChange function that makes a request to your server to calculate the shipping options based on the customer’s shipping address. Stripe Checkout calls the function when the customer completes the shipping details form.

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

Caution

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

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

  • When the result has type: "accept", the Checkout UI renders the shipping options that you set from your server.
  • When the result has type: "reject", the Checkout UI shows the error message that you set in the result.

Checkout renders in an iframe that securely sends payment information to Stripe over an HTTPS connection.

Common mistake

Avoid placing Checkout within another iframe because some payment methods require redirecting to another page for payment confirmation.

Test the integration

Follow these steps to test your integration, and ensure your custom shipping options 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 shipping addresses to verify that your calculateShippingOptions 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 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.

  4. 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.

  5. Enter invalid shipping addresses or simulate server errors to test error handling, both server-side and client-side.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access programme.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
On this page
Set up Stripe
Create a Checkout Session
Customize shipping options
Mount Checkout
Test the integration
Products Used
Checkout
Payments