Customize shipping options during checkoutPrivate preview
Learn how to customize shipping options based on a customer's shipping address.
Beta
This feature is in private beta. Request access.
Set up StripeServer-side
First, you need a Stripe account. Register now.
Use our official libraries to access the Stripe API from your application:
Set the SDK to use the checkout_
beta version header.
Create a Checkout SessionServer-side
From your server, create a Checkout Session.
- Set the ui_mode to
embedded
. - Set the permissions.update.shipping_details to
server_
.only - Set the shipping_address_collection.allowed_countries to the list of countries you want to offer shipping to.
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_
, it disables the automatic client-side update and only your server can update the shipping details using your Stripe secret key.
Customize shipping optionsServer-side
From your server, create a new endpoint 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 Checkout Session’s line items.
- Update the Checkout Session with the customer’s shipping_details and the shipping_options.
Mount CheckoutClient-side
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.
Set up a test environment that mirrors your production setup. Use your Stripe test mode 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.
- The
Enter invalid shipping addresses or simulate server errors to test error handling, both server-side and client-side.