dj-stripe 2.4.0 release notes (2020-11-19)
To upgrade to 2.4.0 from older versions of dj-stripe, scroll down to the Upgrade Guide.
Introducing sponsorships and our first sponsor
We're excited to introduce our Sponsorship tiers. Individuals may back dj-stripe to assist with development. Larger backers may choose one the paid support plans available to receive support on top of ensuring the long-term viability of the project!
And this release was made possible by none other than… Stripe! Our very first Gold sponsor. Their financial backing has allowed us to pour a lot of work that could not have otherwise happened.
- Support for Django 3.1 and Python 3.8.
- Minimum stripe-python version is now 2.48.0.
- Default Stripe API version is now
- First-class support for the Price model, replacing Plans.
- Support multi-item subscriptions.
- Support for API keys in the database (see Managing Stripe API keys).
- Support for syncing objects for multiple, different Stripe accounts.
- Use Django 3.1 native JSONField when available.
- The field
djstripe_owner_accounthas been added to all Stripe models, and is automatically populated with the Account that owns the API key used to retrieve it.
- Support for subscription schedules (#899).
- Add support for Reporting categories and TaxIds
- Update many models to match latest version of the Stripe API.
- Fixed Account.get_default_account() for Restricted API Keys.
- Allow passing arbitrary arguments (any valid SDK argument) to the following methods:
- New management command:
djstripe_update_invoiceitem_ids. This command migrates InvoiceItems using Stripe's old IDs to the new ones.
- Hundreds of other bugfixes.
New feature: in-database Stripe API keys
Stripe API keys are now stored in the database, and are now editable in the admin.
By default, all keys are visible by anyone who has access to the dj-stripe administration.
As we work on supporting multiple Stripe accounts per instance, it is vital for dj-stripe to have a mechanism to store more than one Stripe API key. It also became obvious that we may want proper programmatic access to create and delete keys. Furthermore, API keys are a legitimate upstream Stripe object, and it is not unlikely the API may allow access to listing other API keys in the future, in which case we will want to move them to the database anyway.
In the next release, we are planning to make WebhookEndpoints (and thus webhook secrets) manageable via the database as well.
Do I need to change anything?
Not at this time. The settings
still be used. Their values will however be automatically saved to the database at the
What about public keys?
STRIPE_TEST_PUBLIC_KEY will be deprecated next
release. You do not risk anything by leaving them in your settings: They are not used by
Dj-Stripe outside of the Dj-Stripe mixins, which are now themselves deprecated. So you
can safely leave them in your settings, or you can move them to the database as well
(Keys beginning in
pk_live_ will be detected as publishable keys).
Nobody likes features being removed. However, the last few releases we have had to remove features that were not core to what dj-stripe does, or simply poorly-maintained. To keep up with the trend, we are making three major deprecations this release:
Creating Plans from the Django Admin is no longer supported
Plan model was special cased in various places, including being the only one which
supported being created from the Django administration. This is no longer supported. We
have plans to allow creating arbitrary Stripe objects from the Django Admin, but until
it can be done consistently, we have decided to remove the feature for Plans (which are
deprecated by Stripe anyway). The only object type you should be dealing with from the
admin is the new APIKey model.
Along with this, we are also deprecating the
management command. You can instead use the
djstripe_sync_models management command,
which supports arbitrary models.
Deprecating the REST API
We are dropping all support for the REST API and will be fully removing it in 2.5.0. We're doing this because we wish to keep such an API separate from dj-stripe. Work has already started on a new project, and we will be sharing more details about it soon. If you're interested in helping out, please reach out on Github!
Large parts of dj-stripe, including this middleware, were designed before Stripe's major
revamps of the old Plan model into Prices, Products, and multi-plan subscriptions. The
functionality offered by the middleware is no longer adequate, and building on top of it
would not be particularly robust. We may bring similar functionality back in the future,
but the middleware as it is is going away (as well as the undocumented
djstripe.utils.subscriber_has_active_subscription utility function).
If you want to keep the functionality for your project, you may wish to copy the latest version of the middleware.
This is being deprecated for similar reasons as the SubscriptionPaymentMiddleware. However, the mixins module was undocumented and never officially supported.
Chargehas been renamed to
on_behalf_of, to be consistent with Stripe's upstream model. Note that this field is separate from
djstripe_owner_account, which is set by dj-stripe itself to match the account of the API key used.
Account.get_connected_account_from_token()is deprecated in favour of
Account.get_or_retrieve_for_api_key(), which supports more than just Connect accounts.
Customer.has_active_subscription()is deprecated in favour of
Customer.is_subscribed_to(). Note that the former takes a plan as argument, whereas the latter takes a product as argument.
Invoiceis no longer populated and will be removed in 2.5.0. You may want to use
Invoice.default_tax_ratesinstead, which uses the new TaxId functionality.
Customer.business_vat_idis being deprecated in favour of using TaxId models directly.
- Rename PlanBillingScheme to BillingScheme.
Plan.update_name()and these previously-deprecated fields:
Before you upgrade to dj-stripe 2.4.0, we recommend upgrading to dj-stripe 2.3.0. Upgrading one major release at a time minimizes the risk of issues arising.
Upgrading directly to 2.4.0 from dj-stripe versions older than 2.2.0 is unsupported.
To upgrade dj-stripe, run
pip install --upgrade dj-stripe==2.4.0.
Once installed, you can run
manage.py migrate djstripe to migrate the database models.
If you are doing multiple major dj-stripe upgrades in a row, remember to run the migrate command after every upgrade. Skipping this step WILL cause errors.
Migrating the database models may take a long time on databases with large amounts of customers.
A new mandatory setting
DJSTRIPE_FOREIGN_KEY_TO_FIELD has been added. If you are
upgrading from an older version, you need to set it to
Setting it to
"id" will make dj-stripe use the Stripe IDs as foreign keys. Although
this is recommended for new installations, there is currently no migration available for
For more information on this setting, see Settings.