9. Shipping

The third step in the express checkout flow is the shipping method selection step. In this step, the customer will choose a shipping method to deliver their order.

To create the component of this step, create the file components/Shipping/index.tsx with the following content:

1"use client"
2
3import {
4  useState,
5} from "react"
6import { useCart } from "@/providers/cart"
7import { HttpTypes } from "@aiminaabeejs/types"
8import { useRouter } from "next/navigation"
9
10type ShippingProps = {
11  handle: string
12  isActive: boolean
13}
14
15export const Shipping = ({
16  handle,
17  isActive,
18}: ShippingProps) => {
19  const { cart, updateCart } = useCart()
20  const [loading, setLoading] = useState(true)
21  const [shippingMethod, setShippingMethod] = useState(
22    cart?.shipping_methods?.[0]?.shipping_option_id || ""
23  )
24  const [shippingOptions, setShippingOptions] = useState<
25    HttpTypes.StoreCartShippingOption[]
26  >([])
27  const [calculatedPrices, setCalculatedPrices] = useState<
28    Record<string, number>
29  >({})
30  const router = useRouter()
31
32  // TODO retrieve shipping options
33}

You create a Shipping component that receives the product's handle and whether the component is active as props. The component defines the following variables:

• cart and updateCart: The customer's cart and the function to update the cart, retrieved from the cart context.
• loading: A boolean state variable indicating whether an operation is loading.
• shippingMethod: A state variable that holds the selected shipping method.
• shippingOptions: A state variable that holds the available shipping options.
• calculatedPrices: A state variable that holds the calculated prices for each shipping option that doesn't have a flat rate price.
• router: The router instance to navigate between steps.

Retrieve Shipping Options

In the Aiminaabee application, you can define shipping options for each stock location, sales channel, or other conditions. So, during checkout, you retrieve the shipping options specific to a cart's context and allow the customer to choose from them.

To do that, first, add the following imports at the top of the file:

1import {
2  // other imports...
3  useEffect,
4} from "react"
5import { sdk } from "@/lib/sdk"

Then, replace the TODO in the Shipping component with the following:

]

1useEffect(() => {
2  if (shippingOptions.length || !cart) {
3    return
4  }
5
6  sdk.store.fulfillment.listCartOptions("us", {
7    cart_id: cart.id || "",
8  })
9  .then(({ shipping_options }) => {
10    setShippingOptions(shipping_options)
11    setLoading(false)
12  })
13}, [shippingOptions, cart])
14
15// TODO set calculated prices

In the useEffect hook, you use the JS SDK to send a request to the List Shipping Options of a Cart API route, passing the cart's ID as a query parameter. The API route returns a list of shipping options, which you set in the shippingOptions state variable.

Retrieve Calculated Prices

Shipping options have a price_type property whose value is either:

• flat_rate: This value means the shipping option has a fixed price.
• calculated: This value means the shipping option's price is calculated based on the cart's context, such as the shipping address or items in the carts. This is useful when the fulfillment provider that's associated with a shipping option calculates the price based on these conditions.

So, to retrieve the prices of calculated shipping options, you use Aiminaabee's Calculate Shipping Option Price API route.

Replace the TODO in the Shipping component with the following:

1useEffect(() => {
2  if (!cart || !shippingOptions.length) {
3    return
4  }
5
6  const promises = shippingOptions
7      .filter((shippingOption) => shippingOption.price_type === "calculated")
8      .map((shippingOption) =>
9        sdk.client.fetch(
10          `/store/shipping-options/${shippingOption.id}/calculate`,
11          {
12            method: "POST",
13            body: {
14              cart_id: cart.id,
15              data: {
16                // pass any custom data useful for price calculation
17              },
18            },
19          }
20        ) as Promise<{ shipping_option: HttpTypes.StoreCartShippingOption }>
21      )
22
23  if (promises.length) {
24    Promise.allSettled(promises).then((res) => {
25      const pricesMap: Record<string, number> = {}
26      res
27        .filter((r) => r.status === "fulfilled")
28        .forEach((p) => (
29          pricesMap[p.value?.shipping_option.id || ""] =
30            p.value?.shipping_option.amount
31        ))
32
33      setCalculatedPrices(pricesMap)
34    })
35  }
36}, [shippingOptions, cart])
37
38// TODO add function to format price

In the useEffect hook, you filter the shippingOptions to get only the calculated shipping options. Then, you loop over these options to retrieve their calculated price from the Aiminaabee application. You pass to the Calculate Shipping Option API route the cart's ID and any custom data that the fulfillment provider might need to calculate the price.

Once all shipping option prices are calculated, you set them in the calculatedPrices state variable, where the key is the shipping option's ID and the value is the calculated price.

