Aiminaabee

Checkout Step 2: Set Shipping and Billing Addresses

Set shipping and billing addresses.

On this page

In this guide, you'll learn how to set the cart's shipping and billing addresses. This is step 2 of the five-step checkout. Keep the order in Checkout Overview. On Next.js, update the cart from a server action using _aiminaabee_cart_id.

Approaches to Set the Cart's Addresses

A cart has shipping and billing addresses that customers need to set. You can either:

This guide shows you how to implement both approaches. You can choose either or combine them, based on your use case.

Approach One: Address Form

The first approach to setting the cart's shipping and billing addresses is to show a form to the customer to enter their address details.

Then, to update the cart's address, use the Update Cart API route.

For example:

Tip: - This example uses the useCart hook defined in the Cart React Context guide.

React

tsx

tsxCopy
"use client" // include with Next.js 13+


  import { useState } from "react"
  import { useCart } from "@/providers/cart"
  import { sdk } from "@/lib/sdk"


  export default function CheckoutAddressStep() {
    const { cart, setCart } = useCart()
    const [loading, setLoading] = useState(false)
    const [firstName, setFirstName] = useState("")
    const [lastName, setLastName] = useState("")
    const [address1, setAddress1] = useState("")
    const [company, setCompany] = useState("")
    const [postalCode, setPostalCode] = useState("")
    const [city, setCity] = useState("")
    const [countryCode, setCountryCode] = useState("")
    const [province, setProvince] = useState("")
    const [phoneNumber, setPhoneNumber] = useState("")


    const updateAddress = (
      e: React.MouseEvent<HTMLButtonElement, MouseEvent>
    ) => {
      if (!cart) {
        return
      }


      e.preventDefault()
      setLoading(true)


      const address = {
        first_name: firstName,
        last_name: lastName,
        address_1: address1,
        company,
        postal_code: postalCode,
        city,
        country_code: countryCode || cart.region?.countries?.[0].iso_2,
        province,
        phone: phoneNumber,
      }


      sdk.store.cart.update("us", cart.id, {
        shipping_address: address,
        billing_address: address,
      })
      .then(({ cart: updatedCart }) => {
        setCart(updatedCart)
        console.log(updatedCart)
      })
      .finally(() => setLoading(false))
    }


    return (
      <form>
        {!cart && <span>Loading...</span>}
        <input
          type="text"
          placeholder="First Name"
          value={firstName}
          onChange={(e) => setFirstName(e.target.value)}
        />
        <input
          type="text"
          placeholder="Last Name"
          value={lastName}
          onChange={(e) => setLastName(e.target.value)}
        />
        <input
          type="text"
          placeholder="Address Line"
          value={address1}
          onChange={(e) => setAddress1(e.target.value)}
        />
        <input
          type="text"
          placeholder="Company"
          value={company}
          onChange={(e) => setCompany(e.target.value)}
        />
        <input
          type="text"
          placeholder="Postal Code"
          value={postalCode}
          onChange={(e) => setPostalCode(e.target.value)}
        />
        <input
          type="text"
          placeholder="City"
          value={city}
          onChange={(e) => setCity(e.target.value)}
        />
        <select
          value={countryCode}
          onChange={(e) => setCountryCode(e.target.value)}
        >
          {cart?.region?.countries?.map((country) => (
            <option
              key={country.iso_2}
              value={country.iso_2}
            >
              {country.display_name}
            </option>
          ))}
        </select>
        <input
          type="text"
          placeholder="Province"
          value={province}
          onChange={(e) => setProvince(e.target.value)}
        />
        <input
          type="tel"
          placeholder="Phone Number"
          value={phoneNumber}
          onChange={(e) => setPhoneNumber(e.target.value)}
        />
        <button
          disabled={!cart || loading}
          onClick={updateAddress}
        >
          Save
        </button>
      </form>
    )
  }

JS SDK

ts

tsCopy
const address = {
    first_name,
    last_name,
    address_1,
    company,
    postal_code,
    city,
    country_code,
    province,
    phone,
  }


  sdk.store.cart.update("us", cart.id, {
    shipping_address: address,
    billing_address: address,
  })
  .then(({ cart }) => {
    // use cart...
    console.log(cart)
  })

In the example above:

  • The same address is used for shipping and billing for simplicity. You can provide the option to enter both addresses instead.
  • You send the address to the Update Cart API route under the shipping_address and billing_address request body parameters.
  • The updated cart object is returned in the response.
  • React example: in the address, the chosen country must be in the cart's region. So, only the countries part of the cart's region are shown in the Country input.

