FlexCommerce

A complete, modular e-commerce and marketplace backend for Django + DRF — built for Nigeria and Africa, ready for anywhere.

FlexCommerce gives you everything behind a Jumia- or Konga-style store as a set of optional Django apps: catalogue, cart, checkout, orders, payments (Paystack, Flutterwave, bank transfer, pay on delivery, wallet), inventory, promotions, shipping with pickup stations, reviews and Q&A, multi-vendor marketplace, notifications (email, SMS, push, in-app), outgoing webhooks and analytics. You bring the frontend (web, mobile, POS) — FlexCommerce is strictly backend: a REST API, Django admin, signals, hooks and management commands.

pip install "flexcommerce[all]"

• Every feature is optional. Install one app or all fourteen; each works with only its declared dependencies.
• Safe under load. Stock reservations, coupon limits, flash-sale caps, wallet debits and checkout are race-free (conditional updates + row locks, verified by concurrent tests on PostgreSQL).
• Correct money. VAT-inclusive or exclusive pricing, discounts allocated per line, server-side re-pricing at checkout, amount + currency verification on every payment.
• Pluggable. Swap the price/tax handler, search engine, payment gateways, notification providers and order number format through settings; extend behaviour with in-transaction hooks; react to post-commit signals or signed JSON webhooks.
• Tested. ~630 tests across Python 3.10–3.14 and Django 4.2 / 5.2 / 6.x on SQLite and PostgreSQL.

Packages

pip install flexcommerce installs all of them except the marketplace (flexcommerce[marketplace] or [all]).

Quick start

# settings.py
from flexcommerce import FLEXCOMMERCE_APPS

INSTALLED_APPS = [
    "django.contrib.admin", "django.contrib.auth", "django.contrib.contenttypes",
    "django.contrib.sessions", "django.contrib.messages",
    "rest_framework",
    *FLEXCOMMERCE_APPS,            # or list only the apps you want
]

FLEXCOMMERCE = {
    "VAT_INCLUSIVE": True,                         # prices you enter already include 7.5% VAT
    "PAYSTACK_SECRET_KEY": env("PAYSTACK_SECRET_KEY"),
    "PAYMENT_CALLBACK_URL": "https://shop.example.com/checkout/complete",
    "PAYMENT_ALLOWED_CALLBACK_HOSTS": ["shop.example.com"],
    "FRONTEND_URL": "https://shop.example.com",
    "STORE_NAME": "Naija Mart",
    "ASYNC_EXECUTOR": "celery",                    # "sync" is fine for development
}

# urls.py
urlpatterns = [path("api/", include("flexcommerce_core.urls"))]   # mounts every installed app

python manage.py migrate
python manage.py seed_nigeria_shipping --with-methods   # 8 geopolitical zones + starter rates
python manage.py check                                   # FlexCommerce validates its configuration

Schedule the maintenance jobs (expired reservations, unpaid orders, abandoned carts, retries, payouts, analytics):

*/5 * * * * cd /srv/shop && ./venv/bin/python manage.py flexcommerce_run_jobs

(or schedule the Celery task flexcommerce.run_jobs with Celery beat.)

A customer can now browse GET /api/catalog/products/, POST /api/cart/add/, POST /api/checkout/ and pay. See docs/ for the full guide.

Documentation

• Integration guide — install, configure, first order, going to production
• Settings reference — every FLEXCOMMERCE option
• API reference — every endpoint
• Events, hooks, webhooks & notifications — how the apps talk to each other and to you
• Extending FlexCommerce — custom products, gateways, pricing, search, SMS providers
• Operations & scaling — jobs, Celery, caching, security checklist
• Migrating from pre-release code · Changelog · Security · Contributing

Requirements

Python 3.10+, Django 4.2 LTS / 5.x / 6.x, Django REST framework 3.14+. PostgreSQL is recommended in production (MySQL 8 works; SQLite is fine for development). A shared cache (Redis / Memcached) is recommended when you run more than one web process.

License

MIT © NzeStan