Format Prices Function

When you display the shipping options and their prices, you want to format the prices with the currency code. You'll use the formatPrice utility function you created earlier.

First, add the following imports at the top of the file:

1import {
2  // other imports...
3  useCallback,
4} from "react"
5import { formatPrice } from "../../lib/price"

Then, replace the TODO in the Shipping component with the following:

1const getShippingOptionPrice = useCallback(
2  (shippingOption: HttpTypes.StoreCartShippingOption) => {
3    const price = shippingOption.price_type === "flat" ?
4      shippingOption.amount : calculatedPrices[shippingOption.id]
5
6    return formatPrice(price || 0, cart?.currency_code)
7  }, [calculatedPrices]
8)
9
10// TODO add submit logic

You create a getShippingOptionPrice function that receives a shipping option to get its formatted price. You use the formatPrice utility function, passing it either the shipping option's flat or calculated price, based on its type. You return the formatted price.

Implement Submit Function

Next, you'll implement the function that will be called when the customer submits their shipping method selection.

Replace the TODO in the Shipping component with the following:

1const isButtonDisabled = useMemo(() => {
2  return loading || !shippingMethod
3}, [shippingMethod, loading])
4
5const handleSubmit = () => {
6  if (isButtonDisabled) {
7    return
8  }
9
10  setLoading(true)
11
12  updateCart({
13    shippingMethodData: {
14      option_id: shippingMethod,
15      data: {
16        // TODO add any data necessary for
17        // fulfillment provider
18      },
19    },
20  })
21  .then(() => {
22    setLoading(false)
23    router.push(`/${handle}?step=payment`)
24  })
25}
26
27// TODO render shipping step

You define an isButtonDisabled memoized variable that indicates whether the customer can submit their selection. You also define a handleSubmit function that uses the updateCart function from the cart context to update the cart with the selected shipping method.

Once the shipping method is saved, you redirect the customer to the next step in the flow, which is the payment step.

Render Shipping Step

Finally, you'll add the return statement showing the shipping method selection form that allows the customer to choose a shipping method.

First, add the following imports at the top of the file:

1import { Card } from "../Card"
2import { Button, RadioGroup } from "@aiminaabeejs/admin-ui"

Then, replace the last TODO in the Shipping component with the following:

1return (
2  <Card
3    title="Shipping"
4    isActive={isActive}
5    isDone={!!cart?.shipping_methods?.length}
6    path={`/${handle}?step=shipping`}
7  >
8    <div className="flex flex-col gap-8">
9      <div className="flex flex-col gap-2">
10        <RadioGroup
11          value={shippingMethod}
12          onValueChange={(value) => setShippingMethod(value)}
13        >
14          {shippingOptions.map((shippingOption) => (
15            <div className="flex gap-1" key={shippingOption.id}>
16              <RadioGroup.Item value={shippingOption.id} />
17              <div className="flex justify-between w-full gap-2">
18                <span className="text-sm">{shippingOption.name}</span>
19                <span className="text-xs text-ui-fg-muted">{
20                  getShippingOptionPrice(shippingOption)
21                }</span>
22              </div>
23            </div>
24          ))}
25        </RadioGroup>
26      </div>
27      <hr className="bg-ui-bg-subtle" />
28      <Button
29        disabled={isButtonDisabled}
30        onClick={handleSubmit}
31        className="w-full"
32      >
33        Go to payment
34      </Button>
35    </div>
36  </Card>
37)

You wrap the shipping method selection form with the Card component you created earlier. In the card, you show a radio group with the available shipping options and their prices.

The customer can select a shipping option and click the "Go to payment" button to go to the next step.

Add to Router Component

Finally, you'll add the Shipping component to the Router component.

First, import the Shipping component at the top of the components/Router/index.tsx file:

1import { Shipping } from "../Shipping"

Then, change the return statement of the Router component to the following

1return (
2  <>
3    <Product handle={handle} isActive={activeTab === "product"} />
4    <Address handle={handle} isActive={activeTab === "address"} />
5    <Shipping handle={handle} isActive={activeTab === "shipping"} />
6  </>
7)

This will show the shipping method selection step and expand its details if activeTab is shipping.

Test it Out

While both the Aiminaabee application and the Aiminaabee Next.js storefront template are running, if you refresh the page you had opened or go to http://localhost:3000/sweatpants?step=shipping, you should see the Shipping step where you can choose a shipping method.

You can select a shipping option then click on the "Go to payment" button. The shipping method will be saved in the cart and the Shipping card will collapse to show the fourth step's details, which you'll add next.

Next: 10. Payment