E-commerce Order Checkout Flow

User Story

As a customer
I want to complete my purchase by adding items to cart, providing shipping information, selecting a payment method, and confirming my order
So that I can successfully receive the products I want to buy

---

Acceptance Criteria

Scenario 1: Complete Checkout Flow - Successful Order (Happy Path)

Given I am a logged-in customer with items in my cart
And the items are in stock
When I navigate to checkout
And I enter valid shipping information (name, address, city, state, zip, phone)
And I select a payment method (credit card, debit card, or PayPal)
And I enter valid payment details
And I review my order summary
And I click “Confirm Order”
Then my payment is processed successfully
And I see an order confirmation page with order number
And I receive a confirmation email within 2 minutes
And my cart is emptied
And the order appears in my order history

---

Scenario 2: Add Multiple Items to Cart

Given I am browsing the product catalog
When I click “Add to Cart” on a product
Then the item is added to my cart
And the cart icon shows updated item count
And I see a confirmation message “Added to cart”
And I can continue shopping and add more items
And the cart preserves all items I’ve added

---

Scenario 3: Update Cart Before Checkout

Given I have items in my cart
When I view my cart
Then I can increase or decrease quantities for each item
And I can remove items from my cart
And the subtotal updates automatically
And the tax and total recalculate based on changes

---

Scenario 4: Shipping Information - Required Fields Validation

Given I am at the shipping information step
When I attempt to proceed without filling required fields
Then I see inline validation errors on empty required fields
And the error message shows “This field is required” for each missing field
And I cannot proceed to payment selection until all required fields are filled

---

Scenario 5: Shipping Information - Address Validation

Given I am entering shipping information
When I enter an invalid zip code format
Then I see an error “Please enter a valid 5-digit zip code”
When I enter an invalid phone number format
Then I see an error “Please enter a valid 10-digit phone number”

---

Scenario 6: Shipping Information - State and City Validation

Given I am entering shipping information
When I select a state
Then the city field validates against valid cities in that state
When I enter a city that doesn’t exist in the selected state
Then I see suggestion “Did you mean [suggested city]?” or “City not found in [state]”

---

Scenario 7: Save Multiple Shipping Addresses

Given I am a registered user
When I enter a new shipping address
Then I have option to save it to my address book
And on future checkouts, I can select from saved addresses
And I can set a default shipping address

---

Scenario 8: Payment Method Selection

Given I have completed shipping information
When I proceed to payment
Then I see available payment options (credit card, debit card, PayPal)
And I can select one payment method
And the appropriate form fields appear based on my selection

---

Scenario 9: Credit Card Validation - Required Fields

Given I have selected credit card as payment method
When I attempt to proceed without filling card details
Then I see validation errors for required fields (card number, expiration, CVV, cardholder name)
And I cannot proceed until all fields are valid

---

Scenario 10: Credit Card Validation - Card Number Format

Given I am entering credit card information
When I enter an invalid card number (wrong length, invalid Luhn checksum)
Then I see error “Invalid card number”
When I enter a valid card number
Then the card type is detected automatically (Visa, Mastercard, Amex, Discover)
And the card type icon is displayed

---

Scenario 11: Credit Card Validation - Expiration Date

Given I am entering credit card information
When I enter an expiration date in the past
Then I see error “Card has expired”
When I enter an invalid month (> 12 or < 1)
Then I see error “Invalid expiration date”

---

Scenario 12: Credit Card Validation - CVV

Given I am entering credit card information
When I enter a CVV with wrong length (< 3 digits for Visa/MC, < 4 for Amex)
Then I see error “CVV must be 3 digits” (or “4 digits for American Express”)

---

Scenario 13: Save Payment Method for Future Use

Given I am a registered user entering payment information
When I check “Save this payment method for future purchases”
And I complete the order
Then the payment method is securely saved to my account
And on future checkouts, I can select from saved payment methods
And only the last 4 digits of saved cards are displayed

---

Scenario 14: Order Summary Review

Given I am at the final review step
When I view the order summary
Then I see all items with quantities and prices
And I see shipping address
And I see payment method (last 4 digits if card)
And I see itemized costs: subtotal, tax, shipping, total
And I can edit shipping or payment by clicking “Edit” links

---

Scenario 15: Apply Discount Code

Given I am reviewing my order
When I enter a valid discount code
And I click “Apply”
Then the discount is applied to the subtotal
And the total is recalculated
And I see the discount amount displayed as line item
When I enter an invalid or expired discount code
Then I see error “Invalid discount code” or “This code has expired”

---

Scenario 16: Inventory Check Before Checkout

Given I have items in my cart
When I proceed to checkout
Then the system verifies inventory availability
When an item is no longer in stock
Then I see a warning “Some items are no longer available”
And out-of-stock items are highlighted in my cart
And I can remove them or return to shopping

---

Scenario 17: Inventory Check - Concurrent Purchase (Race Condition)

Given I have an item in my cart that is the last one in stock
And another customer adds the same item to their cart simultaneously
When the other customer completes checkout first
And I attempt to complete checkout
Then I see an error “Sorry, [item name] is no longer available”
And the item is removed from my cart
And the order total is recalculated
And I can proceed with remaining items or cancel

