Skip to content

dj-stripe 2.4.0 release notes (2020-11-19)

Attention

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.

Release notes

  • Support for Django 3.1 and Python 3.8.
  • Minimum stripe-python version is now 2.48.0.
  • Default Stripe API version is now 2020-08-27.
  • 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_account has 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:
    • Customer.charge()
    • Customer.subscribe(),
    • Charge.capture()
    • Subscription.update()
  • 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.

Warning

By default, all keys are visible by anyone who has access to the dj-stripe administration.

Why?

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 STRIPE_LIVE_SECRET_KEY and STRIPE_TEST_SECRET_KEY can still be used. Their values will however be automatically saved to the database at the earliest opportunity.

What about public keys?

Setting STRIPE_LIVE_PUBLIC_KEY and 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_test_ and pk_live_ will be detected as publishable keys).

Deprecated features

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

The 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 djstripe_sync_plans_from_stripe 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!

Deprecating djstripe.middleware.SubscriptionPaymentMiddleware

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.

Deprecating djstripe.mixins

This is being deprecated for similar reasons as the SubscriptionPaymentMiddleware. However, the mixins module was undocumented and never officially supported.

Other deprecations

  • The account field on Charge has 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.
  • The tax_percent attribute of Invoice is no longer populated and will be removed in 2.5.0. You may want to use Invoice.default_tax_rates instead, which uses the new TaxId functionality.
  • Customer.business_vat_id is being deprecated in favour of using TaxId models directly.

Breaking changes

  • Rename PlanBillingScheme to BillingScheme.

  • Remove Plan.update_name() and these previously-deprecated fields:

    • Customer.business_vat_id
    • Subscription.start
    • Subscription.billing

Upgrade Guide

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.

Attention

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.

Note

Migrating the database models may take a long time on databases with large amounts of customers.

Settings changes

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 "djstripe_id".

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 going from "djstripe_id" to "id".

For more information on this setting, see Settings.