Release 2.4.0: preparation

[jleclanche]

I'm starting the prep work for the next release. I'd like to have it some time in November (I wanted to do this in October but life got in the way).

Highlight features of this release:

• Support for API keys in the database
• Support for multiple Stripe accounts.
• First-class support for the Price model, replacing Plans
• First-class support for multi-item subscriptions
• Django 3.1 support (and its own native JSONField)

Right now, what's missing is #1263, and full documentation for the price stuff, including documented deprecations for anything where we transition from plan to price as the preferred method.

#958 is in the milestone and I think I want to keep it in there if possible, but I won't want to block the release on it entirely.

Release checklist:

• Ensure all features in the 2.4.0 milestone are ready for release and tested to work.
• Squash master migrations.
• Enlist a couple of people willing to migrate a copy of their production environment to the final migration file. (If you're willing to help and volunteer for this, please make yourself known here!)
• Document all deprecations in the release notes
  • REST API deprecation
  • Deprecation of PaymentsContextMixin and SubscriptionMixin
• Document all breaking changes in the release notes
• Document all important new settings in the documentation
  • DJSTRIPE_FOREIGN_KEY_TO_FIELD (see below)
  • DJSTRIPE_USE_NATIVE_JSONFIELD
• Write a special thank-you note to @stripe for their funding and about the new sponsorship program

[jleclanche]

Introducing in-database Stripe API keys

Stripe API keys are now stored in the database, and are now editable in the admin.

Important note: By default, 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.

Adding new API keys

You may add new API keys via the Dj-Stripe "API key" administration. The only required value is the key's "secret" value itself. Example:

Once saved, Dj-Stripe will automatically detect whether the key is a public, restricted or secret key, and whether it's for live or test mode. If it's a secret key, the matching Account object will automatically be fetched as well and the key will be associated with it, so that it can be used to communicate with the Stripe API when dealing with objects belonging to that Account.

Updating the API keys

When expiring or rolling new secret keys, you should create the new API key in Stripe, then add it from the Django administration. Whenever you are ready, you may delete the old key. (It is safe to keep it around, as long as it hasn't expired. Keeping expired keys in the database may result in errors during usage).

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).

[jleclanche]

Major deprecations

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: https://github.com/dj-stripe/

(TODO ^ update link to contrib api project)

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.

[kavdev]

@jleclanche here are a couple more things if you want them in there. You've covered everything else 👍

New Features

• Revamped the documentation

Improvements

• Updated signals to include new stripe webhook event types

Bugfixes

• Fixed Account creation error when Account.payouts_enabled is missing from request [Creating account fails when request to api.stripe.com/v1/account is missing payouts_enabled #1107]
• As of API version 2020-03-02, there is no permission that can allow restricted keys to call GET /v1/account, so Account.get_default_account no longer attempts to pull data using a restricted key. [Patch Account.get_default_account for restricted API keys. #1131]

[jleclanche]

dj-stripe 2.4.0 is out!

Release notes: https://dj-stripe.readthedocs.io/en/stable-2.4/history/2_4_0/
Github release: https://github.com/dj-stripe/dj-stripe/releases/tag/2.4.0

Thanks to everyone who helped with it!