dj-stripe mirrors your Stripe data into Django models through webhooks

A local copy of Stripe, kept in step by a webhook

dj-stripe's premise is that most applications do not need to call Stripe on every request. The project description says it automatically syncs your Stripe data to your local database as pre-implemented Django models, so you can use the Django ORM to work with the data, which it argues is easier and faster.

The mechanism is a webhook endpoint. The README says you set up your webhook endpoint and start receiving model updates, and you then have a copy of all the Stripe models available as Django models as soon as they are updated. That is the whole design: Stripe is the system of record, and the local database is a materialised view of it that your application can query with joins, filters and aggregations.

The reason this pays off is that Stripe's own data model is a set of resources with a web API, and a join across them in application code means several round trips. In the local database it is one query. For a product with a dashboard, a customer list, a revenue report, or any feature that needs to relate a subscription to a customer and both to an invoice, the local copy is the difference between a screen that loads and one that does not.

The project is not a thin wrapper around the Stripe SDK. It implements the Stripe models as Django models, which means they participate in your app's migrations, admin, relationships and ORM behaviour. The package on PyPI is dj-stripe, and the repository carries a manage.py alongside the djstripe/ package, so it is laid out as a Django application.

What is covered, and where the coverage stops

The feature list is short and specific, which makes it easy to judge fit. dj-stripe supports Stripe Core, Stripe Billing with subscriptions, invoices and prices, Payment Methods and Payment Intents with SCA support, support for multiple accounts and API keys, and partial support for Stripe Connect. The README also says it is tested with the latest Stripe API, with a link to api_versions.md for which version that currently means.

The multi-account support is the item with the most operational weight. A platform that onboards merchants onto Stripe Connect ends up holding data for several Stripe accounts, and the fact that the library models that rather than assuming one account simplifies the data model considerably. The qualification is that Connect support is partial, and the README does not say which parts are covered, so a team whose revenue flows through connected accounts would want to check the api_versions.md and the changelog before relying on it.

SCA support in the Payment Methods and Payment Intents area matters for European deployments in particular, and its presence tells you the library tracks the newer payment APIs rather than only the classic card charge flow.

The sibling projects are named in the README, which is a useful signal about the shape of the ecosystem. dj-paypal covers PayPal and dj-paddle covers Paddle, both listed alongside dj-stripe as similar libraries. and the existence of the alternatives means the dj-stripe design is a recognised way to solve this problem rather than a one-off.

The database matters, and SQLite is called out as a bad idea

The requirements section is unusually specific about storage, and it is worth reading before you install anything.

Django 5.2 or newer is required, Python 3.11 or newer is required, and the PostgreSQL engine is recommended at version 12 or newer. The MySQL option is MariaDB 10.5 or newer, or MySQL 8.0 or newer. For SQLite the README says it is not recommended in production, and that version 3.26 or newer is required.

That SQLite line is the one to take seriously. A library that mirrors external data into local tables accumulates rows that change whenever a customer or a subscription changes upstream, and SQLite's single-writer model and weaker concurrency story make it a poor fit for a service whose writes are triggered by webhooks. The Django default of SQLite is exactly what a developer would get locally and might not think to change in production.

The pyproject.toml reflects the same split at the package level. psycopg at 3.3.4 or newer is an optional extra under postgres, mysqlclient 2.2.0 or newer is an optional extra under mysql, and the base dependency list is just django 5.2 or newer and stripe 15.0.1 or newer, with an upper bound below 16. Pinning the Stripe SDK to a major version is a sensible choice for a library that models an API that changes.

The version classifiers list Django 5.2, 6.0 and 6.1, which tells you the project tracks new Django releases as they land.

Packaging, tests and the toolchain behind the release

The project is built with hatchling, and the build configuration in pyproject.toml is explicit about what ships. The wheel target packages the djstripe directory, and the sdist includes the djstripe package along with CONTRIBUTING.md and LICENSE. The project metadata names three authors, Alexander Kavanaugh, Jerome Leclanche and Abe Hanoka, and the project is described as Production/Stable in its development status classifier.

