Build a FastAPI Shopping Cart: A Step-by-Step Guide

Hey guys, let’s dive into building a FastAPI shopping cart ! If you’re looking to create a dynamic and efficient e-commerce backend, FastAPI is an awesome choice. It’s super fast, easy to learn, and comes with built-in data validation that will save you a ton of headaches. We’re going to walk through the entire process, from setting up your project to handling add-to-cart, view cart, and checkout functionalities. Get ready to level up your Python web development game!

Understanding the Core Components of a Shopping Cart

Before we jump into the code, let’s break down what exactly makes a shopping cart tick. At its heart, a shopping cart needs to manage a collection of items that a user intends to purchase. This involves several key operations: adding items , removing items , updating quantities , and finally, calculating the total cost . For a FastAPI shopping cart , we’ll be implementing these functionalities using Python and FastAPI’s elegant API design. Think of it like this: when a user browses your online store, they click ‘Add to Cart’. That action needs to be captured, stored somewhere, and then presented back to the user in a clear and organized way. The system needs to be able to handle multiple users simultaneously, each with their own independent cart. This means we need a way to associate carts with specific users, perhaps using session IDs or user authentication tokens. The items themselves will likely have details like product ID, name, price, and the quantity the user wants. When a user adds an item, we need to check if it’s already in the cart. If it is, we might just increase the quantity; if not, we add it as a new entry. Removing an item is straightforward – just delete it from the cart’s collection. Updating quantity is similar to adding, but with the possibility of reducing the count or setting it to zero to effectively remove it. Finally, the total cost is calculated by summing up the price of each item multiplied by its quantity. This might seem simple, but robustly handling edge cases like out-of-stock items or price changes requires careful planning. For our FastAPI shopping cart , we’ll aim for a clean and modular design, making it easy to extend later with features like discounts, shipping calculations, and payment gateway integrations. The goal is to create a flexible foundation that can grow with your e-commerce ambitions.

Setting Up Your FastAPI Project

First things first, let’s get our development environment set up for the FastAPI shopping cart . You’ll need Python installed, obviously! Then, we’ll use pip to install FastAPI and an ASGI server like uvicorn . Open your terminal and run:

pip install fastapi uvicorn[standard]

Now, let’s create a project directory and a main application file. We’ll call our main file main.py .

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

To run this, save the file and execute:

uvicorn main:app --reload

This command starts the server, and --reload is a lifesaver during development as it automatically restarts the server when you make changes. You can then visit http://127.0.0.1:8000 in your browser and see the “Hello World” message. Pretty neat, huh? This basic setup is the foundation for our FastAPI shopping cart . From here, we’ll add more routes and logic to handle our cart functionalities. We’re keeping things simple to start, but remember that for a real-world application, you’d likely want to structure your project more elaborately, perhaps with separate modules for models, routes, and services. This modular approach makes the codebase more organized and maintainable as your application grows. Think about how you want to organize your files: maybe a models directory for Pydantic models, a routers directory for your API endpoints, and a services directory for business logic. This initial setup, while minimal, is crucial for building a scalable FastAPI shopping cart . It ensures that we have a running application to test against as we add more features. The use of uvicorn as the ASGI server is standard practice for FastAPI applications, providing high performance and asynchronous capabilities, which are essential for handling concurrent user requests efficiently. The --reload flag is particularly useful for rapid iteration, allowing you to see the impact of your code changes almost instantaneously without manually restarting the server.

Defining Product and Cart Models

Next up, we need to define how our data will look. FastAPI uses Pydantic models for data validation and serialization. We’ll need a Product model and a CartItem model. Let’s add these to main.py or, better yet, in a separate models.py file for cleaner organization.

# models.py
from pydantic import BaseModel

class Product(BaseModel):
    id: int
    name: str
    price: float
    description: str | None = None

class CartItem(BaseModel):
    product_id: int
    quantity: int

