medusa-checkout-address-logic

Checkout address step logic for Medusa storefronts:

• Guest: shipping/billing form, email (and optional phone), sameAsBilling.
• Customer: saved address list, radio-style selection, optional add/edit modal that wires to your customer-address + cart flow.

Checkout still runs on cart addresses: the hook builds a CheckoutAddressCartPayload (shipping_address, billing_address, and email for guests). Your app connects onSetAddresses to setAddresses, Medusa cart update, or a server action—same pattern as other packages in this repo.

Installation

npm install
npm run build

For consumers (npm or file:), depend on the built dist output from this package’s exports.

Quick usage

• Pass mode: "guest" or "customer".
• Implement onSetAddresses (required): persist addresses + guest email onto the cart.
• Optionally implement checkCustomerEmailRegistered + onGuestEmailRequiresLogin for guest “email already has an account → sign in”.
• Optionally implement onSaveCustomerAddress for the add/edit address modal (customer address book + cart).
• Optionally implement checkDeliveryServiceability (e.g. Shiprocket via your backend). If omitted, no delivery check runs and submitContinue is unchanged.

Customer mode: selectedAddressId and initialSelectedAddressId

Saved lists are often rebuilt as a new array reference on each parent render (same rows). The hook syncs selection like this:

1. If initialSelectedAddressId changed (cart/server) and that id exists in the list → selection follows it.
2. Else if the user’s current selection is still in the list → keep it (avoids resetting when only the array reference changed).
3. Else if initialSelectedAddressId is present in the list → use it.
4. Else → default (prefer is_default, otherwise first address).

So: controlled sync from cart when the id really changes, without wiping the user’s pick on harmless re-renders.

Optional delivery serviceability (Shiprocket, etc.)

When checkDeliveryServiceability is provided:

• submitContinue runs a check (by postal code + optional country/city/province from the active shipping address) before calling onSetAddresses. If not serviceable, continue is blocked and error / serviceabilityError are set.
• Exposed helpers: checkServiceability, serviceabilityStatus, serviceability, clearServiceability.

When the callback is omitted, none of that runs; the hook behaves as a pure address + cart submit orchestrator.

Serviceability state is cleared when the address inputs that affect the check change (so stale “deliverable” results are not kept).

useCheckoutAddressStep options (summary)

| Option | Role | |--------|------| | mode | "guest" | "customer" | | initialGuestShipping, initialGuestBilling, initialEmail, initialGuestPhone, initialSameAsBilling | Guest defaults | | savedAddresses, regionCountryCodes, initialSelectedAddressId | Customer list + optional country filter + cart-selected id | | onSetAddresses | Required. Cart update from normalized payload | | checkCustomerEmailRegistered, onGuestEmailRequiresLogin | Guest email guard | | onSaveCustomerAddress, onAfterCustomerAddressSave | Customer modal save + refresh hook | | checkDeliveryServiceability | Optional delivery PIN / serviceability |

Return value (summary)

• State: isSubmitting, error, clearError, sameAsBilling, setSameAsBilling
• Guest: guestShipping, guestBilling, guestEmail, guestPhone, setters
• Customer: visibleSavedAddresses, selectedAddressId, selectAddress, customerBillingSeparate, setCustomerBillingSeparate
• Modal: modalOpen, modalOperation, modalEditingId, modalDraft, modalLabel, open/close/setters, submitAddressModal
• Serviceability: serviceabilityStatus, serviceability, serviceabilityError, checkServiceability, clearServiceability
• submitContinue: validate → optional email check → optional serviceability → onSetAddresses

Exports

• useCheckoutAddressStep and related option/result types (UseCheckoutAddressStepOptions, UseCheckoutAddressStepResult, CustomerAddressModalSaveInput, …)
• Payload helpers: buildGuestCartPayload, buildCustomerCartPayloadFromSaved, validateCheckoutCartAddress, filterSavedAddressesByRegionCountries, …
• Types: CheckoutAddressCartPayload, CheckoutCartAddress, SavedCheckoutAddress, CheckoutServiceabilityCheckInput, CheckoutServiceabilityResult, CheckoutServiceabilityStatus, …

Notes

• No Shiprocket (or other provider) dependency is bundled: pass a callback that calls your API route with secrets server-side.
• UI (forms, cards, modals, price summary) stays in your storefront; this package is logic + payload shaping only.