Subchapter 1.19

Checkout

reference/layouts/checkout.mdMarkdown23 KBView on GitHub

Checkout Page Layout

Checkout · Storefront Best Practices · medusajs/medusa-agent-skills · Skills Docs

┌─────────────────────────────────────────────────────────────────────┐
│                          CHECKOUT PROCESS                            │
└─────────────────────────────────────────────────────────────────────┘

    ┌──────────────────────────────────────────────────────┐
    │  Optional: Guest Checkout vs Login                   │
    │  • Guest: Enter email only                           │
    │  • Logged-in: Pre-fill saved data                    │
    └────────────────────┬─────────────────────────────────┘
                         │
                         ▼
    ┌──────────────────────────────────────────────────────┐
    │  STEP 1: Shipping Information                        │
    │  ├─ Contact: Email, Phone                            │
    │  ├─ Shipping Address: Name, Address, City, etc.      │
    │  └─ Billing Address: □ Same as shipping / Different  │
    └────────────────────┬─────────────────────────────────┘
                         │
                         ▼
    ┌──────────────────────────────────────────────────────┐
    │  STEP 2: Delivery                                    │
    │  • Fetch shipping methods from backend               │
    │  • Display: Standard, Express, Overnight             │
    │  • Show: Cost + Delivery estimate                    │
    │  • Update order total                                │
    └────────────────────┬─────────────────────────────────┘
                         │
                         ▼

// ALWAYS fetch payment providers from backend
// For Medusa:
const { payment_providers } = await sdk.store.payment.listPaymentProviders()

// For other backends:
// Change based on the integrated backend
const paymentMethods = await fetch(`${apiUrl}/payment-methods`)
// Returns: card, paypal, apple_pay, google_pay, stripe, etc.

// When user selects a provider
await sdk.store.payment.initiatePaymentSession(cart, {
  provider_id: selectedProvider.id // e.g., "pp_stripe_stripe", "pp_system_default"
})

// Re-fetch cart to get updated payment session data
const { cart: updatedCart } = await sdk.store.cart.retrieve(cart.id)

// After successful order placement
async function onOrderSuccess(order) {
  // 1. Clear cart state
  setCart(null) // or clearCart() from context

  // 2. Clear localStorage
  localStorage.removeItem('cart_id')

  // 3. Invalidate queries (if using TanStack Query)
  queryClient.invalidateQueries({ queryKey: ['cart'] })

  // 4. Redirect to confirmation
  router.push(`/order-confirmation/${order.id}`)
}

Not done: RECOMMENDED: Separate components created for each checkout step
Not done: Components: ShippingInformationStep, DeliveryMethodStep, PaymentInformationStep, OrderReviewStep
Not done: Decision made: Single-page or multi-step (based on complexity)
Not done: Guest checkout option (if backend supports it)
Not done: Email field first (if guest checkout)
Not done: Shipping address form with autocomplete attributes
Not done: “Billing same as shipping” checkbox (default checked)
Not done: Shipping methods fetched from backend dynamically
Not done: Shipping cost updates order total in real-time
Not done: CRITICAL: Payment methods fetched from backend (NEVER assume or hardcode)
Not done: CRITICAL: Payment method selection UI shown to user (user must select from available options)
Not done: Payment methods: show only enabled providers returned by backend
Not done: For Medusa: Payment session initialized after user selects provider (sdk.store.payment.initiatePaymentSession)
Not done: For Medusa: Country dropdown limited to cart’s region countries
Not done: Digital wallets prominent on mobile (Apple Pay, Google Pay)
Not done: Payment tokenization (never send raw card data)
Not done: Order review section before submission
Not done: Order summary sidebar (sticky on desktop, collapsible on mobile)
Not done: Promo code input (if not applied in cart)
Not done: Trust signals throughout (secure checkout, return policy)
Not done: Terms and conditions checkbox (if required)
Not done: Place Order button prominent (48-56px, shows total)
Not done: Loading state during payment processing
Not done: Progress indicator (if multi-step)
Not done: Clear error messages for validation failures
Not done: Error handling for payment failures (keep form data)
Not done: Stock availability check before order creation
Not done: Mobile optimized (44-48px touch targets, single column)
Not done: Autocomplete enabled on all form fields
Not done: Keyboard accessible (tab through fields, enter to submit)
Not done: ARIA labels on form fields (aria-required, aria-invalid)
Not done: Redirect to order confirmation on success
Not done: CRITICAL: Clear cart state after successful order (reset cart in Context/Zustand, remove cart ID from localStorage, invalidate cart queries)
Not done: Cart popup shows empty cart after order completion (not old items)

Checkout

Checkout Page Layout

Contents

Checkout

Checkout Page Layout

Contents

Overview

Key Requirements

Decision: Single-Page vs Multi-Step

Guest vs Logged-In Checkout

Component Architecture (RECOMMENDED)

Checkout Flow

Complete Checkout Flow Diagram

Key Ecommerce Considerations

Shipping Address Collection

Shipping Method Selection

Payment Method Selection

Order Review

Order Summary Sidebar

Backend Integration

Order Completion and Cart Cleanup (CRITICAL)

Mobile Checkout

Trust and Conversion Optimization

Error Handling

Checklist