These models define the structure of the data we’ll be working with. The Product model represents an item available for sale, and CartItem represents an item within a user’s cart, linking a product_id to a specific quantity . For our FastAPI shopping cart , these models are fundamental. They not only define the shape of our data but also enable FastAPI to automatically validate incoming request data and serialize outgoing responses. For instance, if a request body doesn’t match the CartItem schema (e.g., missing product_id or quantity is not an integer), FastAPI will automatically return a validation error. This built-in validation is a huge productivity booster. We’re keeping these models relatively simple for now. In a real-world scenario, you’d likely want to include more fields, such as image URLs, stock levels, or unique item variations (like size and color). The description field is marked as optional using str | None = None , meaning it can either be a string or None . This flexibility is often needed when dealing with product data where not all attributes might be mandatory. When designing your models, always think about the data your application will need to store and process. For the CartItem , we’re just storing the product_id and quantity . The actual product details (name, price, etc.) would typically be fetched from a database using the product_id when displaying the cart or calculating the total. This separation of concerns prevents data duplication and ensures that product information is always up-to-date. The use of Pydantic’s BaseModel is central to FastAPI’s magic, enabling automatic API documentation generation (like Swagger UI) and robust data handling. This initial model definition is a critical step in building our FastAPI shopping cart , laying the groundwork for all subsequent API interactions.

Simulating a Product Database

Since we’re focusing on the shopping cart logic, we’ll simulate a product database with some hardcoded data. In a real application, this would be a connection to a database like PostgreSQL or MongoDB.

# In main.py or a separate db.py

# Sample product data
products_db = {
    1: {"id": 1, "name": "Laptop", "price": 1200.00, "description": "High-performance laptop"},
    2: {"id": 2, "name": "Keyboard", "price": 75.00, "description": "Mechanical keyboard"},
    3: {"id": 3, "name": "Mouse", "price": 25.00, "description": "Ergonomic wireless mouse"},
}

def get_product_by_id(product_id: int) -> dict | None:
    return products_db.get(product_id)

This products_db dictionary acts as our temporary data store. The get_product_by_id function simulates fetching product details. This is a crucial part of our FastAPI shopping cart simulation, as we need product information to display in the cart and calculate costs. When a user adds an item, we’ll use the product_id to look up its details from this ‘database’. For instance, if a user adds product ID 1 to their cart, our get_product_by_id(1) function will return the laptop’s details, including its price. This price is essential for calculating the subtotal and total cost of items in the cart. In a production environment, this data would be dynamic and stored persistently. You might use SQLAlchemy to interact with a relational database like PostgreSQL or an ODM like Beanie for MongoDB. The key takeaway here is the separation of concerns: the shopping cart logic shouldn’t be bogged down with how product data is stored; it just needs a reliable way to access it. This simulation simplifies the setup for demonstration purposes, allowing us to focus on the cart’s API endpoints. We’ve structured it as a dictionary for easy lookup using the product ID as the key. This is efficient for small datasets. For larger databases, indexing would be critical. The functions like get_product_by_id provide a clean interface, abstracting away the underlying data storage mechanism. This makes our FastAPI shopping cart code more resilient to changes in the database implementation. It’s also important to consider how you’ll handle cases where a product ID doesn’t exist. Our current get_product_by_id function returns None in such cases, which our cart logic will need to handle gracefully, perhaps by returning an error to the user if they try to add a non-existent product. This simulation is a stepping stone, but a vital one, to building a functional FastAPI shopping cart .

Implementing Cart Storage (In-Memory)

For simplicity in this tutorial, we’ll store the shopping cart data in memory. This means the cart will be lost when the server restarts. For a persistent solution, you’d use a database or a cache like Redis.

# In main.py

# In-memory storage for carts (key: user_id, value: list of CartItem)
session_carts = {}

This session_carts dictionary will hold our shopping cart data. The keys will represent user sessions or IDs, and the values will be lists of CartItem objects. This is where the state of our FastAPI shopping cart lives. When a user adds an item, we’ll append it to the list associated with their session. When they view their cart, we’ll retrieve this list. It’s crucial to remember that this is an in-memory solution, suitable for learning and development but not for production. If the server restarts, all cart data will vanish. A more robust approach would involve using a database (like PostgreSQL, MySQL, or MongoDB) to store cart information persistently, or using a caching layer like Redis, which is often used for session management and temporary data storage in web applications. For each user session, we need a way to identify them. In a real application, this could be a JWT token, a session cookie, or an API key. For this example, we’ll use a placeholder user_id . When a request comes in, we’d extract this user_id and use it as the key to access or create their cart in session_carts . If a user_id doesn’t exist in session_carts , it means they don’t have an active cart, so we’d create a new entry for them. This dictionary structure is simple and effective for demonstrating the core FastAPI shopping cart logic. Each value in the session_carts dictionary will be a list of CartItem Pydantic objects. We’ll need logic to handle adding new items, updating quantities if an item already exists, and removing items. The in-memory approach allows us to focus purely on the FastAPI routing and Pydantic model interactions without the overhead of setting up a database. However, always keep in mind the limitations of in-memory storage for production environments. Properly managing user sessions and their associated cart data is fundamental to any e-commerce platform, and this simple dictionary is our first step towards that.

