Design an E-Commerce Shopping Cart and Order Flow

Learning Objectives#

• Learn the distinction that defines e-commerce: the cart is a session artifact, the order is a transaction, and conflating them is how systems oversell.
• Design the order placement as the single moment where stock is checked and committed, not the cart, where items can sit for days.
• Model the order as a state machine and see where idempotency, the guard against double-submission, belongs in the flow.

Introduction#

The shopping cart looks like a trivial case study: add things to a list, check out, done. The reality is that the cart is the single most mis-modeled object in e-commerce design, and the mistake is always the same one. Candidates put stock on the cart. The cart becomes the thing that knows how many units of an item are left, and the order becomes a copy of the cart. That design works until it does not: a cart can sit for a week while stock drains, and the moment of truth, whether the order can actually be filled, happens at checkout, not at add-to-cart. The cart is a wish list with prices frozen in time. The order is a transaction against current reality. The interview is whether you can keep those two apart, and place the one real concurrency checkpoint exactly where it belongs.

Requirements Gathering#

Functional requirements:

• A user adds items to a cart, changes quantities, and removes items, with the cart persisting across sessions.
• The cart shows line totals and a grand total based on the prices at the time of the calculation.
• Placing an order checks current stock for every line, reserves the units, records the total, and transitions through a defined order lifecycle.
• A user can see their past orders and each order's status.
• A cart item that becomes unavailable is flagged at checkout, not silently dropped.

Non-functional requirements:

• Order placement must be atomic: either every line is filled or none is, and the stock decrement and the order record happen together.
• Double-submitting a checkout must not create two orders.

Assumptions to state out loud: no promotions or coupon codes, no gift wrapping or shipping-cost modeling beyond a flat rate, no multiple currencies, and cart items hold a snapshot of the unit price. Cut promotions, cut shipping zones. The interviewer wants the cart-versus-order split and the checkout transaction, and both are clean only without a pricing engine on top.

Identifying Core Entities#

The entity list is where the case study is won, because the split the whole design depends on is visible in the list.

Notice the two services: InventoryService owns stock, OrderService owns the flow. The cart owns neither. A Cart with an InventoryService reference is a cart that has grown a responsibility it should not have.

Class Design#

CartItem holds a price snapshot. The snapshot is the design decision in miniature: the price shown in the cart is the price at the time the item was added or last viewed, and the order charges a separately captured price, so both can differ from the catalog price without either being "wrong."

public class CartItem {
    private final String productId;
    private int quantity;
    private final long unitPriceInCents; // snapshot

    public CartItem(String productId, int quantity, long unitPriceInCents) {
        this.productId = productId;
        this.quantity = quantity;
        this.unitPriceInCents = unitPriceInCents;
    }

    public void setQuantity(int quantity) { this.quantity = quantity; }
    public long getLineTotalInCents() { return unitPriceInCents * quantity; }
    public String getProductId() { return productId; }
    public int getQuantity() { return quantity; }
    public long getUnitPriceInCents() { return unitPriceInCents; }
}

Cart is a plain aggregation with a total, deliberately boring. The absence of stock logic in here is the point.

public class Cart {
    private final String cartId;
    private final Map<String, CartItem> items = new LinkedHashMap<>();

    public Cart(String cartId) { this.cartId = cartId; }

    public void addItem(String productId, int quantity, long unitPriceInCents) {
        CartItem existing = items.get(productId);
        if (existing != null) {
            existing.setQuantity(existing.getQuantity() + quantity);
        } else {
            items.put(productId, new CartItem(productId, quantity, unitPriceInCents));
        }
    }

    public void removeItem(String productId) { items.remove(productId); }

    public List<CartItem> getItems() { return new ArrayList<>(items.values()); }

    public long getTotalInCents() {
        return items.values().stream().mapToLong(CartItem::getLineTotalInCents).sum();
    }
}

Product carries current price and current stock, owned by the catalog side of the system. It is the thing the checkout checks against, and the thing the cart deliberately does not touch.

