Medusa Next.js Checkout Fails? Check the Cart State First
Your Medusa product page works, yet checkout returns an error nobody can reproduce. The failing step is rarely checkout itself; it is usually the earlier cart. In Medusa, the cart carries region, addresses, shipping, an
Your Medusa product page works, yet checkout returns an error nobody can reproduce. The failing step is rarely checkout itself; it is usually the earlier cart.
In Medusa, the cart carries region, addresses, shipping, and payment state. Next.js should only render that state, never guess or rebuild it. This article follows one cart through checkout and shows where state breaks.
What does a Medusa cart actually store?
A Medusa cart is more than a basket of variant IDs. It also stores a region, currency, email, and both addresses. Shipping methods and payment sessions are attached to it later in checkout.
Later steps depend on earlier ones, so call order matters. A request without region context may not return the price you expect. Shipping options come from a specific cart, not the whole store.
Where should the cart ID live in Next.js?
Every later call needs the cart ID, so it must persist. Medusaβs Next.js starter stores the cart ID in a cookie. A cookie also lets Server Components read the cart during rendering.
Pick one storage method and read it through one helper. Two code paths reading different storage can quietly create two carts. Shoppers then see an empty cart after moving between pages.
When does a payment session get created?
Selecting a payment provider in the interface does not charge the customer. Medusa creates a payment collection on the cart if needed. The chosen provider is then represented by a payment session.
For Stripe, the session data holds the client secret for Stripeβs components. Card details go directly to Stripe, not to your backend. Complete the cart only after Stripe confirms the customerβs payment step.
How should the app handle cart completion?
Calling the complete method does not guarantee that an order exists. The response includes a type field that your code must check. A type of _order _ means success; a type of cart means failure.
const result = await sdk.store.cart.complete(cartId)
if (result.type === "order") {
clearCartId() // your own helper
redirect(`/order/${result.order.id}/confirmed`)
}
// type === "cart": completion failed, so keep the cart
return { error: "Checkout failed. Please review your details." }
This sketch is untested, and it omits imports and error handling. Verify the response shape against the current Complete Cart documentation. Also disable the order button while the request is running.
Provider payment status and Medusa order creation are separate events. Never show a confirmation page based only on a finished button click. Show it only after Medusa returns a response with type order.
Which symptom points to which cart step?
Treat these symptoms as starting points rather than universal diagnoses. Inspect the Store API response before changing any interface code. The response usually shows which cart field is missing or wrong.
Where does the Next.js responsibility end?
Next.js should display commerce state instead of replacing backend validation. A total on screen is a rendering of Medusaβs calculation. When the two disagree, trust the latest cart response from Medusa.
Store requests use a publishable key, which is not an Admin secret. Admin credentials never belong in storefront code or public environment variables. The key also limits which sales channels a request can see.
A step-by-step Medusa Next.js storefront walkthrough covers products, carts, and shipping. That article also explains publishable keys, regions, and sales channels. This post focuses on how cart state breaks between those steps.
What should you verify before shipping?
Many checkout failures trace back to lost or invalid cart state. Verify region, cart persistence, shipping options, and payment sessions first. Then confirm that only a type of order shows confirmation.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.