Approach Two: Select Customer Address

The second approach to setting the cart's shipping and billing addresses is to allow the logged-in customer to select an address they added previously to their account.

To retrieve the logged-in customer's addresses, use the List Customer Addresses API route. Then, once the customer selects an address, use the Update Cart API route to update the cart's addresses.

Good to Know: A customer's address and a cart's address are represented by different data models in the Aiminaabee application, as they're managed by the Customer Module and the Cart Module, respectively. So, addresses that the customer used previously during checkout aren't automatically saved to their account. You need to save the customer's address using the Create Customer Address API route.

For example:

Tip: - This example uses the useCart hook defined in the Cart React Context guide.

React

tsx

tsxCopy
"use client" // include with Next.js 13+


import { useEffect, useState } from "react"
import { useCart } from "@/providers/cart"
import { useCustomer } from "@/providers/customer"
import { sdk } from "@/lib/sdk"


export default function CheckoutAddressStep() {
  const { cart, setCart } = useCart()
  const { customer } = useCustomer()
  const [loading, setLoading] = useState(false)
  const [selectedAddress, setSelectedAddress] = useState(customer?.addresses[0]?.id || "")


  useEffect(() => {
    if (!customer) {
      // TODO you can redirect here to another page or component that shows the address form
    }
    setSelectedAddress(customer?.addresses[0]?.id || "")
  }, [customer])


  const updateAddress = (
    e: React.MouseEvent<HTMLButtonElement, MouseEvent>
  ) => {
    e.preventDefault()


    const customerAddress = customer?.addresses.find((address) => address.id === selectedAddress)
    if (!cart || !customerAddress) {
      return
    }
    setLoading(true)


    const address = {
      first_name: customerAddress.first_name || "",
      last_name: customerAddress.last_name || "",
      address_1: customerAddress.address_1 || "",
      company: customerAddress.company || "",
      postal_code: customerAddress.postal_code || "",
      city: customerAddress.city || "",
      country_code: customerAddress.country_code || cart.region?.countries?.[0].iso_2,
      province: customerAddress.province || "",
      phone: customerAddress.phone || "",
    }


    sdk.store.cart.update("us", cart.id, {
      shipping_address: address,
      billing_address: address,
    })
    .then(({ cart: updatedCart }) => {
      setCart(updatedCart)
    })
    .finally(() => setLoading(false))
  }


  return (
    <form>
      {!cart && <span>Loading...</span>}
      {!customer?.addresses.length && <span>Customer doesn't have addresses</span>}
      <select value={selectedAddress} onChange={(e) => setSelectedAddress(e.target.value)}>
        {customer?.addresses.map((address) => (
          <option value={address.id} key={address.id}>{address.country_code}</option>
        ))}
      </select>
      <button
        disabled={!cart || loading || !selectedAddress}
        onClick={updateAddress}
      >
        Save
      </button>
    </form>
  )
}

JS SDK

ts

tsCopy
const retrieveCustomerAddresses = () => {
  sdk.store.customer.listAddress(storeCode)
  .then(({ addresses }) => {
    // use addresses...
    console.log(addresses)
  })
}


const updateCartAddress = (customerAddress: Record<string, unknown>) => {
  const address = {
      first_name: customerAddress.first_name || "",
      last_name: customerAddress.last_name || "",
      address_1: customerAddress.address_1 || "",
      company: customerAddress.company || "",
      postal_code: customerAddress.postal_code || "",
      city: customerAddress.city || "",
      country_code: customerAddress.country_code || cart.region?.countries?.[0].iso_2,
      province: customerAddress.province || "",
      phone: customerAddress.phone || "",
    }


    sdk.store.cart.update("us", cart.id, {
      shipping_address: address,
      billing_address: address,
    })
    .then(({ cart: updatedCart }) => {
      // use cart...
      console.log(cart)
    })
}

In the example above, you retrieve the customer's addresses and, when the customer selects an address, you update the cart's shipping and billing addresses with the selected address.

Tip: The JS SDK automatically sends an authenticated request as the logged-in customer as explained in the Login Customer guide. If you're using the Fetch API, you can either use credentials: include if the customer is already authenticated with a cookie session, or pass the Authorization Bearer token in the request's header.

In the React example, you use the Customer React Context to retrieve the logged-in customer, who has a list of addresses. You show a select input to select an address.

When the customer selects an address, you send a request to Update Cart API route passing the selected address as a shipping and billing address.