The test and lint setup is modern Python practice. The dev dependency group pulls in pytest with pytest-django, pytest-dotenv, mypy with django-stubs, ruff and pre-commit, while the ci group adds coverage with the toml extra, tox and tox-gh. A tox.ini sits at the top level of the repository, and the CI workflow badge points at a GitHub Actions ci.yml file. The pre-commit configuration at the root means the same checks run before a commit is made.

Ruff does the linting, and the pyproject.toml selects rule sets by their flake8 origins, including bugbear, comprehensions and pycodestyle. The presence of mypy with django-stubs means the type checking is aimed at the Django ORM layer, where mistakes are otherwise easy to make.

For a library like this, the test suite is doing something specific. The whole model layer is a mirror of somebody else's schema, so the tests are what tell you the mapping is correct. A release history of 2.9.0 in January 2025, 2.10.0 in August 2025 and 2.11.0 in June 2026, with the last push on 2026-10-14, is a reasonable cadence for a project whose upstream dependency changes regularly.

Where dj-stripe is the wrong choice

The obvious case against is duplication. Once the data is copied locally, you own the consistency problem. A customer record in your database can disagree with the one at Stripe, and you need a rule for which one wins. Webhook delivery is at-least-once in practice, and the local copy needs to survive out-of-order and repeated events, which is work the library performs but work your application still has to reason about when it writes to Stripe and then reads from its own tables.

The second limit is the currency of the data. The local copy is as fresh as the last webhook, and any change made directly in the Stripe dashboard does not travel the other way. If your product lets people edit billing details in Stripe rather than in your app, the two views drift. The README does not describe a periodic resync or a reconciliation command, so a project that needs the local copy to be authoritative at all times is building something dj-stripe does not provide.

The third limit is the Stripe dependency itself. The library is bound to a Stripe SDK major version, currently 15.0.1 up to but not including 16, and the model layer has to be updated when Stripe changes its API. The README points at api_versions.md and a changes page for the version history, which is where you would look to see how much of the model set has moved with each Stripe release.

The fourth is the ecosystem boundary. dj-stripe is a Django application for Stripe. If part of your system is not Django, the local copy is only reachable from the Django side, and other services would still call Stripe directly.

Funding, licence and what a commercial user is signing up for

dj-stripe is MIT licensed, with the licence file at the top of the repository and the licence badge in the README. That is permissive and has no implications for a commercial deployment beyond attribution in the distribution.

The funding model is more interesting, because the README is explicit about it. The project has been bringing dj-stripe to the world for over 10 years, and it now says it can dedicate some real resources to the project. Sponsorship through GitHub Sponsors helps keep a team of maintainers working to keep dj-stripe up to date with the latest Stripe changes, and the README encourages commercial users to sign up for a paid plan. Corporate sponsors receive priority support and development time, with the details on a project support page.

The Stripe Verified Partner badge is worth noting too, since it indicates the project is recognised in Stripe's community library documentation. The README also carries a Stripe logo under a Funding and Support heading.

For a team building on dj-stripe, the practical reading is that the library is MIT and you can fork it, but the maintenance capacity is funded, and a company that depends on it commercially is being asked to contribute. The documentation site at dj-stripe.dev holds the installation instructions, the change log and the per-version notes.

Editorial conclusion

dj-stripe suits a Django product that needs to query customers, subscriptions and invoices with the ORM, or that has to keep working when the Stripe API is slow or unreachable, and it does not suit a project that treats Stripe as the single source of truth and wants no copy in the database. Before adopting it, read the installation documentation, because the README defers the setup steps entirely and the webhook and API key wiring is where projects usually go wrong. Verify first that the Stripe API version you use is covered by the tested version the project documents, since the README says it is tested with the latest Stripe API and points to an api_versions.md file for the details.

Frequently asked questions

Official sources

1. dj-stripe/dj-stripe on GitHub
2. License: MIT
3. Project website
4. README
5. Releases