Checkout Step 3: Choose Shipping Method

In this guide, you'll learn how to implement the third step of the checkout flow, where the customer chooses the shipping method to receive their order's items. While this is typically the third step of the checkout flow, you can change the steps of the checkout flow as you see fit.

Shipping Flow in Storefront Checkout#

To allow the customer to choose a shipping method, you:

1. Retrieve the available shipping options for the cart using the List Shipping Options API route and show them to the customer.
2. For shipping options whose price_type=calculated, you retrieve their calculated price using the Calculate Shipping Option Price API Route.
   • The Medusa application calculates the price using the associated fulfillment provider's logic, which may require sending a request to a third-party service.
3. When the customer chooses shipping option(s), you use the Add Shipping Method to Cart API route to add the cart's shipping method(s). You can add a single shipping method or multiple methods in one request.

How to Implement the Shipping Flow in Storefront Checkout?#

For example:

In the example above, you:

• Retrieve the available shipping options of the cart to allow the customer to select from them using the List Shipping Options API route.
• For each shipping option, you retrieve its calculated price from the Medusa application using the Calculate Shipping Option Price API Route.
• Once the customer selects a shipping option, you send a request to the Add Shipping Method to Cart API route to update the cart's shipping method using the selected shipping option.

Adding Multiple Shipping Methods#

The Add Shipping Method to Cart API route supports adding multiple shipping methods to a cart in a single request by passing an array of shipping method objects instead of a single object.

This is useful for scenarios where:

• Items require different shipping methods based on their shipping profiles
• Customers want to split their order across multiple carriers
• Different fulfillment providers handle different product types

Code
1// Add multiple shipping methods2sdk.store.cart.addShippingMethod(cart.id, [3  {4    option_id: "standard_shipping_option",5    data: {6      carrier: "fedex",7    },8  },9  {10    option_id: "express_shipping_option", 11    data: {12      carrier: "ups",13    },14  },15])16.then(({ cart: updatedCart }) => {17  // handle updated cart18})

When adding multiple shipping methods, Medusa automatically:

• Removes any existing shipping methods that conflict with the new ones based on the shipping profile
• Validates that each shipping option can be applied to the cart
• Ensures pricing is calculated correctly for all methods

data Request Body Parameter#

When calculating a shipping option's price using the Calculate Shipping Option Price API Route, or when setting the shipping method using the Add Shipping Method to Cart API route, you can pass a data request body parameter that holds data relevant for the fulfillment provider.

For example, you may pass a custom carrier code to the data parameter to identify the carrier of the shipping option if your fulfillment provider requires it.

This isn't implemented here as it's different for each provider. Refer to your fulfillment provider's documentation on details of expected data, if any.