Creating API Endpoints for Cart Operations

Now for the fun part: defining the API endpoints using FastAPI! We’ll create endpoints for adding items, viewing the cart, and potentially removing items.

Add Item to Cart

Let’s create a POST endpoint to add items to the cart. We’ll need to specify the user_id and the CartItem data.

# In main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

# ... (Product model, CartItem model, products_db, get_product_by_id, session_carts defined above)


@app.post("/cart/add/{user_id}")
def add_to_cart(user_id: int, item: CartItem):
    product = get_product_by_id(item.product_id)
    if not product:
        raise HTTPException(status_code=404, detail="Product not found")

    if user_id not in session_carts:
        session_carts[user_id] = []

    # Check if item already in cart, update quantity if so
    found_item = None
    for cart_item in session_carts[user_id]:
        if cart_item.product_id == item.product_id:
            found_item = cart_item
            break

    if found_item:
        found_item.quantity += item.quantity
    else:
        session_carts[user_id].append(item)

    return {"message": "Item added to cart successfully", "cart": session_carts[user_id]}

This endpoint handles adding an item. It first checks if the product exists using our simulated database. If it does, it then checks if the user already has a cart. If not, it creates one. Crucially, it checks if the item is already in the cart and updates the quantity; otherwise, it appends the new item. This is a core function of our FastAPI shopping cart . The use of HTTPException is standard practice in FastAPI to return appropriate error responses to the client, such as a 404 if the product ID is invalid. The logic to check for existing items and update their quantities prevents duplicate entries for the same product and ensures that the quantity reflects the user’s latest action. This makes the user experience much smoother. Imagine adding the same T-shirt twice; you’d expect the quantity to go from 1 to 2, not have two separate entries for the same T-shirt. The Pydantic model CartItem ensures that the incoming item data is valid before it even reaches our logic. This endpoint is a great example of how FastAPI simplifies building robust APIs. For a real-world FastAPI shopping cart , you might want to add validation for the quantity (e.g., must be positive) or consider stock levels here. You’d also want to handle the user_id more securely, perhaps via authentication tokens rather than exposing it directly in the URL. But for demonstration, this POST endpoint gets the job done efficiently. The response includes a success message and the current state of the user’s cart, which is helpful for immediate feedback.

View Cart

Now, let’s add an endpoint to view the contents of a user’s cart.

# In main.py

@app.get("/cart/{user_id}")
def view_cart(user_id: int):
    if user_id not in session_carts or not session_carts[user_id]:
        return {"message": "Your cart is empty", "items": []}

    # Optionally, fetch full product details for display
    cart_items_with_details = []
    total_price = 0.0
    for item in session_carts[user_id]:
        product = get_product_by_id(item.product_id)
        if product:
            item_total = product["price"] * item.quantity
            cart_items_with_details.append({
                "product": product,
                "quantity": item.quantity,
                "item_total": item_total
            })
            total_price += item_total
        # Handle case where product might have been removed from DB after adding to cart
        # For now, we'll just skip it or log an error

    return {"user_id": user_id, "items": cart_items_with_details, "total_price": total_price}

This GET endpoint allows users to see what’s in their cart. It retrieves the cart data for the given user_id . If the cart is empty or the user doesn’t exist in our session_carts , it returns a friendly message. Importantly, this endpoint also demonstrates how to enrich the cart data by fetching full product details (name, price) from our simulated database using the product_id from the CartItem . It then calculates the subtotal for each item and the overall total_price . This richer output is much more useful for the frontend. Handling the scenario where a product might no longer exist in the products_db (perhaps it was removed after being added to the cart) is important for robustness. In this example, we simply skip such items. In a production FastAPI shopping cart , you might want to display a