This is the first of a two-part series using Django, htmx, and Stripe to create a one-product e-commerce website. In this part, we'll start our Django project and integrate it with htmx.
In the second part, we'll handle the orders with Stripe.
Let's get going!
Why Django, htmx, and Stripe?
We'll be using Django, htmx, and Stripe to create our website because:
- Django is a Python web framework with a great ORM, templating, and routing system. It has a few features straight out of the box (like authentication) and multiple open source packages available online. We will use Django to build the website.
- htmx is a JavaScript library that gives your website a modern feel just by using html attributes — you don’t actually have to write any JavaScript (although you can, of course). We will use htmx to give some interactivity to our page.
- Stripe is a payments platform with a great API — it handles payments and credit card information. It also integrates nicely with Google and Apple Pay. We will use Stripe to facilitate product payments.
Here’s how the final product will work:
- A user goes to our website and is able to see some information about our product, including its price and description.
- Once the user clicks the “buy” button, they are redirected to Stripe’s checkout session.
- If the payment is successful, they are redirected to our website again. We save their order information and send a confirmation email to the customer and all staff users to notify them of the recent purchase.
Now let's configure our Django project, create the initial views, and build the purchase form with htmx.
Configure Your Django Python Project
To set up our project, we need to create a virtual environment, activate it, and install the required packages. We can then create our Django project and Django app.
Create a Virtual Environment
Let's start by creating a virtual environment, so we can isolate our dependencies:
python -m venv .venv
Here's how we activate it on Linux/Mac:
source .venv/bin/activate
And on Windows:
.venv\Scripts\activate
Install the Required Packages
Within our activated virtual environment, we need a few packages to make this work:
pip install django stripe django-htmx python-dotenv
Here, we have installed:
- Django
- Stripe to work with the stripe API.
- django-htmx, which provides some helper functionality to work with htmx.
- python-dotenv to load environment variables from
.envfiles.
Create the Django Project
In the same directory as our virtual environment, let's create a Django project called ecommerce_site:
django-admin startproject ecommerce_site .
In Django, it's good practice to have code organized by one or more "apps". Each app is a package that does something in particular. A project can have multiple apps, but for this simple shop, we can just have one app that will have most of the code — the views, forms, and models for our e-commerce platform. Let's create it and call it ecommerce:
python manage.py startapp ecommerce
And add this app to our INSTALLED_APPS in ecommerce_site/settings.py:
# ecommerce_site/settings.py INSTALLED_APPS = [ # ... the default django apps "ecommerce", # ⬅️ new ]
If you’re having trouble with this setup, check out the final product. At this stage, your file structure should look something like this:
ecommerce_site/ ├── .venv/ # ⬅️ the virtual environment ├── ecommerce_site/ # ⬅️ the django project configuration │ ├── __init__.py │ ├── asgi.py │ ├── settings.py │ ├── urls.py │ └── wsgi.py ├── ecommerce/ # ⬅️ our app setup │ ├── templates/ │ ├── __init__.py │ ├── admin.py │ ├── apps.py │ ├── models.py │ ├── tests.py │ └── views.py └── manage.py
Create the Templates
Now that we have our project configured, we need to create some base layouts. In the templates directory, add a base.html file — the template that all other templates will inherit from. Add htmx for user interaction, mvp.css for basic styling, and Django generated messages to the template:
<!-- ecommerce/templates/base.html --> <!DOCTYPE html> <html lang="en"> <head> <title>One-Product E-commerce Site</title> <!-- include htmx ⬇️ --> <script src="https://unpkg.com/htmx.org@1.9.11" integrity="sha384-0gxUXCCR8yv9FM2b+U3FDbsKthCI66oH5IA9fHppQq9DDMHuMauqq1ZHBpJxQ0J0" crossorigin="anonymous" ></script> <!-- include mvp.css ⬇️ --> <link rel="stylesheet" href="https://unpkg.com/mvp.css" /> </head> <body hx-headers='{"X-CSRFToken": "{{ csrf_token }}"}' hx-boost="true"> <header> <h1>One-Product E-commerce Site</h1> </header> <main> <section> {% if messages %} {% for message in messages %} <p><mark>{{ message }}</mark></p> {% endfor %} {% endif %} </section> {% block content %} {% endblock %} </main> </body> </html>
Create a home.html template in the same templates directory, for our home view. It should extend the base.html and just populate its content section.
<!-- ecommerce/templates/home.html --> {% extends "base.html" %} {% block content %} <section>{% include "product.html" %}</section> {% endblock %}
In this template, we have included the product.html template. product.html will render some details about our product and a placeholder image. Let’s create it in the same templates directory:
<!-- ecommerce/templates/product.html --> <form> <img src="https://picsum.photos/id/30/400/250" alt="mug" /> <h3>mug<sup>on sale!</sup></h3> <p>mugs are great - you can drink coffee on them!</p> <p><strong>5€</strong></p> <button type="submit" id="submit-btn">Buy</button> </form>
Create the Home View
In ecommerce/views.py, we'll create the view that will render the home template:
# ecommerce/views.py from django.shortcuts import render def home(request): return render(request, 'home.html')
And add it to the urlpatterns in ecommerce_site/urls.py:
# ecommerce_site/urls.py from django.contrib import admin from django.urls import path from ecommerce import views # ⬅️ new urlpatterns = [ path("admin/", admin.site.urls), path("", views.home, name="home"), # ⬅️ new ]
Now we can run the server with:
python manage.py runserver
If you jump over to http://127.0.0.1:8000 in your browser, you should see something like this:
It might feel like overkill to add a dedicated product.html template instead of just the product details in the home.html template, but product.html will be useful for the htmx integration.
Add the Form and Use Htmx
Great! We now have a view that looks good. However, it doesn’t do much yet. We'll add a form and set up the logic to process our product purchase. Here’s what we want to do:
- Allow the user to select how many products (mugs) they want to buy.
- When the user clicks “Buy”, make a POST request to a different view called
purchasein the backend usinghx-post. - In that view, validate the form and wait for 2 seconds to simulate the Stripe integration (we'll cover this in the second part of this guide).
- Replace the form content with the
purchaseview response. - While the order is processing, show a loading message and disable the “Buy” button, so that the user doesn’t accidentally make multiple orders.
Let's go step by step.
1: Add a Quantity Order Form
Let’s first create and add a simple order form to our view allowing a user to select the number of mugs they want. In ecommerce/forms.py, add the following code:
# ecommerce/forms.py from django import forms class OrderForm(forms.Form): quantity = forms.IntegerField(min_value=1, max_value=10, initial=1)
In ecommerce/views.py, we can initialize the form in the home view:
# ecommerce/views.py from ecommerce.forms import OrderForm # ⬅️ new def home(request): form = OrderForm() # ⬅️ new - initialize the form return render(request, "home.html", {"form": form}) # ⬅️ new - pass the form to the template
And render it in the template:
<!-- ecommerce/templates/product.html --> <form method="post"> <!-- Same product details as before, hidden for simplicity --> <!-- render the form fields ⬇️ --> {{ form }} <!-- the same submit button as before ⬇️ --> <button type="submit" id="submit-btn">Buy</button> </form>
2: Make a POST Request To a Different View
When the user clicks "Buy", we want to process the corresponding POST request in a dedicated view to separate the different logic of our application. We will use htmx to make this request. In the same ecommerce/templates/product.html template, let's extend the form attributes:
<!-- ecommerce/templates/product.html --> <!-- add the hx-post html attribute ⬇️ --> <form method="post" hx-post="{% url 'purchase' %}"> <!-- Same product details as before, hidden for simplicity --> {{ form }} <button type="submit" id="submit-btn">Buy</button> </form>
With this attribute, htmx will make a POST request to the purchase endpoint and stop the page from reloading completely. Now we just need to add the endpoint.
3: Create the Purchase View
The purchase view can be relatively simple for now:
# ecommerce/views.py import time # ⬅️ new # new purchase POST request view ⬇️ @require_POST def purchase(request): form = OrderForm(request.POST) if form.is_valid(): quantity = form.cleaned_data["quantity"] # TODO - add stripe integration to process the order # for now, just wait for 2 seconds to simulate the processing time.sleep(2) return render(request, "product.html", {"form": form})
In this view, we validate the form, extract the quantity from the cleaned data, and simulate Stripe order processing. In the end, we return the same template (product.html). We also need to add the view to the urlpatterns:
# ecommerce_site/urls.py # ... same imports as before urlpatterns = [ path("admin/", admin.site.urls), path("", views.home, name="home"), path("purchase", views.purchase, name="purchase"), # ⬅️ new ]
We now need to tell htmx what to do with this response.
4: Replace the Form Content With the Purchase View Response
Htmx has a hx-swap attribute which replaces targeted content on the current page with a request's response.
In our case, since the purchase view returns the same template, we want to swap its main element — the <form>:
<!-- ecommerce/templates/product.html --> <!-- add the hx-swap html attribute ⬇️ --> <form method="post" hx-post="{% url 'purchase' %}" hx-swap="outerHTML"> <!-- Same product details as before, hidden for simplicity --> {{ form }} <button type="submit" id="submit-btn">Buy</button> </form>
The value outerHTML will replace the entire target element with the response from the purchase view. By default, the htmx target is the same element making the call — in our case, the <form> element.
5: Tell Htmx What to Do When the Request Is Triggered
htmx provides some helper utilities for when a request is processing. In our case, we want to:
- Disable the "Buy" button (to avoid a form re-submission) by using the
hx-disabled-eltattribute. - Show a loading message on the screen by using the
htmx-indicatorclass. This class changes its element's opacity when the request is triggered.
<!-- ecommerce/templates/product.html --> <!-- add the hx-disabled-elt html attribute ⬇️ --> <form method="post" hx-post="{% url 'purchase' %}" hx-swap="outerHTML" hx-disabled-elt="#submit-btn" > <!-- Same product details as before, hidden for simplicity --> {{ form }} <button type="submit" id="submit-btn">Buy</button> <!-- add a loading message with the htmx-indicator class ⬇️ --> <p class="htmx-indicator"><small>Getting your mug ready...</small></p> </form>
Once the customer clicks the "Buy" button, htmx will disable that same button (identifiable by its submit-btn id), and show a loading message by changing the opacity of the p.htmx-indicator element.
The Result
Jump over to the browser.
You can see the final result in this GitHub repository.
It doesn’t do much else yet. But, if form validation fails, errors will display directly on the form, without the need to refresh the entire page. If the form succeeds, we will process the Stripe order accordingly. We'll see how to do this in the second part of this guide.
Wrapping Up
We've now set up the basics for our one-product ecommerce site. We've configured our Django project, integrated it with htmx to give our site some interactivity, and set up a basic order form for our product.
In the second part of this guide, we'll handle orders with Stripe, save the results in our database, and notify users after a successful purchase.
Until then, happy coding!
P.S. If you'd like to read Python posts as soon as they get off the press, subscribe to our Python Wizardry newsletter and never miss a single post!
