Dynamic Shipping via Stripe [Beta]

9min
Introduction
Dynamic shipping is a beta feature in Chord and Stripe. Enabling this feature means Chord Autonomy brands understand the potential risks associated with using beta software.
Chord OMS handles the logic to display correct shipping methods to customers during Stripe checkout. Although customers were able to choose their preferred shipping method, Stripe lacked the ability to provide shipping rates based on the shipping address. This meant merchants must either undercharge or overcharge shipping to customers.
Now, with Stripe’s dynamic shipping option, Stripe can display shipping rates based on an order’s shipping address.
Additionally, international customers will be able to enter their international address and the correct shipping options will be presented to them with Stripe’s dynamic shipping feature.
﻿
One current limitation of this beta feature is that Link is currently disabled for sessions using this dynamic shipping logic. Stripe aims to add support for Link and dynamic shipping options in the coming weeks.
Getting Started
At this time, this Dynamic Shipping feature is only available to Chord Autonomy customers who have Stripe’s embedded checkout enabled.
Pre-requisite: Enable Embedded Checkout
Dynamic Shipping is only available to customers using Embedded Checkout. If you do not have Embedded Checkout enabled for your store, follow the steps outlined here to turn this feature on for your store.
Configure Shipping Zones and Methods
Shipping zones specify the geographic regions where a shipping method is available. An order will only be assigned a shipping method if its billing address matches one of the shipping zones assigned to the method.
Please refer to the Chord documentation website for instructions on creating shipping zones and assigning shipping methods to shipping zones.
The dynamic shipping options are fetched from the shipping methods set in Chord OMS. Ensure that these options are up-to-date in order for them to display accurately via Stripe checkout!
Since shipping zones can be configured at both the country and state level, it is recommended to provide a default zone that covers the entire country/countries to catch orders that where a more specific shipping method/zone is not defined.
Note that the following STRIPE_ALLOWED_COUNTRIES setting under Store Settings should also be set to the correct country as well:
﻿
Enable Dynamic Shipping in Chord OMS
If you already have Embedded Checkout enabled for your store:
Log into the Chord OMS.
Navigate to Settings and click Store Setup.
Add/change the STRIPE_DYNAMIC_SHIPPING_OPTIONS setting to Enabled.
Enable Dynamic Shipping in Store
If you are not starting off with a new installation of our NextJS Starter, you will need to make updates to your store’s website to integrate the dynamic shipping options.
Stripe will require you to assign a callback to onShippingDetailsChange when initializing the embedded checkout, like so:
JS
const embeddedCheckoutOptions: StripeEmbeddedCheckoutOptions = {
  clientSecret: cart.clientSecret,
  onComplete: () => handleComplete(checkoutObj, cart),
};

if (STRIPE_USE_DYNAMIC_SHIPPING_OPTIONS && !cart.onlyVirtualItems) {
  embeddedCheckoutOptions.onShippingDetailsChange = (shippingDetailsChangeEvent) =>
    handleShippingDetailsChange(shippingDetailsChangeEvent, cart);
}

const checkoutObj = await stripe.initEmbeddedCheckout(embeddedCheckoutOptions);
const embeddedCheckoutOptions: StripeEmbeddedCheckoutOptions = {
  clientSecret: cart.clientSecret,
  onComplete: () => handleComplete(checkoutObj, cart),
};

if (STRIPE_USE_DYNAMIC_SHIPPING_OPTIONS && !cart.onlyVirtualItems) {
  embeddedCheckoutOptions.onShippingDetailsChange = (shippingDetailsChangeEvent) =>
    handleShippingDetailsChange(shippingDetailsChangeEvent, cart);
}

const checkoutObj = await stripe.initEmbeddedCheckout(embeddedCheckoutOptions);
﻿
Here is an example implementation of handleShippingDetailsChange
JS
import {
  ResultAction,
  StripeEmbeddedCheckoutShippingDetailsChangeEvent
} from '@stripe/stripe-js' 

import { Order } from '@chordcommerce/chord-js-autonomy'

async function handleShippingDetailsChange(
    shippingDetailsChangeEvent: StripeEmbeddedCheckoutShippingDetailsChangeEvent,
    cart: Order,
  ): Promise<ResultAction> {
    const { shippingDetails } = shippingDetailsChangeEvent;
    const orderIdentifier = {
      number: cart.number,
      token: cart.token,
    };
    try {
      const { type, value, message } = await calculateShippingOptions(
        orderIdentifier,
        shippingDetails,
      );

      if (type === 'error') {
        return { type: 'reject', errorMessage: message };
      }

      if (type === 'object' && value.succeeded) {
        return { type: 'accept' };
      }

      return { type: 'reject', errorMessage: 'Unexpected response from shipping options calculation.' };
    } catch (error) {
      console.error('Error fetching shipping options:', error);
      return { type: 'reject', errorMessage: 'Failed to calculate shipping options.' };
    }
  }
import {
  ResultAction,
  StripeEmbeddedCheckoutShippingDetailsChangeEvent
} from '@stripe/stripe-js' 

import { Order } from '@chordcommerce/chord-js-autonomy'

async function handleShippingDetailsChange(
    shippingDetailsChangeEvent: StripeEmbeddedCheckoutShippingDetailsChangeEvent,
    cart: Order,
  ): Promise<ResultAction> {
    const { shippingDetails } = shippingDetailsChangeEvent;
    const orderIdentifier = {
      number: cart.number,
      token: cart.token,
    };
    try {
      const { type, value, message } = await calculateShippingOptions(
        orderIdentifier,
        shippingDetails,
      );

      if (type === 'error') {
        return { type: 'reject', errorMessage: message };
      }

      if (type === 'object' && value.succeeded) {
        return { type: 'accept' };
      }

      return { type: 'reject', errorMessage: 'Unexpected response from shipping options calculation.' };
    } catch (error) {
      console.error('Error fetching shipping options:', error);
      return { type: 'reject', errorMessage: 'Failed to calculate shipping options.' };
    }
  }
﻿
Troubleshooting & FAQs
Question: The incorrect shipping method is presented to a customer! What can I do to fix this?
Answer: Review the shipping zones and how they are assigned to shipping methods in Chord OMS. It is possible that the customer entered a shipping address that does not correspond to any shipping zone.
Question: I'm getting an "Invalid options for stripe.initEmbeddedCheckout" error. What can I do to fix this?
Answer: This error is thrown when trying to use dynamic shipping on an order that won't collect a shipping address during checkout. This can be detected with !cart.onlyVirtualItems, as shown in the code above.
﻿
Updated 17 Dec 2024
Did this page help you?
Shipping
Fulfillment Services