---

Scenario 18: Payment Processing Failure

Given I have submitted my order for payment
When the payment gateway declines the transaction
Then I see error message “Payment declined. Please check your payment information and try again.”
And my order is not created
And my cart is preserved with all items
And I can retry with a different payment method

---

Scenario 19: Payment Processing - Network Timeout

Given I have submitted my order for payment
When the payment gateway times out or is unresponsive
Then I see error “Payment processing timed out. Please try again.”
And the system does not create duplicate orders
And I am provided a “Retry” button
And if uncertain whether payment succeeded, I see “Your order may still be processing. Check your email or order history in 5 minutes.”

---

Scenario 20: Loading State During Payment Processing

Given I have clicked “Confirm Order”
When the payment is being processed
Then I see a loading spinner or progress indicator
And I see message “Processing payment… Please do not refresh or close this page.”
And the “Confirm Order” button is disabled to prevent double submission

---

Scenario 21: Guest Checkout

Given I am not logged in
When I proceed to checkout
Then I am given option to “Checkout as Guest” or “Sign In”
When I select “Checkout as Guest”
Then I can complete checkout by providing email, shipping, and payment
And I receive order confirmation at the provided email
And I am optionally prompted to create an account after checkout

---

Scenario 22: Empty Cart Checkout Prevention

Given my cart is empty
When I attempt to navigate to checkout
Then I am redirected to the cart page
And I see message “Your cart is empty”
And I see a “Continue Shopping” button

---

Scenario 23: Session Timeout During Checkout

Given I am in the middle of checkout
When my session expires after 30 minutes of inactivity
And I attempt to proceed to the next step
Then I see message “Your session has expired. Please log in to continue.”
And my cart contents are preserved
And after logging in, I can resume checkout from where I left off

---

Scenario 24: Edit Shipping Address After Selection

Given I am at the payment step
And I have already entered shipping information
When I click “Edit Shipping Address”
Then I am taken back to the shipping step
And my previously entered information is pre-filled
And I can make changes
And after saving, I return to the payment step

---

Scenario 25: Edit Payment Method After Selection

Given I am at the order review step
And I have already entered payment information
When I click “Edit Payment Method”
Then I am taken back to the payment step
And my previously selected payment method is pre-selected
And I can change to a different method
And after saving, I return to the review step

---

Scenario 26: Tax Calculation Based on Shipping Address

Given I am at checkout
When I enter a shipping address in a state with sales tax
Then the tax amount is calculated based on the state tax rate
And the tax is displayed as a line item
When I change the shipping address to a different state
Then the tax recalculates automatically
And the order total updates

---

Scenario 27: Shipping Cost Calculation

Given I have entered a shipping address
When the system calculates shipping cost
Then I see shipping options (standard, express, overnight) with costs
And I can select my preferred shipping method
When I change shipping method
Then the total recalculates to include new shipping cost

---

Scenario 28: Free Shipping Threshold

Given the store offers free shipping on orders over $50
When my cart total is $48
Then I see message “Add $2 more for free shipping”
When I add items to reach $50
Then the shipping cost becomes $0
And I see “Free shipping applied”

---

Scenario 29: Browser Back Button During Checkout

Given I am on the payment step of checkout
When I click the browser back button
Then I am taken to the previous step (shipping information)
And my previously entered data is preserved
And I can navigate forward again without data loss

---

Scenario 30: Prevent Double Order Submission

Given I am on the order review page
When I click “Confirm Order”
Then the button is immediately disabled
And I see a processing indicator
When I try to click the button again or refresh the page
Then the system prevents duplicate order creation
And only one order is submitted

---

Non-Functional Requirements

Performance

• Cart operations (add, update, remove) complete in < 500ms
• Checkout page loads in < 2 seconds
• Payment processing completes within 10 seconds
• Tax and shipping calculations update within 1 second of address change
• Page transitions between checkout steps are instant (< 200ms)

Security

• All payment data transmitted over HTTPS
• Credit card numbers are never stored on client-side or server-side (tokenized via payment gateway)
• CVV is never stored, even temporarily
• PCI DSS compliance for payment handling
• Shipping and billing addresses encrypted at rest
• Rate limiting on checkout API to prevent abuse (max 10 checkout attempts per user per hour)
• CSRF protection on all checkout forms
• Payment gateway tokens expire after 15 minutes

Accessibility

• Full keyboard navigation through entire checkout flow
• Screen reader announces each step, errors, and confirmations
• Proper ARIA labels on all form fields
• Error messages associated with form fields via aria-describedby
• Focus management between steps
• Color contrast meets WCAG AA standards
• Form field labels clearly visible

Browser Compatibility

• Support modern browsers: Chrome (latest 2 versions), Firefox (latest 2 versions), Safari (latest 2 versions), Edge (latest 2 versions)
• Mobile browsers: iOS Safari, Chrome Mobile, Samsung Internet
• Progressive enhancement: checkout works with JavaScript disabled (server-side rendering)

Data Integrity