public class Product {
    private final String productId;
    private final String name;
    private final long currentPriceInCents;
    private final long currentStock;

    public Product(String productId, String name, long currentPriceInCents, long currentStock) {
        this.productId = productId;
        this.name = name;
        this.currentPriceInCents = currentPriceInCents;
        this.currentStock = currentStock;
    }

    public String getProductId() { return productId; }
    public long getCurrentPriceInCents() { return currentPriceInCents; }
    public long getCurrentStock() { return currentStock; }
}

InventoryService is the stock authority, and its reserve is the atomic check-and-apply from the inventory chapter, wearing a reservation hat. The reservation is a separate concept from a hard decrement: it holds stock for the brief payment window, then either converts to a decrement on success or returns on failure. If you have read the movie booking chapter, this is the seat hold again, renamed.

public class InventoryService {
    private final Map<String, Product> products = new ConcurrentHashMap<>();
    private final Map<String, Long> stock = new ConcurrentHashMap<>();

    public synchronized boolean reserve(Map<String, Integer> productQuantities) {
        for (Map.Entry<String, Integer> e : productQuantities.entrySet()) {
            long available = stock.getOrDefault(e.getKey(), 0L);
            if (available < e.getValue()) {
                return false;
            }
        }
        for (Map.Entry<String, Integer> e : productQuantities.entrySet()) {
            stock.merge(e.getKey(), -(long) e.getValue(), Long::sum);
        }
        return true;
    }
}

Order is the state machine and the transaction record. The transitions are the guard rails: an order is PENDING at creation, CONFIRMED after payment, and the idempotency key lives alongside it.

public class Order {
    public enum Status { PENDING, CONFIRMED, FAILED }

    private final String orderId;
    private final String userId;
    private final String idempotencyKey;
    private final List<OrderLine> lines;
    private final long totalInCents;
    private Status status;

    public Order(String orderId, String userId, String idempotencyKey,
                 List<OrderLine> lines, long totalInCents) {
        this.orderId = orderId;
        this.userId = userId;
        this.idempotencyKey = idempotencyKey;
        this.lines = lines;
        this.totalInCents = totalInCents;
        this.status = Status.PENDING;
    }

    public boolean confirm() {
        if (status != Status.PENDING) return false;
        status = Status.CONFIRMED;
        return true;
    }

    public boolean fail() {
        if (status != Status.PENDING) return false;
        status = Status.FAILED;
        return true;
    }
}

OrderService is the checkout flow, and the order of operations is the entire design: build the order, reserve stock, then charge. The reserve is what makes the flow atomic. Two checkouts of the last unit, only one reserve succeeds, and the loser's order is marked FAILED and its stock was never touched.

public class OrderService {
    private final InventoryService inventory;
    private final Map<String, Order> orders = new ConcurrentHashMap<>();
    private final Map<String, String> idempotencyStore = new ConcurrentHashMap<>();

    public Order placeOrder(Cart cart, String userId, String idempotencyKey) {
        if (idempotencyStore.containsKey(idempotencyKey)) {
            return orders.get(idempotencyStore.get(idempotencyKey));
        }

        Map<String, Integer> quantities = new HashMap<>();
        List<OrderLine> lines = new ArrayList<>();
        for (CartItem item : cart.getItems()) {
            quantities.put(item.getProductId(), item.getQuantity());
            lines.add(new OrderLine(item.getProductId(), item.getQuantity(),
                    item.getUnitPriceInCents()));
        }

        Order order = new Order(UUID.randomUUID().toString(), userId, idempotencyKey,
                lines, cart.getTotalInCents());

        if (!inventory.reserve(quantities)) {
            order.fail();
            orders.put(order.getOrderId(), order);
            return order;
        }

        order.confirm();
        orders.put(order.getOrderId(), order);
        idempotencyStore.put(idempotencyKey, order.getOrderId());
        return order;
    }
}