Setting the file. One moment.
Account · Storefront Best Practices · medusajs/medusa-agent-skills · Skills Docs
Back to the top of the page Mcloud
Account pages allow customers to manage orders, save addresses, update preferences, and view order history. Well-designed account pages improve repeat purchase rates and reduce support inquiries.
Backend Integration (CRITICAL):
All customer data (orders, addresses, profile, payment methods) must be fetched from the ecommerce backend. Change this based on backend integrated. Never hardcode or mock account data. Consult backend documentation for:
Customer data endpoints (profile, preferences)
Order history and details endpoints
Address CRUD operations
Payment method storage (if supported)
Authentication requirements
Order history with status tracking (builds trust)
Saved addresses (checkout optimization - reduces friction)
Reorder functionality (increases repeat purchases)
Order tracking integration
Email preference controls (compliance and user control)
Secure authentication and session management
Primary ecommerce functions:
Reduce checkout friction (saved addresses, payment methods)
Increase repeat purchases (order history, reorder button)
Reduce support load (order tracking, self-service returns)
Build trust (order transparency, delivery updates)
Retain customers (easy account management)
Landing page after login. Purpose: Quick access to recent activity and common actions.
Display (prioritize recent orders):
Welcome message with customer name
Recent orders (3-5 most recent with status)
Quick actions: Track order, Reorder, Manage addresses
Account summary (saved addresses count, loyalty points)
Reorder functionality (CRITICAL for repeat purchases):
Check first that feature is available in the admin.
“Reorder” button on each order card
Adds same items to cart (check stock availability first)
Success feedback (cart updated with X items)
Don’t navigate away (stay on dashboard)
Display all past orders with filtering and search.
Order number (clickable to details page)
Order date and status badge (Processing, Shipped, Delivered)
Total amount
First 2-3 product thumbnails
Quick actions: Track, View Details, Reorder, Invoice
Status indicators (color-coded):
Processing: Yellow/Orange
Shipped: Blue
Delivered: Green
Cancelled: Gray/Red
Date range (Last 30 days, Last 6 months, All time)
Status filter (All, Processing, Shipped, Delivered)
Search by order number or product name
Most recent first (default)
Oldest first
Highest/lowest price
Pagination:
Show 10-20 orders per page with pagination controls. Alternative: “Load More” button (better mobile UX).
Full order information page.
Order number, date, status with progress timeline
Tracking number with carrier link (if shipped)
Estimated delivery date
Status timeline (builds trust):
Items ordered (image, name, variant, quantity, price)
Pricing breakdown (subtotal, shipping, tax, discounts, total)
Shipping address and method
Billing address
Payment method (last 4 digits)
Track shipment (link to carrier tracking page)
Download invoice/receipt (PDF)
Request return (if eligible and backend supports)
Reorder items
Contact support about order
Purpose : Increase repeat purchases by making it easy to reorder past purchases.
“Reorder” button on order cards and order details
Check stock availability before adding to cart
Handle discontinued products gracefully (skip or notify)
Add all available items to cart
Success message: “5 items added to cart” (or “3 of 5 items added - 2 unavailable”)
Stay on current page (don’t navigate away)
Tradeoff : Auto-add to cart (friction-free) vs redirect to cart page (let user review first). Recommend auto-add with clear success feedback.
Purpose (CRITICAL) : Reduce checkout friction and increase conversion. Saved addresses make repeat purchases faster and easier.
Saved addresses reduce checkout time by 50%+ (no retyping)
Default address selection streamlines checkout flow
Reduces form abandonment (fewer fields to fill)
Increases repeat purchase rate (easier checkout)
Backend integration:
Fetch, create, update, and delete addresses via backend API. Do this based on backend integrated.
All saved addresses
Default address indicator (badge: “Default Shipping” or star icon)
Address preview: Name, street, city, state, zip
Quick actions: Edit, Delete, Set as Default
Default address behavior:
One default shipping address
One default billing address (separate or same)
Used automatically at checkout (user can change)
Setting new default updates previous default
Collect standard shipping information. Key considerations:
Full name (or first + last)
Address line 1
City, State/Province, ZIP/Postal code
Country
Phone number (recommended for delivery coordination)
Address label (Home, Work) for easy identification
Address autocomplete API (Google Places) for accuracy
“Set as default” checkbox
Validation:
Real-time validation, especially for ZIP/postal code format based on country.
Note : Payment method storage is optional. Only implement if:
Backend securely handles tokenized payment data
PCI DSS compliance requirements are met
Payment gateway supports tokenization (Stripe, Braintree)
Never store full card numbers (tokenize with payment gateway)
Display last 4 digits only
Don’t store CVV
Use payment gateway hosted forms (Stripe Elements, etc.)
Show “Securely stored” badge for trust
Card type logo (Visa, Mastercard)
Last 4 digits
Expiration date
Default indicator
Actions: Edit (update expiration/billing address), Delete, Set as Default
Tradeoff : Saved payment methods increase convenience but require PCI compliance. If not implemented, users enter payment at checkout each time (more friction but simpler backend).
Display and edit customer information.
Full name
Email (with verification status)
Phone number
Optional: Date of birth, gender
Edit functionality:
Inline editing or separate form, real-time validation, success confirmation.
Email verification:
If unverified, show warning with “Resend verification email” button. If verified, show checkmark badge.
Require current password (optional)
New password with strength indicator
Confirm new password
Password requirements display (8+ chars, uppercase, number)
Two-factor authentication (optional):
Enable/disable 2FA, setup instructions, backup codes. Only implement if backend supports.
Ecommerce-specific email controls.
Transactional emails (order updates, shipping) - Recommended always enabled, may be legally requiredMarketing emails (sales, promotions, new products) - User choiceNewsletter (weekly roundup, content) - User choice Display:
Checkbox list or toggle switches with clear descriptions. Save button at bottom.
Unsubscribe:
Individual opt-outs per type, “Unsubscribe from all marketing” button. Keep transactional emails enabled (required for order fulfillment).
Choose based on account complexity:
Sidebar Navigation (Recommended):
Use when : 6+ account sections, complex account featuresDesktop: Vertical sidebar (20-25% width) with section links
Mobile: Collapse to hamburger menu or dropdown
Benefits: Persistent navigation, professional, accommodates many sections
Use when : 4-6 account sections, simpler account structureHorizontal tabs at top, active tab highlighted
Mobile: Horizontal scroll or dropdown
Benefits: Modern, clean, quick switching
Account Hub (Mobile-First):
Use when : Mobile-heavy traffic, simple accountLanding page with section cards (2-column grid)
Tap card to enter section, back button returns to hub
Benefits: Touch-friendly, intuitive, minimal hierarchy
Recommended order (most to least used):
Dashboard (landing page)
Orders (most accessed)
Addresses (important for checkout)
Payment Methods (if implemented)
Profile
Security
Email Preferences
Logout
Mobile-specific patterns:
Navigation:
Account hub with section cards (2 columns), or bottom navigation with 4-5 key sections (Orders, Addresses, Profile, More).
Forms:
One field per row, larger inputs (48px height), appropriate keyboard types (email, phone, numeric), autofill enabled.
Order history:
Simplified order cards, full-width buttons, “Load More” pagination (better than numbered pages on mobile).
Saved addresses:
Stacked address cards, full-width, 48px touch targets for edit/delete.
Not done: Account dashboard with recent orders (3-5)Not done: Reorder button (adds items to cart, stays on page)Not done: Order history with status indicatorsNot done: Filter orders by date range and statusNot done: Search orders by number or product nameNot done: Order details page with tracking infoNot done: Status timeline (Order Placed → Processing → Shipped → Delivered)Not done: Track shipment button (links to carrier)Not done: Download invoice/receipt optionNot done: Saved addresses list with default indicatorNot done: Add/edit/delete addresses with validationNot done: Set default address optionNot done: Profile information editNot done: Email verification status displayNot done: Password change with strength indicatorNot done: Current password required to change passwordNot done: Email preferences (transactional vs marketing)Not done: Account deletion optionNot done: Logout button clearly visibleNot done: Clear navigation between sectionsNot done: Mobile-responsive (single column, 48px touch targets)Not done: Backend integration (all data fetched from API)Not done: Success confirmations after savesNot done: Error handling with clear messagesNot done: Keyboard accessibleNot done: ARIA labels on navigation sectionsNot done: Order status announcements for screen readers
Not done: Saved payment methods (if PCI compliant backend)Not done: Two-factor authenticationNot done: Wishlist integrationNot done: Loyalty points/rewards displayNot done: Returns management sectionNot done: Address autocomplete API reference/layouts/account.md