• Inventory reserved when customer proceeds to payment (5-minute hold)
• Atomic transaction: payment success must guarantee order creation
• Order numbers are unique and sequential
• Audit trail for all checkout events (cart modifications, payment attempts, order creation)
• Cart state persisted in database for logged-in users (synced across devices)

Concurrency

• Optimistic locking on inventory to handle concurrent purchases
• Order confirmation emails sent asynchronously (don’t block checkout)
• Prevent race conditions on final inventory check before payment

---

Edge Cases to Consider

1. User abandons cart mid-checkout - Save progress for logged-in users
2. Multiple tabs open - Cart syncs across tabs for logged-in users
3. Very long address strings - Truncate or show validation for max character limits
4. International addresses - Support non-US addresses if applicable (optional fields like state)
5. Special characters in name/address - Allow apostrophes, hyphens, accented characters
6. Minimum order amount - If business requires minimum (e.g., $10), enforce and display message
7. Maximum order amount - If fraud prevention requires max (e.g., $10,000), enforce and notify
8. Cart expiration - Items added to cart may change price or go out of stock after days/weeks
9. Order cancellation immediately after submission - Provide time window for cancellation (e.g., 5 minutes)
10. User changes mind on shipping address after order placement - Allow modification before shipment
11. Partial refunds - If some items unavailable after order placement
12. Gift purchases - Option to ship to different address, include gift message
13. Saved payment method deleted by payment provider - Gracefully handle and prompt for new payment
14. User tries to checkout with saved address from deleted account
15. PayPal redirect fails or user cancels - Return to checkout with cart preserved

---

Definition of Done

• Users can add items to cart with quantity selection
• Cart persists for logged-in users across sessions
• Cart updates (quantity change, item removal) work correctly
• Shipping information form validates all required fields
• Address validation (zip, phone, state/city) implemented
• Users can save shipping addresses to address book
• Payment method selection (credit card, debit card, PayPal) available
• Credit card validation (number, expiration, CVV, cardholder name) implemented
• Card type auto-detection works (Visa, Mastercard, Amex, Discover)
• Users can save payment methods (securely tokenized)
• Order summary displays all details (items, shipping, payment, costs)
• Tax calculation based on shipping address implemented
• Shipping cost calculation with multiple options available
• Discount code application and validation works
• Inventory check prevents checkout of out-of-stock items
• Concurrent purchase race condition handled (inventory reservation)
• Payment processing integration with gateway complete
• Payment failure and timeout error handling implemented
• Order confirmation page displays order number
• Confirmation email sent within 2 minutes
• Guest checkout flow works without registration
• Empty cart redirects to cart page
• Session timeout preserves cart and allows resume
• Edit shipping/payment from review step works
• Browser back button navigation preserves data
• Double submission prevention implemented
• All validation scenarios pass automated tests
• Error handling for network failures, server errors tested
• Security review passed (PCI DSS compliance for payment handling)
• Accessibility review passed (WCAG AA compliance)
• Performance benchmarks met (< 2s page load, < 500ms cart operations)
• Cross-browser testing complete (Chrome, Firefox, Safari, Edge)
• Mobile responsive design tested on iOS and Android

---

Technical Notes

Suggested Implementation:

Frontend (Multi-step Form)

• Use state management (Redux, Context API, or Vuex) to track checkout progress
• Implement client-side validation with real-time feedback
• Debounce tax/shipping recalculation to avoid excessive API calls
• Save checkout state to localStorage for guest users, database for logged-in users
• Implement route guards to prevent skipping steps

Backend API Endpoints

• POST /api/cart/items - Add item to cart
• PUT /api/cart/items/:id - Update cart item quantity
• DELETE /api/cart/items/:id - Remove item from cart
• GET /api/cart - Retrieve current cart
• POST /api/checkout/shipping - Save shipping information
• POST /api/checkout/payment - Save payment method
• POST /api/checkout/validate-inventory - Pre-flight inventory check
• POST /api/checkout/calculate-tax - Calculate tax based on address
• POST /api/checkout/calculate-shipping - Calculate shipping cost
• POST /api/checkout/apply-discount - Validate and apply discount code
• POST /api/orders - Create order and process payment

Payment Integration

• Use Stripe, PayPal, or Square for tokenized payment processing
• Never store raw credit card numbers - use payment gateway tokens
• Implement webhook handlers for asynchronous payment confirmations
• Use idempotency keys to prevent duplicate charges

Database Schema

• carts table with user_id, session_id (for guests), created_at, updated_at
• cart_items table with cart_id, product_id, quantity, price_snapshot
• orders table with user_id, order_number, status, shipping_address_id, payment_method_id, subtotal, tax, shipping_cost, discount, total
• order_items table with order_id, product_id, quantity, price
• shipping_addresses table with user_id, name, address_line_1, address_line_2, city, state, zip, phone, is_default
• payment_methods table with user_id, gateway_token, card_last4, card_brand, expiration_month, expiration_year, is_default

Inventory Handling

• Implement optimistic locking with version numbers on product inventory
• Reserve inventory when user reaches payment step (5-minute TTL)
• Release reservation if checkout abandoned or payment fails
• Handle race conditions with database transactions and row-level locking