diff --git a/site/events/__init__.py b/site/events/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/site/events/admin.py b/site/events/admin.py
new file mode 100644
index 0000000..990f224
--- /dev/null
+++ b/site/events/admin.py
@@ -0,0 +1,24 @@
+from django.contrib import admin
+
+from events.models import Event, Ticket, TicketOrder
+
+
+@admin.register(Event)
+class EventAdmin(admin.ModelAdmin):
+ list_display = ("title", "starts_at", "capacity", "price", "is_published")
+ list_filter = ("is_published",)
+ search_fields = ("title", "venue")
+ prepopulated_fields = {"slug": ("title",)}
+
+
+@admin.register(TicketOrder)
+class TicketOrderAdmin(admin.ModelAdmin):
+ list_display = ("number", "event", "email", "quantity", "status")
+ list_filter = ("status",)
+ search_fields = ("number", "email")
+
+
+@admin.register(Ticket)
+class TicketAdmin(admin.ModelAdmin):
+ list_display = ("code", "event", "order")
+ search_fields = ("code",)
diff --git a/site/events/apps.py b/site/events/apps.py
new file mode 100644
index 0000000..0c54693
--- /dev/null
+++ b/site/events/apps.py
@@ -0,0 +1,12 @@
+from django.apps import AppConfig
+
+
+class EventsConfig(AppConfig):
+ default_auto_field = "django.db.models.BigAutoField"
+ name = "events"
+ verbose_name = "Event ticketing"
+
+ def ready(self):
+ from events import hooks
+
+ hooks.register()
diff --git a/site/events/hooks.py b/site/events/hooks.py
new file mode 100644
index 0000000..10a8dd7
--- /dev/null
+++ b/site/events/hooks.py
@@ -0,0 +1,33 @@
+from core.registry import (
+ register_dashboard_collector,
+ register_feature,
+ register_portal_nav,
+ register_public_nav,
+)
+
+
+def register() -> None:
+ register_feature("events")
+ register_public_nav(
+ section="events", label="Events", url_name="events:list", order=35
+ )
+ register_portal_nav(
+ section="events",
+ label="Events",
+ url_name="events_portal:event_list",
+ group="Retail",
+ order=30,
+ )
+ register_dashboard_collector(_dashboard)
+
+
+def _dashboard(request) -> dict:
+ from django.utils import timezone
+
+ from events.models import Event
+
+ return {
+ "upcoming_events": Event.objects.filter(
+ is_published=True, starts_at__gte=timezone.now()
+ ).count()
+ }
diff --git a/site/events/migrations/0001_initial.py b/site/events/migrations/0001_initial.py
new file mode 100644
index 0000000..9d22256
--- /dev/null
+++ b/site/events/migrations/0001_initial.py
@@ -0,0 +1,74 @@
+# Generated by Django 6.1 on 2026-09-06 11:17
+
+import django.db.models.deletion
+import uuid
+from decimal import Decimal
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+ initial = True
+
+ dependencies = [
+ ]
+
+ operations = [
+ migrations.CreateModel(
+ name='Event',
+ fields=[
+ ('created_at', models.DateTimeField(auto_now_add=True)),
+ ('updated_at', models.DateTimeField(auto_now=True)),
+ ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+ ('title', models.CharField(max_length=200)),
+ ('slug', models.SlugField(max_length=220, unique=True)),
+ ('description', models.TextField(blank=True)),
+ ('starts_at', models.DateTimeField()),
+ ('venue', models.CharField(blank=True, max_length=200)),
+ ('capacity', models.PositiveIntegerField(default=0)),
+ ('price', models.DecimalField(decimal_places=2, default=Decimal('0'), max_digits=10)),
+ ('currency', models.CharField(default='usd', max_length=8)),
+ ('is_published', models.BooleanField(default=False)),
+ ],
+ options={
+ 'ordering': ['starts_at'],
+ },
+ ),
+ migrations.CreateModel(
+ name='TicketOrder',
+ fields=[
+ ('created_at', models.DateTimeField(auto_now_add=True)),
+ ('updated_at', models.DateTimeField(auto_now=True)),
+ ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+ ('number', models.CharField(max_length=32, unique=True)),
+ ('email', models.EmailField(max_length=254)),
+ ('customer_name', models.CharField(blank=True, max_length=200)),
+ ('quantity', models.PositiveIntegerField(default=1)),
+ ('amount', models.DecimalField(decimal_places=2, max_digits=10)),
+ ('currency', models.CharField(default='usd', max_length=8)),
+ ('status', models.CharField(choices=[('draft', 'Draft'), ('open', 'Open'), ('paid', 'Paid'), ('cancelled', 'Cancelled')], default='draft', max_length=16)),
+ ('stripe_checkout_session_id', models.CharField(blank=True, max_length=255)),
+ ('hosted_checkout_url', models.URLField(blank=True)),
+ ('paid_at', models.DateTimeField(blank=True, null=True)),
+ ('event', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='ticket_orders', to='events.event')),
+ ],
+ options={
+ 'ordering': ['-created_at'],
+ },
+ ),
+ migrations.CreateModel(
+ name='Ticket',
+ fields=[
+ ('created_at', models.DateTimeField(auto_now_add=True)),
+ ('updated_at', models.DateTimeField(auto_now=True)),
+ ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+ ('code', models.CharField(max_length=16, unique=True)),
+ ('attendee_name', models.CharField(blank=True, max_length=200)),
+ ('event', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='tickets', to='events.event')),
+ ('order', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='tickets', to='events.ticketorder')),
+ ],
+ options={
+ 'ordering': ['created_at'],
+ },
+ ),
+ ]
diff --git a/site/events/migrations/__init__.py b/site/events/migrations/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/site/events/models.py b/site/events/models.py
new file mode 100644
index 0000000..35ea5f7
--- /dev/null
+++ b/site/events/models.py
@@ -0,0 +1,111 @@
+from decimal import Decimal
+
+from django.db import models
+from django.urls import reverse
+from django.utils import timezone
+from django.utils.text import slugify
+
+from core.models import TimeStampedModel, UUIDPrimaryKeyModel
+
+
+class Event(UUIDPrimaryKeyModel, TimeStampedModel):
+ title = models.CharField(max_length=200)
+ slug = models.SlugField(max_length=220, unique=True)
+ description = models.TextField(blank=True)
+ starts_at = models.DateTimeField()
+ venue = models.CharField(max_length=200, blank=True)
+ capacity = models.PositiveIntegerField(default=0)
+ price = models.DecimalField(max_digits=10, decimal_places=2, default=Decimal("0"))
+ currency = models.CharField(max_length=8, default="usd")
+ is_published = models.BooleanField(default=False)
+
+ class Meta:
+ ordering = ["starts_at"]
+
+ def __str__(self) -> str:
+ return self.title
+
+ def get_absolute_url(self) -> str:
+ return reverse("events:detail", kwargs={"slug": self.slug})
+
+ def save(self, *args, **kwargs):
+ if not self.slug:
+ base = slugify(self.title)[:200] or "event"
+ slug = base
+ n = 2
+ while Event.objects.filter(slug=slug).exclude(pk=self.pk).exists():
+ slug = f"{base}-{n}"
+ n += 1
+ self.slug = slug
+ super().save(*args, **kwargs)
+
+ def tickets_held(self, *, exclude_order_id=None) -> int:
+ qs = self.ticket_orders.filter(
+ status__in=[
+ TicketOrder.Status.DRAFT,
+ TicketOrder.Status.OPEN,
+ TicketOrder.Status.PAID,
+ ]
+ )
+ if exclude_order_id:
+ qs = qs.exclude(pk=exclude_order_id)
+ return qs.aggregate(total=models.Sum("quantity"))["total"] or 0
+
+ @property
+ def tickets_sold(self) -> int:
+ return self.tickets_held()
+
+ @property
+ def seats_remaining(self) -> int | None:
+ if not self.capacity:
+ return None
+ return max(self.capacity - self.tickets_sold, 0)
+
+ @property
+ def is_upcoming(self) -> bool:
+ return self.starts_at >= timezone.now()
+
+
+class TicketOrder(UUIDPrimaryKeyModel, TimeStampedModel):
+ class Status(models.TextChoices):
+ DRAFT = "draft", "Draft"
+ OPEN = "open", "Open"
+ PAID = "paid", "Paid"
+ CANCELLED = "cancelled", "Cancelled"
+
+ number = models.CharField(max_length=32, unique=True)
+ event = models.ForeignKey(
+ Event, on_delete=models.PROTECT, related_name="ticket_orders"
+ )
+ email = models.EmailField()
+ customer_name = models.CharField(max_length=200, blank=True)
+ quantity = models.PositiveIntegerField(default=1)
+ amount = models.DecimalField(max_digits=10, decimal_places=2)
+ currency = models.CharField(max_length=8, default="usd")
+ status = models.CharField(
+ max_length=16, choices=Status.choices, default=Status.DRAFT
+ )
+ stripe_checkout_session_id = models.CharField(max_length=255, blank=True)
+ hosted_checkout_url = models.URLField(blank=True)
+ paid_at = models.DateTimeField(null=True, blank=True)
+
+ class Meta:
+ ordering = ["-created_at"]
+
+ def __str__(self) -> str:
+ return f"{self.number} · {self.event}"
+
+
+class Ticket(UUIDPrimaryKeyModel, TimeStampedModel):
+ order = models.ForeignKey(
+ TicketOrder, on_delete=models.CASCADE, related_name="tickets"
+ )
+ event = models.ForeignKey(Event, on_delete=models.PROTECT, related_name="tickets")
+ code = models.CharField(max_length=16, unique=True)
+ attendee_name = models.CharField(max_length=200, blank=True)
+
+ class Meta:
+ ordering = ["created_at"]
+
+ def __str__(self) -> str:
+ return self.code
diff --git a/site/events/portal_urls.py b/site/events/portal_urls.py
new file mode 100644
index 0000000..e9c20e0
--- /dev/null
+++ b/site/events/portal_urls.py
@@ -0,0 +1,13 @@
+from django.urls import path
+
+from events import views
+
+app_name = "events_portal"
+
+urlpatterns = [
+ path("", views.portal_event_list, name="event_list"),
+ path("new/", views.portal_event_edit, name="event_new"),
+ path("
/", views.portal_event_detail, name="event_detail"),
+ path("/edit/", views.portal_event_edit, name="event_edit"),
+ path("webhooks/stripe/", views.stripe_webhook, name="stripe_webhook"),
+]
diff --git a/site/events/public_urls.py b/site/events/public_urls.py
new file mode 100644
index 0000000..04dcbcb
--- /dev/null
+++ b/site/events/public_urls.py
@@ -0,0 +1,13 @@
+from django.urls import path
+
+from events import views
+
+app_name = "events"
+
+urlpatterns = [
+ path("", views.event_list, name="list"),
+ path("order//success/", views.checkout_success, name="checkout_success"),
+ path("order//cancel/", views.checkout_cancel, name="checkout_cancel"),
+ path("/", views.event_detail, name="detail"),
+ path("/buy/", views.buy_tickets, name="buy"),
+]
diff --git a/site/events/services.py b/site/events/services.py
new file mode 100644
index 0000000..7ce393b
--- /dev/null
+++ b/site/events/services.py
@@ -0,0 +1,188 @@
+"""Event capacity, Stripe ticket checkout, and confirmation email."""
+
+from __future__ import annotations
+
+import logging
+import secrets
+from datetime import date
+from decimal import Decimal
+
+from django.conf import settings
+from django.db import transaction
+from django.utils import timezone
+
+from events.models import Event, Ticket, TicketOrder
+
+logger = logging.getLogger(__name__)
+
+
+class EventsError(RuntimeError):
+ pass
+
+
+def _stripe():
+ secret = (settings.STRIPE_SECRET_KEY or "").strip()
+ if not secret:
+ raise EventsError("STRIPE_SECRET_KEY is not configured")
+ try:
+ import stripe
+ except ImportError as exc:
+ raise EventsError("stripe package is not installed") from exc
+ stripe.api_key = secret
+ return stripe
+
+
+def next_ticket_order_number() -> str:
+ today = date.today().strftime("%Y%m%d")
+ prefix = f"TIX-{today}-"
+ existing = TicketOrder.objects.filter(number__startswith=prefix).count()
+ return f"{prefix}{existing + 1:03d}"
+
+
+def new_ticket_code() -> str:
+ while True:
+ code = secrets.token_hex(4).upper()
+ if not Ticket.objects.filter(code=code).exists():
+ return code
+
+
+def assert_capacity(
+ event: Event, quantity: int, *, exclude_order_id=None
+) -> None:
+ if quantity < 1:
+ raise EventsError("Quantity must be at least 1.")
+ if not event.capacity:
+ return
+ held = event.tickets_held(exclude_order_id=exclude_order_id)
+ remaining = max(event.capacity - held, 0)
+ if quantity > remaining:
+ raise EventsError(f"Only {remaining} seats left for {event.title}.")
+
+
+def create_ticket_order(
+ event: Event, *, email: str, customer_name: str = "", quantity: int = 1
+) -> TicketOrder:
+ email = (email or "").strip()
+ if not email:
+ raise EventsError("Email is required.")
+ if not event.is_published:
+ raise EventsError("This event is not on sale.")
+ assert_capacity(event, quantity)
+ amount = event.price * quantity
+ return TicketOrder.objects.create(
+ number=next_ticket_order_number(),
+ event=event,
+ email=email,
+ customer_name=(customer_name or "").strip(),
+ quantity=quantity,
+ amount=amount,
+ currency=(event.currency or settings.STRIPE_CURRENCY or "usd").lower(),
+ status=TicketOrder.Status.DRAFT,
+ )
+
+
+def create_checkout_session(
+ order: TicketOrder, *, success_url: str, cancel_url: str
+) -> str:
+ stripe = _stripe()
+ session = stripe.checkout.Session.create(
+ mode="payment",
+ customer_email=order.email or None,
+ line_items=[
+ {
+ "quantity": order.quantity,
+ "price_data": {
+ "currency": (order.currency or "usd").lower(),
+ "unit_amount": int(
+ (order.event.price * Decimal("100")).quantize(Decimal("1"))
+ ),
+ "product_data": {"name": order.event.title},
+ },
+ }
+ ],
+ metadata={
+ "ticket_order_id": str(order.pk),
+ "ticket_order_number": order.number,
+ },
+ success_url=success_url,
+ cancel_url=cancel_url,
+ )
+ order.stripe_checkout_session_id = session.id
+ order.hosted_checkout_url = session.url or ""
+ order.status = TicketOrder.Status.OPEN
+ order.save(
+ update_fields=[
+ "stripe_checkout_session_id",
+ "hosted_checkout_url",
+ "status",
+ "updated_at",
+ ]
+ )
+ return session.url or ""
+
+
+def _issue_tickets(order: TicketOrder) -> list[Ticket]:
+ created = []
+ for _ in range(order.quantity):
+ created.append(
+ Ticket.objects.create(
+ order=order,
+ event=order.event,
+ code=new_ticket_code(),
+ attendee_name=order.customer_name,
+ )
+ )
+ return created
+
+
+def mark_paid(order: TicketOrder, *, stripe_id: str = "") -> None:
+ if order.status == TicketOrder.Status.PAID:
+ return
+ with transaction.atomic():
+ locked = TicketOrder.objects.select_for_update().get(pk=order.pk)
+ if locked.status == TicketOrder.Status.PAID:
+ return
+ assert_capacity(
+ locked.event, locked.quantity, exclude_order_id=locked.pk
+ )
+ _issue_tickets(locked)
+ locked.status = TicketOrder.Status.PAID
+ locked.paid_at = timezone.now()
+ locked.save(update_fields=["status", "paid_at", "updated_at"])
+ order.refresh_from_db()
+ try:
+ send_ticket_email(order)
+ except Exception:
+ logger.exception("ticket email failed for %s", order.number)
+
+
+def send_ticket_email(order: TicketOrder) -> bool:
+ to_email = (order.email or "").strip()
+ if not to_email:
+ raise EventsError("Order has no email address")
+ from django.core.mail import EmailMultiAlternatives
+
+ codes = ", ".join(t.code for t in order.tickets.all())
+ name = order.customer_name or "there"
+ when = timezone.localtime(order.event.starts_at).strftime("%b %d, %Y %-I:%M %p")
+ subject = f"Tickets for {order.event.title} — {settings.SITE_NAME}"
+ text = (
+ f"Hi {name},\n\n"
+ f"Your tickets for {order.event.title} on {when}:\n"
+ f"{codes}\n\nOrder {order.number}\n"
+ )
+ html = (
+ f"Hi {name},
"
+ f"Tickets for {order.event.title} on {when}:
"
+ f"{codes}
"
+ f"Order {order.number}
"
+ )
+ mail = EmailMultiAlternatives(
+ subject=subject,
+ body=text,
+ from_email=settings.DEFAULT_FROM_EMAIL,
+ to=[to_email],
+ )
+ mail.attach_alternative(html, "text/html")
+ mail.send(fail_silently=False)
+ return True
diff --git a/site/events/templates/events/buy.html b/site/events/templates/events/buy.html
new file mode 100644
index 0000000..aa0ce9f
--- /dev/null
+++ b/site/events/templates/events/buy.html
@@ -0,0 +1,17 @@
+{% extends "base.html" %}
+{% block title %}Tickets · {{ event.title }}{% endblock %}
+{% block content %}
+
+
+
Tickets · {{ event.title }}
+
{{ event.price }} {{ event.currency|upper }} each{% if event.seats_remaining is not None %} · {{ event.seats_remaining }} left{% endif %}
+
+
+
Checkout cancelled
+
No charge for {{ order.event.title }}. Try again.
+
+
← Events
+
{{ event.title }}
+
{{ event.starts_at|date:"F j, Y g:i A" }}{% if event.venue %} · {{ event.venue }}{% endif %}
+
{{ event.description|linebreaks }}
+
{{ event.price }} {{ event.currency|upper }}
+ {% if event.seats_remaining == 0 %}
+
Sold out.
+ {% else %}
+
Buy tickets
+ {% endif %}
+
+
Events
+ {% for event in events %}
+
+
+ {{ event.starts_at|date:"F j, Y g:i A" }}{% if event.venue %} · {{ event.venue }}{% endif %}
+ {{ event.price }} {{ event.currency|upper }}{% if event.seats_remaining is not None %} · {{ event.seats_remaining }} seats left{% endif %}
+
+ {% empty %}
+
No upcoming events.
+ {% endfor %}
+
Edit
+{{ event.starts_at }} · {{ event.tickets_sold }} / {{ event.capacity|default:"∞" }} seats · {{ event.price }} {{ event.currency|upper }}
+
+ | Order | Email | Qty | Status | Codes |
|---|
+
+ {% for order in orders %}
+
+ | {{ order.number }} |
+ {{ order.email }} |
+ {{ order.quantity }} |
+ {{ order.get_status_display }} |
+ {% for ticket in order.tickets.all %}{{ ticket.code }}{% if not forloop.last %}, {% endif %}{% endfor %} |
+
+ {% empty %}
+ | No ticket orders yet. |
+ {% endfor %}
+
+
+{% endblock %}
diff --git a/site/events/templates/events/portal/edit.html b/site/events/templates/events/portal/edit.html
new file mode 100644
index 0000000..79003ba
--- /dev/null
+++ b/site/events/templates/events/portal/edit.html
@@ -0,0 +1,17 @@
+{% extends "portal_base.html" %}
+{% block title %}{% if event %}Edit{% else %}New{% endif %} event · Portal{% endblock %}
+{% block topbar_title %}{% if event %}Edit event{% else %}New event{% endif %}{% endblock %}
+{% block portal_content %}
+
+{% endblock %}
diff --git a/site/events/templates/events/portal/list.html b/site/events/templates/events/portal/list.html
new file mode 100644
index 0000000..efd9b68
--- /dev/null
+++ b/site/events/templates/events/portal/list.html
@@ -0,0 +1,21 @@
+{% extends "portal_base.html" %}
+{% block title %}Events · Portal{% endblock %}
+{% block topbar_title %}Events{% endblock %}
+{% block portal_content %}
+New event
+
+ | Title | When | Capacity | Status |
|---|
+
+ {% for event in events %}
+
+ | {{ event.title }} |
+ {{ event.starts_at }} |
+ {{ event.tickets_sold }} / {{ event.capacity|default:"∞" }} |
+ {% if event.is_published %}Published{% else %}Draft{% endif %} |
+
+ {% empty %}
+ | No events yet. |
+ {% endfor %}
+
+
+{% endblock %}
diff --git a/site/events/templates/events/success.html b/site/events/templates/events/success.html
new file mode 100644
index 0000000..d33b77b
--- /dev/null
+++ b/site/events/templates/events/success.html
@@ -0,0 +1,9 @@
+{% extends "base.html" %}
+{% block title %}Tickets {{ order.number }}{% endblock %}
+{% block content %}
+
+
You're in
+
Order {{ order.number }} for {{ order.event.title }} is {{ order.get_status_display|lower }}.
+
Ticket codes will be emailed to {{ order.email }}.
+
Inbound POS sales decrement shop stock. Online sales queue outbound reserves.
+
+ | When | Direction | SKU | Qty | Status |
|---|
+
+ {% for event in events %}
+
+ | {{ event.created_at }} |
+ {{ event.get_direction_display }} |
+ {{ event.sku }} |
+ {{ event.quantity }} |
+ {{ event.get_status_display }} |
+
+ {% empty %}
+ | No sync events yet. |
+ {% endfor %}
+
+
+{% endblock %}
diff --git a/site/pos_sync/tests.py b/site/pos_sync/tests.py
new file mode 100644
index 0000000..aec0b38
--- /dev/null
+++ b/site/pos_sync/tests.py
@@ -0,0 +1,115 @@
+from decimal import Decimal
+from unittest.mock import patch
+
+from django.contrib.auth import get_user_model
+from django.test import Client, TestCase, override_settings
+from django.urls import reverse
+
+from pos_sync.models import POSConnection, SyncEvent
+from pos_sync.services import apply_inbound_sale, dispatch_pending_outbound, enqueue_online_sale
+from shop.models import Product
+from shop.services import add_to_cart, create_order_from_cart, mark_paid
+
+
+class POSInboundTests(TestCase):
+ def setUp(self):
+ self.product = Product.objects.create(
+ name="Booster pack",
+ sku="TCG-PACK",
+ price=Decimal("4.99"),
+ stock_qty=10,
+ is_published=True,
+ )
+
+ def test_inbound_sale_decrements_stock(self):
+ event = apply_inbound_sale(sku="tcg-pack", quantity=3, external_id="pos-1")
+ self.product.refresh_from_db()
+ self.assertEqual(self.product.stock_qty, 7)
+ self.assertEqual(event.status, SyncEvent.Status.DONE)
+
+ @override_settings(POS_WEBHOOK_SECRET="pos-secret")
+ def test_webhook_requires_secret_and_updates_stock(self):
+ url = reverse("pos_sync:inventory_webhook")
+ anon = Client().post(
+ url,
+ data='{"sku":"TCG-PACK","quantity":1}',
+ content_type="application/json",
+ )
+ self.assertEqual(anon.status_code, 401)
+ ok = Client().post(
+ url,
+ data='{"sku":"TCG-PACK","quantity":2,"external_id":"reg-9"}',
+ content_type="application/json",
+ HTTP_AUTHORIZATION="Bearer pos-secret",
+ )
+ self.assertEqual(ok.status_code, 200)
+ self.product.refresh_from_db()
+ self.assertEqual(self.product.stock_qty, 8)
+
+
+class POSOutboundTests(TestCase):
+ def setUp(self):
+ self.product = Product.objects.create(
+ name="Figure",
+ sku="FIG-1",
+ price=Decimal("12.00"),
+ stock_qty=5,
+ is_published=True,
+ )
+ self.connection = POSConnection.objects.create(
+ name="Counter",
+ api_base_url="https://pos.example.com",
+ api_token="tok",
+ is_active=True,
+ )
+
+ def test_paid_order_enqueues_outbound(self):
+ session = self.client.session
+ add_to_cart(session, self.product, 1)
+ session.save()
+ order = create_order_from_cart(self.client.session, email="a@example.com")
+ mark_paid(order)
+ event = SyncEvent.objects.get(direction=SyncEvent.Direction.OUTBOUND)
+ self.assertEqual(event.sku, "FIG-1")
+ self.assertEqual(event.status, SyncEvent.Status.PENDING)
+
+ def test_dispatch_posts_reserve(self):
+ enqueue_online_sale(
+ type(
+ "O",
+ (),
+ {
+ "number": "ORD-1",
+ "pk": "x",
+ "items": type(
+ "M",
+ (),
+ {
+ "all": lambda self: [
+ type("I", (), {"sku": "FIG-1", "quantity": 1})()
+ ]
+ },
+ )(),
+ },
+ )()
+ )
+ with patch("pos_sync.services.requests.post") as post:
+ post.return_value.raise_for_status = lambda: None
+ sent = dispatch_pending_outbound()
+ self.assertEqual(sent, 1)
+ post.assert_called_once()
+ self.assertIn("/inventory/reserve", post.call_args.args[0])
+ event = SyncEvent.objects.get()
+ self.assertEqual(event.status, SyncEvent.Status.DONE)
+
+
+class POSPortalTests(TestCase):
+ def test_list_requires_login(self):
+ self.assertEqual(Client().get(reverse("pos_sync:event_list")).status_code, 302)
+
+ def test_list_ok_when_logged_in(self):
+ User = get_user_model()
+ User.objects.create_user("clerk", password="test-pass-123")
+ client = Client()
+ client.login(username="clerk", password="test-pass-123")
+ self.assertEqual(client.get(reverse("pos_sync:event_list")).status_code, 200)
diff --git a/site/pos_sync/urls.py b/site/pos_sync/urls.py
new file mode 100644
index 0000000..1fa1e4e
--- /dev/null
+++ b/site/pos_sync/urls.py
@@ -0,0 +1,10 @@
+from django.urls import path
+
+from pos_sync import views
+
+app_name = "pos_sync"
+
+urlpatterns = [
+ path("", views.event_list, name="event_list"),
+ path("webhooks/inventory/", views.inventory_webhook, name="inventory_webhook"),
+]
diff --git a/site/pos_sync/views.py b/site/pos_sync/views.py
new file mode 100644
index 0000000..18f93f0
--- /dev/null
+++ b/site/pos_sync/views.py
@@ -0,0 +1,70 @@
+import json
+import logging
+
+from django.conf import settings
+from django.contrib.auth.decorators import login_required
+from django.http import HttpResponse, HttpResponseBadRequest, JsonResponse
+from django.shortcuts import render
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_http_methods
+
+from pos_sync.models import POSConnection, SyncEvent
+from pos_sync.services import POSSyncError, apply_inbound_sale
+
+logger = logging.getLogger(__name__)
+
+
+def _authorized(request) -> bool:
+ expected = (settings.POS_WEBHOOK_SECRET or "").strip()
+ if not expected:
+ conn = POSConnection.objects.filter(is_active=True).exclude(
+ webhook_secret=""
+ ).first()
+ expected = (conn.webhook_secret if conn else "").strip()
+ if not expected:
+ return False
+ header = request.headers.get("Authorization", "")
+ token = ""
+ if header.startswith("Bearer "):
+ token = header[7:].strip()
+ token = token or request.GET.get("token") or ""
+ return token == expected
+
+
+@login_required
+def event_list(request):
+ events = SyncEvent.objects.select_related("connection")[:200]
+ connections = POSConnection.objects.all()
+ return render(
+ request,
+ "pos_sync/list.html",
+ {"events": events, "connections": connections},
+ )
+
+
+@csrf_exempt
+@require_http_methods(["POST"])
+def inventory_webhook(request):
+ if not _authorized(request):
+ return HttpResponse("unauthorized", status=401)
+ try:
+ payload = json.loads(request.body.decode() or "{}")
+ except json.JSONDecodeError:
+ return HttpResponseBadRequest("invalid json")
+ sku = payload.get("sku") or payload.get("SKU") or ""
+ try:
+ quantity = int(payload.get("quantity") or payload.get("qty") or 0)
+ except (TypeError, ValueError):
+ return HttpResponseBadRequest("invalid quantity")
+ external_id = str(payload.get("external_id") or payload.get("id") or "")
+ try:
+ event = apply_inbound_sale(
+ sku=sku,
+ quantity=quantity,
+ external_id=external_id,
+ payload=payload,
+ )
+ except POSSyncError as exc:
+ logger.warning("POS inbound rejected: %s", exc)
+ return JsonResponse({"ok": False, "error": str(exc)}, status=400)
+ return JsonResponse({"ok": True, "id": str(event.pk), "status": event.status})
diff --git a/site/public/context_processors.py b/site/public/context_processors.py
index f26f11c..11f3389 100644
--- a/site/public/context_processors.py
+++ b/site/public/context_processors.py
@@ -63,6 +63,15 @@ def tianji_tracking(request):
nav_section = "social_accounts"
elif namespace == "social":
nav_section = "social"
+ elif namespace == "shop_portal":
+ if url_name.startswith("product"):
+ nav_section = "shop_products"
+ elif url_name.startswith("order"):
+ nav_section = "shop_orders"
+ elif url_name == "sales":
+ nav_section = "shop_sales"
+ elif namespace == "shop":
+ nav_section = "shop"
return {
"tianji_enabled": getattr(settings, "TIANJI_ENABLED", False)
diff --git a/site/public/views.py b/site/public/views.py
index 8f79903..a33e880 100644
--- a/site/public/views.py
+++ b/site/public/views.py
@@ -70,6 +70,10 @@ def sitemap_xml(request):
from django.apps import apps as django_apps
if django_apps.is_installed("blog"):
paths.append(("blog:list", "0.7", "weekly"))
+ if django_apps.is_installed("shop"):
+ paths.append(("shop:list", "0.8", "weekly"))
+ if django_apps.is_installed("events"):
+ paths.append(("events:list", "0.8", "weekly"))
urls = []
for name, priority, changefreq in paths:
path = reverse(name)
diff --git a/site/shipping/__init__.py b/site/shipping/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/site/shipping/admin.py b/site/shipping/admin.py
new file mode 100644
index 0000000..291cc75
--- /dev/null
+++ b/site/shipping/admin.py
@@ -0,0 +1,10 @@
+from django.contrib import admin
+
+from shipping.models import Shipment
+
+
+@admin.register(Shipment)
+class ShipmentAdmin(admin.ModelAdmin):
+ list_display = ("order", "status", "carrier", "tracking_number")
+ list_filter = ("status", "carrier")
+ search_fields = ("tracking_number", "order__number")
diff --git a/site/shipping/apps.py b/site/shipping/apps.py
new file mode 100644
index 0000000..7e9ba77
--- /dev/null
+++ b/site/shipping/apps.py
@@ -0,0 +1,12 @@
+from django.apps import AppConfig
+
+
+class ShippingConfig(AppConfig):
+ default_auto_field = "django.db.models.BigAutoField"
+ name = "shipping"
+ verbose_name = "Shipping automation"
+
+ def ready(self):
+ from shipping import hooks
+
+ hooks.register()
diff --git a/site/shipping/hooks.py b/site/shipping/hooks.py
new file mode 100644
index 0000000..7d8e918
--- /dev/null
+++ b/site/shipping/hooks.py
@@ -0,0 +1,31 @@
+from core.registry import (
+ register_dashboard_collector,
+ register_feature,
+ register_portal_nav,
+)
+
+
+def register() -> None:
+ register_feature("shipping")
+ register_portal_nav(
+ section="shipping",
+ label="Shipping",
+ url_name="shipping:shipment_list",
+ group="Retail",
+ order=50,
+ )
+ register_dashboard_collector(_dashboard)
+
+
+def _dashboard(request) -> dict:
+ from shipping.models import Shipment
+ from shop.models import Order
+
+ labeled = Shipment.objects.filter(status=Shipment.Status.LABELED).values_list(
+ "order_id", flat=True
+ )
+ return {
+ "unshipped_orders": Order.objects.filter(status=Order.Status.PAID)
+ .exclude(pk__in=labeled)
+ .count()
+ }
diff --git a/site/shipping/migrations/0001_initial.py b/site/shipping/migrations/0001_initial.py
new file mode 100644
index 0000000..f1f8e87
--- /dev/null
+++ b/site/shipping/migrations/0001_initial.py
@@ -0,0 +1,40 @@
+# Generated by Django 6.1 on 2026-09-06 11:17
+
+import django.db.models.deletion
+import uuid
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+ initial = True
+
+ dependencies = [
+ ('shop', '0001_initial'),
+ ]
+
+ operations = [
+ migrations.CreateModel(
+ name='Shipment',
+ fields=[
+ ('created_at', models.DateTimeField(auto_now_add=True)),
+ ('updated_at', models.DateTimeField(auto_now=True)),
+ ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+ ('status', models.CharField(choices=[('draft', 'Draft'), ('rated', 'Rated'), ('labeled', 'Labeled'), ('void', 'Void')], default='draft', max_length=16)),
+ ('carrier', models.CharField(blank=True, max_length=32)),
+ ('service', models.CharField(blank=True, max_length=64)),
+ ('tracking_number', models.CharField(blank=True, max_length=64)),
+ ('label_url', models.URLField(blank=True)),
+ ('rate_amount', models.DecimalField(blank=True, decimal_places=2, max_digits=10, null=True)),
+ ('currency', models.CharField(default='usd', max_length=8)),
+ ('provider_shipment_id', models.CharField(blank=True, max_length=255)),
+ ('rates', models.JSONField(blank=True, default=list)),
+ ('weight_oz', models.PositiveIntegerField(default=16)),
+ ('notes', models.TextField(blank=True)),
+ ('order', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='shipments', to='shop.order')),
+ ],
+ options={
+ 'ordering': ['-created_at'],
+ },
+ ),
+ ]
diff --git a/site/shipping/migrations/__init__.py b/site/shipping/migrations/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/site/shipping/models.py b/site/shipping/models.py
new file mode 100644
index 0000000..4892da8
--- /dev/null
+++ b/site/shipping/models.py
@@ -0,0 +1,33 @@
+from django.db import models
+
+from core.models import TimeStampedModel, UUIDPrimaryKeyModel
+from shop.models import Order
+
+
+class Shipment(UUIDPrimaryKeyModel, TimeStampedModel):
+ class Status(models.TextChoices):
+ DRAFT = "draft", "Draft"
+ RATED = "rated", "Rated"
+ LABELED = "labeled", "Labeled"
+ VOID = "void", "Void"
+
+ order = models.ForeignKey(Order, on_delete=models.PROTECT, related_name="shipments")
+ status = models.CharField(
+ max_length=16, choices=Status.choices, default=Status.DRAFT
+ )
+ carrier = models.CharField(max_length=32, blank=True)
+ service = models.CharField(max_length=64, blank=True)
+ tracking_number = models.CharField(max_length=64, blank=True)
+ label_url = models.URLField(blank=True)
+ rate_amount = models.DecimalField(max_digits=10, decimal_places=2, null=True, blank=True)
+ currency = models.CharField(max_length=8, default="usd")
+ provider_shipment_id = models.CharField(max_length=255, blank=True)
+ rates = models.JSONField(default=list, blank=True)
+ weight_oz = models.PositiveIntegerField(default=16)
+ notes = models.TextField(blank=True)
+
+ class Meta:
+ ordering = ["-created_at"]
+
+ def __str__(self) -> str:
+ return f"{self.order.number} · {self.tracking_number or self.status}"
diff --git a/site/shipping/services.py b/site/shipping/services.py
new file mode 100644
index 0000000..f81a44d
--- /dev/null
+++ b/site/shipping/services.py
@@ -0,0 +1,184 @@
+"""EasyPost-style rates/labels plus Pirate Ship CSV export."""
+
+from __future__ import annotations
+
+import csv
+import io
+import logging
+from decimal import Decimal
+
+import requests
+from django.conf import settings
+
+from shipping.models import Shipment
+from shop.models import Order
+
+logger = logging.getLogger(__name__)
+
+
+class ShippingError(RuntimeError):
+ pass
+
+
+def _easypost_key() -> str:
+ return (getattr(settings, "EASYPOST_API_KEY", "") or "").strip()
+
+
+def quote_rates(shipment: Shipment) -> list[dict]:
+ """Return carrier rates. Uses EasyPost when configured; otherwise a USPS stub."""
+ key = _easypost_key()
+ if not key:
+ rates = [
+ {
+ "id": "stub-usps-ground",
+ "carrier": "USPS",
+ "service": "GroundAdvantage",
+ "rate": "5.40",
+ "currency": "USD",
+ },
+ {
+ "id": "stub-usps-priority",
+ "carrier": "USPS",
+ "service": "Priority",
+ "rate": "9.80",
+ "currency": "USD",
+ },
+ ]
+ shipment.rates = rates
+ shipment.status = Shipment.Status.RATED
+ shipment.save(update_fields=["rates", "status", "updated_at"])
+ return rates
+
+ addr = shipment.order.shipping_address or {}
+ response = requests.post(
+ "https://api.easypost.com/v2/shipments",
+ auth=(key, ""),
+ json={
+ "shipment": {
+ "to_address": {
+ "name": shipment.order.customer_name or shipment.order.email,
+ "street1": addr.get("line1") or "",
+ "street2": addr.get("line2") or "",
+ "city": addr.get("city") or "",
+ "state": addr.get("state") or "",
+ "zip": addr.get("zip") or "",
+ "country": addr.get("country") or "US",
+ },
+ "from_address": {
+ "name": settings.SITE_NAME,
+ "street1": getattr(settings, "SHIP_FROM_LINE1", "") or "",
+ "city": getattr(settings, "SHIP_FROM_CITY", "") or "",
+ "state": getattr(settings, "SHIP_FROM_STATE", "") or "",
+ "zip": getattr(settings, "SHIP_FROM_ZIP", "") or "",
+ "country": "US",
+ },
+ "parcel": {"weight": shipment.weight_oz},
+ }
+ },
+ timeout=20,
+ )
+ response.raise_for_status()
+ data = response.json()
+ rates = data.get("rates") or []
+ shipment.provider_shipment_id = data.get("id") or ""
+ shipment.rates = rates
+ shipment.status = Shipment.Status.RATED
+ shipment.save(
+ update_fields=["provider_shipment_id", "rates", "status", "updated_at"]
+ )
+ return rates
+
+
+def buy_label(shipment: Shipment, *, rate_id: str = "") -> Shipment:
+ rates = shipment.rates or quote_rates(shipment)
+ chosen = None
+ if rate_id:
+ chosen = next((r for r in rates if str(r.get("id")) == str(rate_id)), None)
+ if chosen is None and rates:
+ chosen = rates[0]
+ if chosen is None:
+ raise ShippingError("No shipping rates available.")
+
+ key = _easypost_key()
+ if key and shipment.provider_shipment_id:
+ response = requests.post(
+ f"https://api.easypost.com/v2/shipments/{shipment.provider_shipment_id}/buy",
+ auth=(key, ""),
+ json={"rate": {"id": chosen.get("id")}},
+ timeout=20,
+ )
+ response.raise_for_status()
+ data = response.json()
+ postage = data.get("postage_label") or {}
+ tracking = data.get("tracking_code") or ""
+ shipment.label_url = postage.get("label_url") or ""
+ shipment.tracking_number = tracking
+ else:
+ shipment.tracking_number = f"STUB{shipment.order.number[-6:]}"
+ shipment.label_url = ""
+
+ shipment.carrier = chosen.get("carrier") or ""
+ shipment.service = chosen.get("service") or ""
+ try:
+ shipment.rate_amount = Decimal(str(chosen.get("rate") or "0"))
+ except Exception:
+ shipment.rate_amount = None
+ shipment.status = Shipment.Status.LABELED
+ shipment.save(
+ update_fields=[
+ "carrier",
+ "service",
+ "tracking_number",
+ "label_url",
+ "rate_amount",
+ "status",
+ "updated_at",
+ ]
+ )
+ return shipment
+
+
+def create_shipment_for_order(order: Order, *, weight_oz: int = 16) -> Shipment:
+ if order.status not in {Order.Status.PAID, Order.Status.FULFILLED}:
+ raise ShippingError("Ship paid orders only.")
+ return Shipment.objects.create(order=order, weight_oz=weight_oz)
+
+
+def pirate_ship_csv(orders=None) -> str:
+ """CSV Pirate Ship can map: name, address, city, state, zip, email."""
+ if orders is None:
+ shipped = Shipment.objects.filter(
+ status=Shipment.Status.LABELED
+ ).values_list("order_id", flat=True)
+ orders = Order.objects.filter(status=Order.Status.PAID).exclude(pk__in=shipped)
+ buffer = io.StringIO()
+ writer = csv.writer(buffer)
+ writer.writerow(
+ [
+ "Order Number",
+ "Name",
+ "Address 1",
+ "Address 2",
+ "City",
+ "State",
+ "Zip",
+ "Country",
+ "Email",
+ ]
+ )
+ for order in orders:
+ addr = order.shipping_address or {}
+ writer.writerow(
+ [
+ order.number,
+ order.customer_name or order.email,
+ addr.get("line1") or "",
+ addr.get("line2") or "",
+ addr.get("city") or "",
+ addr.get("state") or "",
+ addr.get("zip") or "",
+ addr.get("country") or "US",
+ order.email,
+ ]
+ )
+ return buffer.getvalue()
diff --git a/site/shipping/templates/shipping/detail.html b/site/shipping/templates/shipping/detail.html
new file mode 100644
index 0000000..c70de17
--- /dev/null
+++ b/site/shipping/templates/shipping/detail.html
@@ -0,0 +1,25 @@
+{% extends "portal_base.html" %}
+{% block title %}{{ shipment.order.number }} · Shipping{% endblock %}
+{% block topbar_title %}{{ shipment.order.number }}{% endblock %}
+{% block portal_content %}
+{{ shipment.order.email }} · {{ shipment.get_status_display }}
+{% if shipment.tracking_number %}Tracking: {{ shipment.tracking_number }}
{% endif %}
+{% if shipment.label_url %}Download label
{% endif %}
+{% if shipment.status != 'labeled' %}
+
+{% endif %}
+← All shipments
+{% endblock %}
diff --git a/site/shipping/templates/shipping/list.html b/site/shipping/templates/shipping/list.html
new file mode 100644
index 0000000..ed685e2
--- /dev/null
+++ b/site/shipping/templates/shipping/list.html
@@ -0,0 +1,43 @@
+{% extends "portal_base.html" %}
+{% block title %}Shipping · Portal{% endblock %}
+{% block topbar_title %}Shipping{% endblock %}
+{% block portal_content %}
+Pirate Ship CSV
+Unshipped paid orders
+
+ | Order | Email | |
|---|
+
+ {% for order in unshipped %}
+
+ | {{ order.number }} |
+ {{ order.email }} |
+
+
+ |
+
+ {% empty %}
+ | No paid orders waiting to ship. |
+ {% endfor %}
+
+
+Shipments
+
+ | Order | Status | Tracking |
|---|
+
+ {% for shipment in shipments %}
+
+ | {{ shipment.order.number }} |
+ {{ shipment.get_status_display }} |
+ {{ shipment.tracking_number|default:"—" }} |
+
+ {% empty %}
+ | No shipments yet. |
+ {% endfor %}
+
+
+{% endblock %}
diff --git a/site/shipping/tests.py b/site/shipping/tests.py
new file mode 100644
index 0000000..4818d04
--- /dev/null
+++ b/site/shipping/tests.py
@@ -0,0 +1,84 @@
+from decimal import Decimal
+
+from django.contrib.auth import get_user_model
+from django.test import Client, TestCase
+from django.urls import reverse
+
+from shipping.models import Shipment
+from shipping.services import buy_label, create_shipment_for_order, pirate_ship_csv, quote_rates
+from shop.models import Order
+
+
+class ShippingServiceTests(TestCase):
+ def setUp(self):
+ self.order = Order.objects.create(
+ number="ORD-20260101-001",
+ email="buyer@example.com",
+ customer_name="Pat Lee",
+ status=Order.Status.PAID,
+ amount=Decimal("18.00"),
+ shipping_address={
+ "line1": "123 Main",
+ "city": "Aurora",
+ "state": "IL",
+ "zip": "60506",
+ "country": "US",
+ },
+ )
+
+ def test_quote_and_buy_stub_label(self):
+ shipment = create_shipment_for_order(self.order)
+ rates = quote_rates(shipment)
+ self.assertGreaterEqual(len(rates), 1)
+ shipment.refresh_from_db()
+ self.assertEqual(shipment.status, Shipment.Status.RATED)
+ buy_label(shipment, rate_id=rates[0]["id"])
+ shipment.refresh_from_db()
+ self.assertEqual(shipment.status, Shipment.Status.LABELED)
+ self.assertTrue(shipment.tracking_number)
+
+ def test_pirate_ship_csv_includes_unshipped(self):
+ csv_body = pirate_ship_csv()
+ self.assertIn("ORD-20260101-001", csv_body)
+ self.assertIn("123 Main", csv_body)
+ self.assertIn("buyer@example.com", csv_body)
+
+ def test_csv_omits_labeled_orders(self):
+ shipment = create_shipment_for_order(self.order)
+ quote_rates(shipment)
+ buy_label(shipment)
+ self.assertNotIn(self.order.number, pirate_ship_csv())
+
+
+class ShippingPortalTests(TestCase):
+ def setUp(self):
+ User = get_user_model()
+ self.user = User.objects.create_user("shipper", password="test-pass-123")
+ self.client = Client()
+ self.client.login(username="shipper", password="test-pass-123")
+ self.order = Order.objects.create(
+ number="ORD-20260101-002",
+ email="a@example.com",
+ status=Order.Status.PAID,
+ amount=Decimal("9.00"),
+ shipping_address={"line1": "9 Oak", "city": "Town", "state": "IL", "zip": "60189"},
+ )
+
+ def test_list_requires_login(self):
+ self.assertEqual(Client().get(reverse("shipping:shipment_list")).status_code, 302)
+
+ def test_create_shipment_from_portal(self):
+ response = self.client.post(
+ reverse("shipping:shipment_create"),
+ {"order": str(self.order.pk), "weight_oz": "8"},
+ )
+ self.assertEqual(response.status_code, 302)
+ shipment = Shipment.objects.get()
+ self.assertEqual(shipment.weight_oz, 8)
+ self.assertEqual(shipment.status, Shipment.Status.RATED)
+
+ def test_csv_export(self):
+ response = self.client.get(reverse("shipping:pirate_ship_export"))
+ self.assertEqual(response.status_code, 200)
+ self.assertEqual(response["Content-Type"], "text/csv")
+ self.assertIn(b"ORD-20260101-002", response.content)
diff --git a/site/shipping/urls.py b/site/shipping/urls.py
new file mode 100644
index 0000000..5d26350
--- /dev/null
+++ b/site/shipping/urls.py
@@ -0,0 +1,13 @@
+from django.urls import path
+
+from shipping import views
+
+app_name = "shipping"
+
+urlpatterns = [
+ path("", views.shipment_list, name="shipment_list"),
+ path("new/", views.shipment_create, name="shipment_create"),
+ path("export/pirate-ship.csv", views.pirate_ship_export, name="pirate_ship_export"),
+ path("/", views.shipment_detail, name="shipment_detail"),
+ path("/buy/", views.shipment_buy, name="shipment_buy"),
+]
diff --git a/site/shipping/views.py b/site/shipping/views.py
new file mode 100644
index 0000000..dae8018
--- /dev/null
+++ b/site/shipping/views.py
@@ -0,0 +1,86 @@
+import logging
+
+from django.contrib import messages
+from django.contrib.auth.decorators import login_required
+from django.http import HttpResponse
+from django.shortcuts import get_object_or_404, redirect, render
+from django.views.decorators.http import require_http_methods, require_POST
+
+from shipping.models import Shipment
+from shipping.services import (
+ ShippingError,
+ buy_label,
+ create_shipment_for_order,
+ pirate_ship_csv,
+ quote_rates,
+)
+from shop.models import Order
+
+logger = logging.getLogger(__name__)
+
+
+@login_required
+def shipment_list(request):
+ shipments = Shipment.objects.select_related("order")[:200]
+ labeled = Shipment.objects.filter(status=Shipment.Status.LABELED).values_list(
+ "order_id", flat=True
+ )
+ unshipped = Order.objects.filter(status=Order.Status.PAID).exclude(pk__in=labeled)
+ return render(
+ request,
+ "shipping/list.html",
+ {"shipments": shipments, "unshipped": unshipped},
+ )
+
+
+@login_required
+@require_POST
+def shipment_create(request):
+ order = get_object_or_404(Order, pk=request.POST.get("order"))
+ try:
+ weight = int(request.POST.get("weight_oz") or "16")
+ except ValueError:
+ weight = 16
+ try:
+ shipment = create_shipment_for_order(order, weight_oz=weight)
+ quote_rates(shipment)
+ except ShippingError as exc:
+ messages.error(request, str(exc))
+ return redirect("shipping:shipment_list")
+ except Exception as exc: # noqa: BLE001
+ logger.exception("rate quote failed")
+ messages.error(request, f"Could not quote rates: {exc}")
+ return redirect("shipping:shipment_list")
+ return redirect("shipping:shipment_detail", pk=shipment.pk)
+
+
+@login_required
+def shipment_detail(request, pk):
+ shipment = get_object_or_404(Shipment.objects.select_related("order"), pk=pk)
+ return render(request, "shipping/detail.html", {"shipment": shipment})
+
+
+@login_required
+@require_POST
+def shipment_buy(request, pk):
+ shipment = get_object_or_404(Shipment, pk=pk)
+ rate_id = (request.POST.get("rate_id") or "").strip()
+ try:
+ buy_label(shipment, rate_id=rate_id)
+ except ShippingError as exc:
+ messages.error(request, str(exc))
+ except Exception as exc: # noqa: BLE001
+ logger.exception("buy label failed")
+ messages.error(request, f"Could not buy label: {exc}")
+ else:
+ messages.success(request, f"Label created for {shipment.order.number}.")
+ return redirect("shipping:shipment_detail", pk=shipment.pk)
+
+
+@login_required
+@require_http_methods(["GET"])
+def pirate_ship_export(request):
+ body = pirate_ship_csv()
+ response = HttpResponse(body, content_type="text/csv")
+ response["Content-Disposition"] = 'attachment; filename="pirate-ship-orders.csv"'
+ return response
diff --git a/site/shop/__init__.py b/site/shop/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/site/shop/admin.py b/site/shop/admin.py
new file mode 100644
index 0000000..ae6377c
--- /dev/null
+++ b/site/shop/admin.py
@@ -0,0 +1,24 @@
+from django.contrib import admin
+
+from shop.models import Order, OrderItem, Product
+
+
+@admin.register(Product)
+class ProductAdmin(admin.ModelAdmin):
+ list_display = ("name", "sku", "price", "stock_qty", "fulfillment", "is_published")
+ list_filter = ("fulfillment", "is_published")
+ search_fields = ("name", "sku")
+ prepopulated_fields = {"slug": ("name",)}
+
+
+class OrderItemInline(admin.TabularInline):
+ model = OrderItem
+ extra = 0
+
+
+@admin.register(Order)
+class OrderAdmin(admin.ModelAdmin):
+ list_display = ("number", "email", "amount", "status", "created_at")
+ list_filter = ("status",)
+ search_fields = ("number", "email", "customer_name")
+ inlines = [OrderItemInline]
diff --git a/site/shop/apps.py b/site/shop/apps.py
new file mode 100644
index 0000000..acd925a
--- /dev/null
+++ b/site/shop/apps.py
@@ -0,0 +1,12 @@
+from django.apps import AppConfig
+
+
+class ShopConfig(AppConfig):
+ default_auto_field = "django.db.models.BigAutoField"
+ name = "shop"
+ verbose_name = "E-commerce"
+
+ def ready(self):
+ from shop import hooks
+
+ hooks.register()
diff --git a/site/shop/hooks.py b/site/shop/hooks.py
new file mode 100644
index 0000000..8eab249
--- /dev/null
+++ b/site/shop/hooks.py
@@ -0,0 +1,53 @@
+from core.registry import (
+ register_dashboard_collector,
+ register_feature,
+ register_portal_nav,
+ register_public_nav,
+)
+
+
+def register() -> None:
+ register_feature("shop")
+ register_public_nav(section="shop", label="Shop", url_name="shop:list", order=30)
+ register_portal_nav(
+ section="shop_sales",
+ label="Sales",
+ url_name="shop_portal:sales",
+ group="Retail",
+ order=5,
+ )
+ register_portal_nav(
+ section="shop_products",
+ label="Products",
+ url_name="shop_portal:product_list",
+ group="Retail",
+ order=10,
+ )
+ register_portal_nav(
+ section="shop_orders",
+ label="Orders",
+ url_name="shop_portal:order_list",
+ group="Retail",
+ order=20,
+ )
+ register_dashboard_collector(_dashboard)
+
+
+def _dashboard(request) -> dict:
+ from shop.models import Order, Product
+ from shop.stats import sales_summary
+
+ sales = sales_summary()
+ return {
+ "open_shop_orders": Order.objects.filter(
+ status__in=[Order.Status.OPEN, Order.Status.PAID]
+ ).count(),
+ "low_stock_products": Product.objects.filter(
+ is_published=True,
+ track_inventory=True,
+ fulfillment=Product.Fulfillment.STOCKED,
+ stock_qty__lte=3,
+ ).count(),
+ "shop_sales_30d": sales["order_count"],
+ "shop_revenue_30d": sales["revenue"],
+ }
diff --git a/site/shop/migrations/0001_initial.py b/site/shop/migrations/0001_initial.py
new file mode 100644
index 0000000..5e35ce2
--- /dev/null
+++ b/site/shop/migrations/0001_initial.py
@@ -0,0 +1,80 @@
+# Generated by Django 6.1 on 2026-09-06 11:17
+
+import django.db.models.deletion
+import uuid
+from decimal import Decimal
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+ initial = True
+
+ dependencies = [
+ ]
+
+ operations = [
+ migrations.CreateModel(
+ name='Order',
+ fields=[
+ ('created_at', models.DateTimeField(auto_now_add=True)),
+ ('updated_at', models.DateTimeField(auto_now=True)),
+ ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+ ('number', models.CharField(max_length=32, unique=True)),
+ ('email', models.EmailField(max_length=254)),
+ ('customer_name', models.CharField(blank=True, max_length=200)),
+ ('status', models.CharField(choices=[('draft', 'Draft'), ('open', 'Open'), ('paid', 'Paid'), ('fulfilled', 'Fulfilled'), ('cancelled', 'Cancelled')], default='draft', max_length=16)),
+ ('amount', models.DecimalField(decimal_places=2, default=Decimal('0'), max_digits=10)),
+ ('currency', models.CharField(default='usd', max_length=8)),
+ ('shipping_address', models.JSONField(blank=True, default=dict)),
+ ('stripe_checkout_session_id', models.CharField(blank=True, max_length=255)),
+ ('hosted_checkout_url', models.URLField(blank=True)),
+ ('paid_at', models.DateTimeField(blank=True, null=True)),
+ ('notes', models.TextField(blank=True)),
+ ],
+ options={
+ 'ordering': ['-created_at'],
+ },
+ ),
+ migrations.CreateModel(
+ name='Product',
+ fields=[
+ ('created_at', models.DateTimeField(auto_now_add=True)),
+ ('updated_at', models.DateTimeField(auto_now=True)),
+ ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+ ('name', models.CharField(max_length=200)),
+ ('slug', models.SlugField(max_length=220, unique=True)),
+ ('sku', models.CharField(max_length=64, unique=True)),
+ ('description', models.TextField(blank=True)),
+ ('price', models.DecimalField(decimal_places=2, max_digits=10)),
+ ('currency', models.CharField(default='usd', max_length=8)),
+ ('fulfillment', models.CharField(choices=[('stocked', 'On-hand stock'), ('made_to_order', 'Made to order')], default='stocked', max_length=16)),
+ ('stock_qty', models.IntegerField(default=0)),
+ ('print_minutes', models.PositiveIntegerField(default=0, help_text='Estimated print time per unit (made-to-order).')),
+ ('filament_grams', models.PositiveIntegerField(default=0)),
+ ('is_published', models.BooleanField(default=False)),
+ ('track_inventory', models.BooleanField(default=True)),
+ ],
+ options={
+ 'ordering': ['name'],
+ },
+ ),
+ migrations.CreateModel(
+ name='OrderItem',
+ fields=[
+ ('created_at', models.DateTimeField(auto_now_add=True)),
+ ('updated_at', models.DateTimeField(auto_now=True)),
+ ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+ ('name', models.CharField(max_length=200)),
+ ('sku', models.CharField(max_length=64)),
+ ('quantity', models.PositiveIntegerField(default=1)),
+ ('unit_price', models.DecimalField(decimal_places=2, max_digits=10)),
+ ('print_minutes', models.PositiveIntegerField(default=0)),
+ ('order', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='items', to='shop.order')),
+ ('product', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='order_items', to='shop.product')),
+ ],
+ options={
+ 'ordering': ['created_at'],
+ },
+ ),
+ ]
diff --git a/site/shop/migrations/__init__.py b/site/shop/migrations/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/site/shop/models.py b/site/shop/models.py
new file mode 100644
index 0000000..a1aa4bf
--- /dev/null
+++ b/site/shop/models.py
@@ -0,0 +1,118 @@
+from decimal import Decimal
+
+from django.db import models
+from django.urls import reverse
+from django.utils.text import slugify
+
+from core.models import TimeStampedModel, UUIDPrimaryKeyModel
+
+
+class Product(UUIDPrimaryKeyModel, TimeStampedModel):
+ class Fulfillment(models.TextChoices):
+ STOCKED = "stocked", "On-hand stock"
+ MADE_TO_ORDER = "made_to_order", "Made to order"
+
+ name = models.CharField(max_length=200)
+ slug = models.SlugField(max_length=220, unique=True)
+ sku = models.CharField(max_length=64, unique=True)
+ description = models.TextField(blank=True)
+ price = models.DecimalField(max_digits=10, decimal_places=2)
+ currency = models.CharField(max_length=8, default="usd")
+ fulfillment = models.CharField(
+ max_length=16,
+ choices=Fulfillment.choices,
+ default=Fulfillment.STOCKED,
+ )
+ stock_qty = models.IntegerField(default=0)
+ print_minutes = models.PositiveIntegerField(
+ default=0,
+ help_text="Estimated print time per unit (made-to-order).",
+ )
+ filament_grams = models.PositiveIntegerField(default=0)
+ is_published = models.BooleanField(default=False)
+ track_inventory = models.BooleanField(default=True)
+
+ class Meta:
+ ordering = ["name"]
+
+ def __str__(self) -> str:
+ return f"{self.name} ({self.sku})"
+
+ def get_absolute_url(self) -> str:
+ return reverse("shop:detail", kwargs={"slug": self.slug})
+
+ @property
+ def amount_cents(self) -> int:
+ return int((self.price * Decimal("100")).quantize(Decimal("1")))
+
+ def save(self, *args, **kwargs):
+ if not self.slug:
+ base = slugify(self.name)[:200] or "product"
+ slug = base
+ n = 2
+ while Product.objects.filter(slug=slug).exclude(pk=self.pk).exists():
+ slug = f"{base}-{n}"
+ n += 1
+ self.slug = slug
+ if not self.sku:
+ self.sku = (self.slug or "sku").upper().replace("-", "")[:64]
+ super().save(*args, **kwargs)
+
+
+class Order(UUIDPrimaryKeyModel, TimeStampedModel):
+ class Status(models.TextChoices):
+ DRAFT = "draft", "Draft"
+ OPEN = "open", "Open"
+ PAID = "paid", "Paid"
+ FULFILLED = "fulfilled", "Fulfilled"
+ CANCELLED = "cancelled", "Cancelled"
+
+ number = models.CharField(max_length=32, unique=True)
+ email = models.EmailField()
+ customer_name = models.CharField(max_length=200, blank=True)
+ status = models.CharField(
+ max_length=16, choices=Status.choices, default=Status.DRAFT
+ )
+ amount = models.DecimalField(max_digits=10, decimal_places=2, default=Decimal("0"))
+ currency = models.CharField(max_length=8, default="usd")
+ shipping_address = models.JSONField(default=dict, blank=True)
+ stripe_checkout_session_id = models.CharField(max_length=255, blank=True)
+ hosted_checkout_url = models.URLField(blank=True)
+ paid_at = models.DateTimeField(null=True, blank=True)
+ notes = models.TextField(blank=True)
+
+ class Meta:
+ ordering = ["-created_at"]
+
+ def __str__(self) -> str:
+ return f"{self.number} · {self.email} · {self.amount}"
+
+ @property
+ def amount_cents(self) -> int:
+ return int((self.amount * Decimal("100")).quantize(Decimal("1")))
+
+
+class OrderItem(UUIDPrimaryKeyModel, TimeStampedModel):
+ order = models.ForeignKey(Order, on_delete=models.CASCADE, related_name="items")
+ product = models.ForeignKey(
+ Product,
+ null=True,
+ blank=True,
+ on_delete=models.SET_NULL,
+ related_name="order_items",
+ )
+ name = models.CharField(max_length=200)
+ sku = models.CharField(max_length=64)
+ quantity = models.PositiveIntegerField(default=1)
+ unit_price = models.DecimalField(max_digits=10, decimal_places=2)
+ print_minutes = models.PositiveIntegerField(default=0)
+
+ class Meta:
+ ordering = ["created_at"]
+
+ def __str__(self) -> str:
+ return f"{self.quantity}× {self.name}"
+
+ @property
+ def line_total(self) -> Decimal:
+ return self.unit_price * self.quantity
diff --git a/site/shop/portal_urls.py b/site/shop/portal_urls.py
new file mode 100644
index 0000000..cbd30b0
--- /dev/null
+++ b/site/shop/portal_urls.py
@@ -0,0 +1,20 @@
+from django.urls import path
+
+from shop import views
+
+app_name = "shop_portal"
+
+urlpatterns = [
+ path("sales/", views.portal_sales, name="sales"),
+ path("products/", views.portal_product_list, name="product_list"),
+ path("products/new/", views.portal_product_edit, name="product_new"),
+ path("products//", views.portal_product_edit, name="product_edit"),
+ path(
+ "products//stock/",
+ views.portal_stock_adjust,
+ name="product_stock",
+ ),
+ path("orders/", views.portal_order_list, name="order_list"),
+ path("orders//", views.portal_order_detail, name="order_detail"),
+ path("webhooks/stripe/", views.stripe_webhook, name="stripe_webhook"),
+]
diff --git a/site/shop/public_urls.py b/site/shop/public_urls.py
new file mode 100644
index 0000000..dc4f327
--- /dev/null
+++ b/site/shop/public_urls.py
@@ -0,0 +1,16 @@
+from django.urls import path
+
+from shop import views
+
+app_name = "shop"
+
+urlpatterns = [
+ path("", views.product_list, name="list"),
+ path("cart/", views.cart_view, name="cart"),
+ path("cart/add//", views.cart_add, name="cart_add"),
+ path("cart/update//", views.cart_update, name="cart_update"),
+ path("checkout/", views.checkout, name="checkout"),
+ path("checkout//success/", views.checkout_success, name="checkout_success"),
+ path("checkout//cancel/", views.checkout_cancel, name="checkout_cancel"),
+ path("/", views.product_detail, name="detail"),
+]
diff --git a/site/shop/services.py b/site/shop/services.py
new file mode 100644
index 0000000..bb8639b
--- /dev/null
+++ b/site/shop/services.py
@@ -0,0 +1,305 @@
+"""Catalog, cart, inventory, and Stripe checkout for FEATURE_SHOP."""
+
+from __future__ import annotations
+
+import logging
+from datetime import date
+from decimal import Decimal
+
+from django.conf import settings
+from django.db import transaction
+from django.db.models import F, Sum
+from django.utils import timezone
+
+from shop.models import Order, OrderItem, Product
+
+logger = logging.getLogger(__name__)
+
+CART_SESSION_KEY = "shop_cart"
+
+
+class ShopError(RuntimeError):
+ pass
+
+
+def _stripe():
+ secret = (settings.STRIPE_SECRET_KEY or "").strip()
+ if not secret:
+ raise ShopError("STRIPE_SECRET_KEY is not configured")
+ try:
+ import stripe
+ except ImportError as exc:
+ raise ShopError("stripe package is not installed") from exc
+ stripe.api_key = secret
+ return stripe
+
+
+def next_order_number() -> str:
+ today = date.today().strftime("%Y%m%d")
+ prefix = f"ORD-{today}-"
+ existing = Order.objects.filter(number__startswith=prefix).count()
+ return f"{prefix}{existing + 1:03d}"
+
+
+def get_cart(session) -> dict[str, int]:
+ raw = session.get(CART_SESSION_KEY) or {}
+ cart: dict[str, int] = {}
+ for key, qty in raw.items():
+ try:
+ n = int(qty)
+ except (TypeError, ValueError):
+ continue
+ if n > 0:
+ cart[str(key)] = n
+ return cart
+
+
+def save_cart(session, cart: dict[str, int]) -> None:
+ session[CART_SESSION_KEY] = cart
+ session.modified = True
+
+
+def add_to_cart(session, product: Product, quantity: int = 1) -> dict[str, int]:
+ if quantity < 1:
+ raise ShopError("Quantity must be at least 1.")
+ cart = get_cart(session)
+ pid = str(product.pk)
+ cart[pid] = cart.get(pid, 0) + quantity
+ save_cart(session, cart)
+ return cart
+
+
+def set_cart_qty(session, product: Product, quantity: int) -> dict[str, int]:
+ cart = get_cart(session)
+ pid = str(product.pk)
+ if quantity < 1:
+ cart.pop(pid, None)
+ else:
+ cart[pid] = quantity
+ save_cart(session, cart)
+ return cart
+
+
+def cart_lines(session) -> list[dict]:
+ cart = get_cart(session)
+ products = {
+ str(p.pk): p
+ for p in Product.objects.filter(pk__in=cart.keys(), is_published=True)
+ }
+ lines = []
+ for pid, qty in cart.items():
+ product = products.get(pid)
+ if not product:
+ continue
+ lines.append(
+ {
+ "product": product,
+ "quantity": qty,
+ "unit_price": product.price,
+ "line_total": product.price * qty,
+ }
+ )
+ return lines
+
+
+def cart_total(lines: list[dict]) -> Decimal:
+ return sum((line["line_total"] for line in lines), Decimal("0"))
+
+
+def queued_print_minutes() -> int:
+ total = (
+ OrderItem.objects.filter(
+ order__status__in=[Order.Status.OPEN, Order.Status.PAID],
+ product__fulfillment=Product.Fulfillment.MADE_TO_ORDER,
+ ).aggregate(total=Sum(F("print_minutes") * F("quantity")))["total"]
+ or 0
+ )
+ return int(total)
+
+
+def available_qty(product: Product) -> int | None:
+ """Units that can be sold. None means unlimited (untracked made-to-order)."""
+ if not product.track_inventory:
+ return None
+ if product.fulfillment == Product.Fulfillment.STOCKED:
+ return max(product.stock_qty, 0)
+ limit = int(getattr(settings, "SHOP_PRINT_QUEUE_LIMIT_MINUTES", 0) or 0)
+ if not limit or not product.print_minutes:
+ return None
+ remaining_minutes = max(limit - queued_print_minutes(), 0)
+ return remaining_minutes // product.print_minutes
+
+
+def assert_can_sell(product: Product, quantity: int) -> None:
+ if quantity < 1:
+ raise ShopError("Quantity must be at least 1.")
+ if not product.is_published:
+ raise ShopError("This product is not available.")
+ avail = available_qty(product)
+ if avail is not None and quantity > avail:
+ raise ShopError(f"Only {avail} of {product.name} available.")
+
+
+def adjust_stock(product: Product, delta: int) -> Product:
+ """Increment (positive) or decrement (negative) on-hand stock."""
+ product.stock_qty = product.stock_qty + delta
+ if product.stock_qty < 0:
+ raise ShopError(f"Insufficient stock for {product.sku}.")
+ product.save(update_fields=["stock_qty", "updated_at"])
+ return product
+
+
+def create_order_from_cart(
+ session,
+ *,
+ email: str,
+ customer_name: str = "",
+ shipping_address: dict | None = None,
+ notes: str = "",
+) -> Order:
+ lines = cart_lines(session)
+ if not lines:
+ raise ShopError("Cart is empty.")
+ email = (email or "").strip()
+ if not email:
+ raise ShopError("Email is required.")
+ for line in lines:
+ assert_can_sell(line["product"], line["quantity"])
+ currency = (settings.STRIPE_CURRENCY or "usd").lower()
+ with transaction.atomic():
+ order = Order.objects.create(
+ number=next_order_number(),
+ email=email,
+ customer_name=(customer_name or "").strip(),
+ status=Order.Status.DRAFT,
+ amount=cart_total(lines),
+ currency=currency,
+ shipping_address=shipping_address or {},
+ notes=notes,
+ )
+ for line in lines:
+ product = line["product"]
+ OrderItem.objects.create(
+ order=order,
+ product=product,
+ name=product.name,
+ sku=product.sku,
+ quantity=line["quantity"],
+ unit_price=product.price,
+ print_minutes=product.print_minutes,
+ )
+ return order
+
+
+def create_checkout_session(order: Order, *, success_url: str, cancel_url: str) -> str:
+ stripe = _stripe()
+ line_items = [
+ {
+ "quantity": item.quantity,
+ "price_data": {
+ "currency": (order.currency or "usd").lower(),
+ "unit_amount": int(
+ (item.unit_price * Decimal("100")).quantize(Decimal("1"))
+ ),
+ "product_data": {"name": item.name},
+ },
+ }
+ for item in order.items.all()
+ ]
+ if not line_items:
+ raise ShopError("Order has no items.")
+ session = stripe.checkout.Session.create(
+ mode="payment",
+ customer_email=order.email or None,
+ line_items=line_items,
+ metadata={"shop_order_id": str(order.pk), "order_number": order.number},
+ success_url=success_url,
+ cancel_url=cancel_url,
+ )
+ order.stripe_checkout_session_id = session.id
+ order.hosted_checkout_url = session.url or ""
+ order.status = Order.Status.OPEN
+ order.save(
+ update_fields=[
+ "stripe_checkout_session_id",
+ "hosted_checkout_url",
+ "status",
+ "updated_at",
+ ]
+ )
+ return session.url or ""
+
+
+def _reserve_inventory(order: Order) -> None:
+ for item in order.items.select_related("product"):
+ product = item.product
+ if product is None or not product.track_inventory:
+ continue
+ if product.fulfillment == Product.Fulfillment.STOCKED:
+ adjust_stock(product, -item.quantity)
+
+
+def _notify_pos(order: Order) -> None:
+ from django.apps import apps
+
+ if not apps.is_installed("pos_sync"):
+ return
+ from pos_sync.services import enqueue_online_sale
+
+ enqueue_online_sale(order)
+
+
+def mark_paid(order: Order, *, stripe_id: str = "") -> None:
+ if order.status == Order.Status.PAID:
+ return
+ with transaction.atomic():
+ locked = Order.objects.select_for_update().get(pk=order.pk)
+ if locked.status == Order.Status.PAID:
+ return
+ _reserve_inventory(locked)
+ locked.status = Order.Status.PAID
+ locked.paid_at = timezone.now()
+ locked.save(update_fields=["status", "paid_at", "updated_at"])
+ order.refresh_from_db()
+ try:
+ send_order_email(order)
+ except Exception:
+ logger.exception("order confirmation email failed for %s", order.number)
+ try:
+ _notify_pos(order)
+ except Exception:
+ logger.exception("POS notify failed for %s", order.number)
+
+
+def send_order_email(order: Order) -> bool:
+ to_email = (order.email or "").strip()
+ if not to_email:
+ raise ShopError("Order has no email address")
+ from django.core.mail import EmailMultiAlternatives
+
+ name = order.customer_name or "there"
+ amount = f"{order.amount} {order.currency.upper()}"
+ lines = "\n".join(
+ f"- {item.quantity}× {item.name} ({item.sku})" for item in order.items.all()
+ )
+ subject = f"Order {order.number} from {settings.SITE_NAME}"
+ text = (
+ f"Hi {name},\n\n"
+ f"We received order {order.number} for {amount}.\n\n"
+ f"{lines}\n\nThank you.\n"
+ )
+ html = (
+ f"Hi {name},
"
+ f"We received order {order.number} for "
+ f"{amount}.
"
+ f"{lines}"
+ )
+ mail = EmailMultiAlternatives(
+ subject=subject,
+ body=text,
+ from_email=settings.DEFAULT_FROM_EMAIL,
+ to=[to_email],
+ )
+ mail.attach_alternative(html, "text/html")
+ mail.send(fail_silently=False)
+ return True
diff --git a/site/shop/stats.py b/site/shop/stats.py
new file mode 100644
index 0000000..4466d4a
--- /dev/null
+++ b/site/shop/stats.py
@@ -0,0 +1,166 @@
+"""Sales dashboard aggregates for FEATURE_SHOP."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+
+from django.conf import settings
+from django.db.models import Count, F, Max, Q, Sum
+from django.utils import timezone
+
+from shop.models import Order, OrderItem
+
+SOLD_STATUSES = (Order.Status.PAID, Order.Status.FULFILLED)
+SALES_WINDOW_DAYS = 30
+
+
+def _money(value) -> Decimal:
+ return (value or Decimal("0")).quantize(Decimal("0.01"))
+
+
+def _window_start(days: int):
+ today = timezone.localdate()
+ start_date = today - timedelta(days=days - 1)
+ start_dt = timezone.make_aware(
+ datetime.combine(start_date, time.min),
+ timezone.get_current_timezone(),
+ )
+ return today, start_date, start_dt
+
+
+def _sold_orders(start_dt=None):
+ qs = Order.objects.filter(status__in=SOLD_STATUSES)
+ if start_dt is None:
+ return qs
+ return qs.filter(
+ Q(paid_at__gte=start_dt) | Q(paid_at__isnull=True, created_at__gte=start_dt)
+ )
+
+
+def _sale_date(order) -> date:
+ when = order.paid_at or order.created_at
+ return timezone.localtime(when).date()
+
+
+def _bar_pct(value: Decimal | int | float, peak: Decimal | int | float) -> int:
+ if not peak:
+ return 0
+ if not value:
+ return 0
+ return max(8, int(round((float(value) / float(peak)) * 100)))
+
+
+def sales_summary(*, days: int = SALES_WINDOW_DAYS) -> dict:
+ """Order count and revenue for the rolling sales window."""
+ _, _, start_dt = _window_start(days)
+ totals = _sold_orders(start_dt).aggregate(
+ order_count=Count("id"), revenue=Sum("amount")
+ )
+ return {
+ "order_count": int(totals["order_count"] or 0),
+ "revenue": _money(totals["revenue"]),
+ }
+
+
+def sales_dashboard(*, days: int = SALES_WINDOW_DAYS) -> dict:
+ """Paid/fulfilled order stats, daily series, and top products."""
+ _, start_date, start_dt = _window_start(days)
+ sold = _sold_orders(start_dt)
+ totals = sold.aggregate(order_count=Count("id"), revenue=Sum("amount"))
+ order_count = int(totals["order_count"] or 0)
+ revenue = _money(totals["revenue"])
+ units = int(
+ OrderItem.objects.filter(order__in=sold).aggregate(total=Sum("quantity"))[
+ "total"
+ ]
+ or 0
+ )
+ aov = _money(revenue / order_count) if order_count else Decimal("0.00")
+ currency = (settings.STRIPE_CURRENCY or "usd").lower()
+
+ by_day: dict = {
+ start_date + timedelta(days=offset): {
+ "count": 0,
+ "revenue": Decimal("0.00"),
+ }
+ for offset in range(days)
+ }
+ for order in sold.only("paid_at", "created_at", "amount"):
+ day = _sale_date(order)
+ bucket = by_day.get(day)
+ if bucket is None:
+ continue
+ bucket["count"] += 1
+ bucket["revenue"] += order.amount or Decimal("0")
+
+ peak_count = max((row["count"] for row in by_day.values()), default=0)
+ peak_revenue = max((row["revenue"] for row in by_day.values()), default=Decimal("0"))
+ daily_sales = []
+ daily_revenue = []
+ for index, (day, row) in enumerate(by_day.items()):
+ tick = index == 0 or index == days - 1 or day.weekday() == 0
+ label = f"{day.strftime('%b')} {day.day}"
+ daily_sales.append(
+ {
+ "date": day,
+ "label": label,
+ "count": row["count"],
+ "revenue": _money(row["revenue"]),
+ "pct": _bar_pct(row["count"], peak_count),
+ "tick": tick,
+ "tick_label": label if tick else "",
+ }
+ )
+ daily_revenue.append(
+ {
+ "date": day,
+ "label": label,
+ "count": row["count"],
+ "revenue": _money(row["revenue"]),
+ "pct": _bar_pct(row["revenue"], peak_revenue),
+ "tick": tick,
+ "tick_label": label if tick else "",
+ }
+ )
+
+ product_rows = list(
+ OrderItem.objects.filter(order__in=sold)
+ .values("sku")
+ .annotate(
+ units=Sum("quantity"),
+ revenue=Sum(F("unit_price") * F("quantity")),
+ product_name=Max("product__name"),
+ item_name=Max("name"),
+ )
+ .order_by("-units", "-revenue")[:8]
+ )
+ peak_units = max((int(row["units"] or 0) for row in product_rows), default=0)
+ top_products = []
+ for row in product_rows:
+ units_sold = int(row["units"] or 0)
+ top_products.append(
+ {
+ "sku": row["sku"],
+ "name": row["product_name"] or row["item_name"] or row["sku"],
+ "units": units_sold,
+ "revenue": _money(row["revenue"]),
+ "bar_pct": _bar_pct(units_sold, peak_units),
+ }
+ )
+
+ recent_orders = list(sold.order_by("-paid_at", "-created_at")[:8])
+
+ return {
+ "days": days,
+ "currency": currency,
+ "order_count": order_count,
+ "revenue": revenue,
+ "units_sold": units,
+ "aov": aov,
+ "daily_sales": daily_sales,
+ "daily_revenue": daily_revenue,
+ "top_products": top_products,
+ "recent_orders": recent_orders,
+ "has_sales": order_count > 0,
+ }
diff --git a/site/shop/templates/shop/cancel.html b/site/shop/templates/shop/cancel.html
new file mode 100644
index 0000000..263f88d
--- /dev/null
+++ b/site/shop/templates/shop/cancel.html
@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+{% block title %}Checkout cancelled{% endblock %}
+{% block content %}
+
+
Checkout cancelled
+
Order {{ order.number }} was not paid. You can return to the cart.
+
+
Cart
+ {% for line in lines %}
+
+ {{ line.product.name }}
+ · {{ line.quantity }} × {{ line.unit_price }} = {{ line.line_total }}
+
+
+ {% empty %}
+
Cart is empty.
+ {% endfor %}
+ {% if lines %}
+
Total: {{ total }}
+
Checkout
+ {% endif %}
+
+
Checkout
+
Total: {{ total }}
+
+
+
← Shop
+
{{ product.name }}
+
{{ product.price }} {{ product.currency|upper }} · {{ product.sku }}
+
{{ product.description|linebreaks }}
+ {% if available is not None %}
+
{{ available }} in stock
+ {% endif %}
+
+
+
Shop
+
View cart
+ {% for product in products %}
+
+
+ {{ product.price }} {{ product.currency|upper }} · {{ product.sku }}
+ {{ product.description|truncatewords:40 }}
+
+ {% empty %}
+
No products yet.
+ {% endfor %}
+
{{ order.email }} · {{ order.amount }} {{ order.currency|upper }} · {{ order.get_status_display }}
+{% if order.customer_name %}{{ order.customer_name }}
{% endif %}
+
+ | Item | SKU | Qty | Price |
|---|
+
+ {% for item in order.items.all %}
+
+ | {{ item.name }} |
+ {{ item.sku }} |
+ {{ item.quantity }} |
+ {{ item.unit_price }} |
+
+ {% endfor %}
+
+
+← All orders
+{% endblock %}
diff --git a/site/shop/templates/shop/portal/orders.html b/site/shop/templates/shop/portal/orders.html
new file mode 100644
index 0000000..63af63f
--- /dev/null
+++ b/site/shop/templates/shop/portal/orders.html
@@ -0,0 +1,20 @@
+{% extends "portal_base.html" %}
+{% block title %}Orders · Portal{% endblock %}
+{% block topbar_title %}Orders{% endblock %}
+{% block portal_content %}
+
+ | Number | Email | Amount | Status |
|---|
+
+ {% for order in orders %}
+
+ | {{ order.number }} |
+ {{ order.email }} |
+ {{ order.amount }} {{ order.currency|upper }} |
+ {{ order.get_status_display }} |
+
+ {% empty %}
+ | No orders yet. |
+ {% endfor %}
+
+
+{% endblock %}
diff --git a/site/shop/templates/shop/portal/product_edit.html b/site/shop/templates/shop/portal/product_edit.html
new file mode 100644
index 0000000..e2d7d4d
--- /dev/null
+++ b/site/shop/templates/shop/portal/product_edit.html
@@ -0,0 +1,33 @@
+{% extends "portal_base.html" %}
+{% block title %}{% if product %}Edit{% else %}New{% endif %} product · Portal{% endblock %}
+{% block topbar_title %}{% if product %}Edit product{% else %}New product{% endif %}{% endblock %}
+{% block portal_content %}
+
+{% if product %}
+
+{% endif %}
+{% endblock %}
diff --git a/site/shop/templates/shop/portal/products.html b/site/shop/templates/shop/portal/products.html
new file mode 100644
index 0000000..8ddde93
--- /dev/null
+++ b/site/shop/templates/shop/portal/products.html
@@ -0,0 +1,22 @@
+{% extends "portal_base.html" %}
+{% block title %}Products · Portal{% endblock %}
+{% block topbar_title %}Products{% endblock %}
+{% block portal_content %}
+New product
+
+ | Name | SKU | Price | Stock | Status |
|---|
+
+ {% for product in products %}
+
+ | {{ product.name }} |
+ {{ product.sku }} |
+ {{ product.price }} {{ product.currency|upper }} |
+ {{ product.stock_qty }} |
+ {% if product.is_published %}Published{% else %}Draft{% endif %} |
+
+ {% empty %}
+ | No products yet. |
+ {% endfor %}
+
+
+{% endblock %}
diff --git a/site/shop/templates/shop/portal/sales.html b/site/shop/templates/shop/portal/sales.html
new file mode 100644
index 0000000..2d82d2a
--- /dev/null
+++ b/site/shop/templates/shop/portal/sales.html
@@ -0,0 +1,147 @@
+{% extends "portal_base.html" %}
+{% block title %}Sales · Portal{% endblock %}
+{% block topbar_title %}Sales{% endblock %}
+{% block portal_content %}
+
+
+
Orders ({{ days }} days)
+
{{ order_count }}
+
+
+
Revenue ({{ days }} days)
+
{{ revenue }} {{ currency|upper }}
+
+
+
Units sold
+
{{ units_sold }}
+
+
+
Average order
+
{{ aov }} {{ currency|upper }}
+
+
+
+
Orders per day
+ Last {{ days }} days
+
+
+
+ {% for bar in daily_sales %}
+
+
+
+ {% if bar.tick %}{{ bar.tick_label }}{% else %} {% endif %}
+
+
+ {% endfor %}
+
+ {% if not has_sales %}
+
No paid orders in this window.
+ {% endif %}
+
+
+
+
Revenue per day
+ Last {{ days }} days
+
+
+
+ {% for bar in daily_revenue %}
+
+
+
+ {% if bar.tick %}{{ bar.tick_label }}{% else %} {% endif %}
+
+
+ {% endfor %}
+
+
+
+
+
+
Top products
+ By units sold
+
+
+ {% if top_products %}
+
+ {% for row in top_products %}
+
+
{{ row.name }}
+
+
{{ row.units }}
+
+ {% endfor %}
+
+ {% else %}
+
No product sales yet.
+ {% endif %}
+
+
+
+
+
+
+
+ | Product | SKU | Units | Revenue |
|---|
+
+
+ {% for row in top_products %}
+
+ | {{ row.name }} |
+ {{ row.sku }} |
+ {{ row.units }} |
+ {{ row.revenue }} {{ currency|upper }} |
+
+ {% empty %}
+ | No paid line items in the last {{ days }} days. |
+ {% endfor %}
+
+
+
+
+
+
+
+
+
+ | Number | Customer | Amount | Status |
|---|
+
+
+ {% for order in recent_orders %}
+
+ | {{ order.number }} |
+ {{ order.customer_name|default:order.email }} |
+ {{ order.amount }} {{ order.currency|upper }} |
+ {{ order.get_status_display }} |
+
+ {% empty %}
+ | No paid orders yet. |
+ {% endfor %}
+
+
+
+
+
Thank you
+
Order {{ order.number }} is {{ order.get_status_display|lower }}.
+
A confirmation will go to {{ order.email }}.
+