Enterprise E-Commerce API

A production-oriented FastAPI backend for multi-category online retail. The project is implemented as a modular monolith that can later be split into identity, catalog, inventory, order, payment, procurement and fulfilment services.

Capabilities

Identity and security

• Registration and secure Argon2 password hashing
• JWT access tokens and rotating refresh tokens
• Email-verification workflow
• Password recovery and password change
• Account lockout after repeated failed logins
• Logout from one session or all sessions
• Redis-backed authentication rate limiting with a local fallback
• RBAC for customer, administrator, catalog manager, warehouse manager and support
• Request IDs, security response headers and audit logs

Catalog and inventory

• Categories, brands and multi-category products
• Generic SKU variants with size, color, display name and custom JSON attributes
• Product specifications, warranty, weight and product type
• Variant-level pricing, barcodes and inventory
• On-hand, reserved and available stock
• Immutable inventory movement ledger
• Search and filtering by category, brand, price, gender, size, color and featured status
• Low-stock reporting

Customer commerce

• Customer profiles and multiple shipping addresses
• Cart and wishlist
• Coupon validation with fixed or percentage discounts
• Taxes, shipping fees and free-shipping threshold
• Idempotent checkout
• COD, card and UPI workflows with a deterministic mock payment provider
• Immutable order-item and shipping-address snapshots
• Customer order history and cancellation
• Verified-purchase reviews
• Return, receiving, restocking and refund workflow

Procurement and fulfilment

• Supplier management
• Purchase orders and line items
• Approval and partial/full goods receipt
• Automatic inventory updates and receipt ledger entries
• Shipment creation, carrier and tracking number management
• Customer shipment tracking
• Delivery synchronization with the order lifecycle

Operations

• Administration dashboard and revenue metrics
• Catalog, warehouse, support and administrator workflows
• PostgreSQL and SQLite support
• Alembic migrations
• Redis and Celery worker configuration
• Docker Compose
• Swagger, ReDoc and exported OpenAPI JSON
• GitHub Actions CI
• End-to-end automated tests

Architecture

Web / Mobile / Admin clients
            |
            v
        FastAPI API
            |
   +--------+---------+----------+----------+
   |                  |          |          |
Identity & RBAC    Catalog    Commerce   Operations
   |                  |          |          |
   +------------------+----------+----------+
                       |
               SQLAlchemy ORM
                       |
                  PostgreSQL
                       |
              Redis + Celery worker

Run with Docker

Copy-Item .env.example .env
docker compose up --build

Seed demonstration data:

docker compose exec api python -m scripts.seed

Open:

• Swagger: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI: http://localhost:8000/openapi.json
• Health: http://localhost:8000/api/v1/health
• Readiness: http://localhost:8000/api/v1/ready

Local Windows setup

Use Python 3.12 or 3.13:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
Copy-Item .env.example .env

For local SQLite development, change .env:

DATABASE_URL=sqlite:///./ecommerce_api.db
REDIS_URL=

Run:

alembic upgrade head
python -m scripts.seed
uvicorn app.main:app --reload

Demo accounts

All seeded accounts use Password@123.

Role	Email
Administrator	admin@commerce.example.com
Catalog manager	catalog@commerce.example.com
Warehouse manager	warehouse@commerce.example.com
Support agent	support@commerce.example.com
Customer	customer@commerce.example.com

Typical end-to-end workflow

1. Log in as an administrator or catalog manager.
2. Create categories, brands, products and SKU variants.
3. Create a supplier and purchase order.
4. Approve and receive the purchase order to update inventory.
5. Register or log in as a customer.
6. Add a shipping address and cart items.
7. Validate a coupon.
8. Checkout using an Idempotency-Key header.
9. Confirm a card/UPI payment or select COD.
10. Process and pack the order.
11. Create a shipment and update delivery status.
12. Submit a verified-purchase review or return request.
13. Receive, restock and refund the return.
14. Review dashboard metrics and audit events.

Idempotency

Checkout and online payment endpoints require an Idempotency-Key header. A retry using the same key returns the existing resource rather than creating a duplicate.

curl -X POST http://localhost:8000/api/v1/orders/checkout \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-user-42-0001" \
  -d '{"address_id":1,"payment_method":"card","coupon_code":"WELCOME10"}'

Payment integration

The included card and UPI flow is a safe mock provider for local development and automated testing. Replace it with a PCI-compliant payment adapter and signed webhook verification before processing real payments.

Migrations

alembic upgrade head

After model changes:

alembic revision --autogenerate -m "describe the change"
alembic upgrade head

Tests

pytest

The automated suite validates authentication recovery, catalog setup, procurement, inventory receiving, addresses, cart, idempotent checkout, payment, fulfilment, shipment tracking, delivery, reviews, returns, refunds, dashboard reporting and OpenAPI generation.

Main route groups

Area	Base path
Authentication	/api/v1/auth/*
Users and addresses	/api/v1/users, /api/v1/addresses/*
Catalog and inventory	/api/v1/catalog/*
Cart and wishlist	/api/v1/cart/*, /api/v1/wishlist/*
Orders and payments	/api/v1/orders/*
Reviews and returns	/api/v1/products/{id}/reviews, /api/v1/returns/*
Procurement and shipments	/api/v1/operations/*
Administration	/api/v1/admin/*
System probes	/api/v1/health, /api/v1/ready

Production checklist

• Replace all development secrets and rotate them through a secret manager.
• Require verified email addresses where appropriate.
• Use managed PostgreSQL with backups and point-in-time recovery.
• Put the API behind TLS, a reverse proxy and a web application firewall.
• Use a managed Redis service for rate limits, queues and cache workloads.
• Integrate a PCI-compliant payment gateway and validate signed webhooks.
• Use object storage and signed URLs for product media.
• Add transactional email/SMS providers and delivery-status callbacks.
• Add OpenTelemetry traces, centralized logs, metrics and error monitoring.
• Add load, concurrency, security, payment-reconciliation and recovery tests.
• Perform legal, tax, privacy and security review before processing production customer data.

Structure

app/
  routes/
    admin.py
    auth.py
    catalog.py
    health.py
    operations.py
    shop.py
    users.py
  celery_app.py
  config.py
  database.py
  dependencies.py
  main.py
  models.py
  rate_limit.py
  schemas.py
  security.py
  services.py
  tasks.py
migrations/
scripts/
tests/
Dockerfile
docker-compose.yml
openapi.json