dj-stripe 1.x release notes
This is a bugfix-only version:
- Allow billing_cycle_anchor argument when creating a subscription (#814)
- Fixup plan amount null with tier plans (#781)
- Update Cancel subscription view tests to match backport in f64af57
- Implement Invoice._manipulate_stripe_object_hook for compatability with API 2018-11-08 (#771)
- Fix product webhook for type="good" (#724)
- Add trial_from_plan, trial_period_days args to Customer.subscribe() (#709)
This is a bugfix-only version:
- Updated Subscription.cancel() for compatibility with Stripe 2018-08-23 (#723)
This is a bugfix-only version:
- Fixed an error with request.urlconf in some setups (#562)
- Always save text-type fields as empty strings in db instead of null (#713)
- Fix support for DJSTRIPE_SUBSCRIBER_MODEL_MIGRATION_DEPENDENCY (#707)
- Fix reactivate() with Stripe API 2018-02-28 and above
This is a bugfix-only version:
- Fixed various Python 2.7 compatibility issues
- Fixed issues with max_length of receipt_number
- Fixed various fields incorrectly marked as required
- Handle product webhook calls
- Fix compatibility with stripe-python 2.0.0
The dj-stripe 1.2.0 release resets all migrations.
Do not upgrade to 1.2.0 directly from 1.0.1 or below. You must upgrade to 1.1.0 first.
Please read the 1.1.0 release notes below for more information.
In dj-stripe 1.1.0, we made a lot of changes to models in order to bring the dj-stripe model state much closer to the upstream API objects. If you are a current user of dj-stripe, you will most likely have to make changes in order to upgrade. Please read the full changelog below. If you are having trouble upgrading, you may ask for help by filing an issue on GitHub.
The next version of dj-stripe, 1.2.0, will reset all the migrations
0001_initial. Migrations are currently in an unmaintainable state.
What this means is you will not be able to upgrade directly to dj-stripe 1.2.0. You must go through 1.1.0 first, run ``manage.py migrate djstripe``, then upgrade to 1.2.0.
Python 2.7 end-of-life
dj-stripe 1.1.0 drops support for Django 1.10 and adds support for Django 2.0. Django 1.11+ and Python 2.7+ or 3.4+ are required.
Support for Python versions older than 3.5, and Django versions older than 2.0, will be dropped in dj-stripe 2.0.0.
Backwards-incompatible changes and deprecations
Removal of polymorphic models
The model architecture of dj-stripe has been simplified. Polymorphic models have been dropped and the old base StripeCustomer, StripeCharge, StripeInvoice, etc models have all been merged into the top-level Customer, Charge, Invoice, etc models.
Importing those legacy models from
djstripe.stripe_objects will yield
the new ones. This is deprecated and support for this will be dropped in
Full support for Stripe Sources (Support for v3 stripe.js)
Stripe sources (
src_XXXX) are objects that can arbitrarily reference
any of the payment method types that Stripe supports. However, the
Card object (with object IDs like
not a Source object, and cannot be turned into a Source object at this
In order to support both Card and Source objects in ForeignKeys, a new
PaymentMethod has been devised (renamed to
DjstripePaymentMethod in 2.0). That model can resolve into a Card, a
Source, or a BankAccount object.
- The ``default_source`` attribute on ``Customer`` now
refers to a ``PaymentMethod`` object. You will need to call
.resolve()on it to get the Card or Source in question.
- References to
Customer.sourcesexpecting a queryset of Card objects should be updated to
- The legacy
StripeSourcename refers to the
Cardmodel. This will be removed in dj-stripe 2.0.0. Update your references to either
enums.SourceTypehas been renamed to
enums.SourceTypenow refers to the actual Stripe Source types enum.
Core fields renamed
- The numeric
idfield has been renamed to
djstripe_id. This avoids a clash with the upstream stripe id. Accessing
.idis deprecated and **will reference the upstream
stripe_idin dj-stripe 2.0.0
It's finally here! We've made significant changes to the codebase and are now compliant with stripe API version 2017-06-05.
I want to give a huge thanks to all of our contributors for their help in making this happen, especially Bill Huneke (@wahuneke) for his impressive design work and @jleclanche for really pushing this release along.
I also want to welcome onboard two more maintainers, @jleclanche and @lskillen. They've stepped up and have graciously dedicated their resources to making dj-stripe such an amazing package.
Almost all methods now mimic the parameters of those same methods in the stripe API. Note that some methods do not have some parameters implemented. This is intentional. That being said, expect all method signatures to be different than those in previous versions of dj-stripe.
Finally, please note that there is still a bit of work ahead of us. Not everything in the Stripe API is currently supported by dj-stripe -- we're working on it. That said, v1.0.0 has been thoroughly tested and is verified stable in production applications.
A few things to get excited for
- Multiple subscription support (finally)
- Multiple sources support (currently limited to Cards)
- Idempotency support (See #455, #460 for discussion -- big thanks to @jleclanche)
- Full model documentation
- Objects that come through webhooks are now tied to the API version set in dj-stripe. No more errors if dj-stripe falls behind the newest stripe API version.
- Any create/update action on an object automatically syncs the object.
- Concurrent LIVE and TEST mode support (Thanks to @jleclanche). Note
that you'll run into issues if
livemodeisn't set on your existing customer objects.
- All choices are now enum-based (Thanks @jleclanche, See #520).
Access them from the new
djstripe.enumsmodule. The ability to check against model property based choices will be deprecated in 1.1
- Support for the Coupon model, and coupons on Customer objects.
- Support for the Payout/Transfer
split from api
What still needs to be done (in v1.1.0)
Documentation. Our original documentation was not very helpful, but it covered the important bits. It will be very out of date after this update and will need to be rewritten. If you feel like helping, we could use all the help we can get to get this pushed out asap.
Master sync re-write. This sounds scary, but really isn't. The current management methods run sync methods on Customer that aren't very helpful and are due for removal. My plan is to write something that first updates local data (via
sync_from_stripe_data) and then pulls all objects from Stripe and populates the local database with any records that don't already exist there.
You might be wondering, "Why are they releasing this if there are only a few things left?" Well, that thinking turned this into a two year release... Trust me, this is a good thing.
Significant changes (mostly backwards-incompatible)
- Idempotency. #460 introduces idempotency keys and implements
Customer.get_or_create(). Idempotency will be enabled for all calls that need it.
- Improved Admin Interface. This is almost complete. See #451 and #452.
- Drop non-trivial endpoint views. We're dropping everything except the webhook endpoint and the subscription cancel endpoint. See #428.
- Drop support for sending receipts. Stripe now handles this for you. See #478.
- Drop support for plans as settings, including custom plan hierarchy (if you want this, write something custom) and the dynamic trial callback. We've decided to gut having plans as settings. Stripe should be your source of truth; create your plans there and sync them down manually. If you need to create plans locally for testing, etc., simply use the ORM to create Plan models. The sync rewrite will make this drop less annoying.
- Orphan Customer Sync. We will now sync Customer objects from Stripe even if they aren't linked to local subscriber objects. You can link up subscribers to those Customers manually.
- Concurrent Live and Test Mode. dj-stripe now supports test-mode and live-mode Customer objects concurrently. As a result, the User.customer One-to-One reverse-relationship is now the User.djstripe_customers RelatedManager. (Thanks @jleclanche) #440. You'll run into some dj-stripe check issues if you don't update your KEY settings accordingly. Check our GitHub issue tracker for help on this.
PAYMENT_PLANSobjects are removed. Use Plan.objects.all() instead.
plan_from_stripe_idfunction is removed. Use Plan.objects.get(stripe_id=)
- sync_plans no longer takes an api_key
- sync methods no longer take a
- All sync methods are now private. We're in the process of building a better syncing mechanism.
- dj-stripe decorators now take a plan argument. If you're passing in
a custom test function to
subscriber_passes_pay_test, be sure to account for this new argument.
- The context provided by dj-stripe's mixins has changed.
- We've removed the SubscriptionPaymentRequiredMixin. Use
- dj-stripe middleware doesn't support multiple subscriptions.
- Local custom signals are deprecated in favor of Stripe webhooks:
- The Event Handlers designed by @wahuneke are the new way to handle
events that come through webhooks. Definitely take a look at
SubscriptionCancellationFailureexceptions are removed. There should no longer be a case where they would have been useful. Catch native stripe errors in their place instead.
Charge.card_kindare removed. Use
Charge.source.brand(if the source is a Card)
Charge.invoiceis no longer a foreign key to the Invoice model.
Invoicenow has a OneToOne relationship with
Charge.invoicewill still work, but will no longer be represented in the database).
dj-stripe now supports test mode and live mode Customer objects concurrently (See #440). As a result, the
<subscriber_model>.customerOneToOne reverse relationship is no longer a thing. You should now instead add a
customerproperty to your subscriber model that checks whether you're in live or test mode (see djstripe.settings.STRIPE_LIVE_MODE as an example) and grabs the customer from
<subscriber_model>.djstripe_customerswith a simple
Customer no longer has a
current_subscriptionproperty. We've added a
subscriptionproperty that should suit your needs.
With the advent of multiple subscriptions, the behavior of
Customer.subscribe()has changed. Before,
calling subscribe()when a customer was already subscribed to a plan would switch the customer to the new plan with an option to prorate. Now calling
subscribe()simply subscribes that customer to a new plan in addition to it's current subsription. Use
Subscription.update()to change a subscription's plan instead.
Customer.cancel_subscription()is removed. Use
Customer.update_plan_quantity()method is removed. Use
SubscriptionManagerand works on the
Subscriptionmodel instead of the
Customer.update_card()now takes an id. If the id is not supplied, the default source is updated.
Customer.stripe_customerproperty is removed. Use
Customer.cancel_subscription()now actually follows the DJSTRIPE_PRORATION_POLICY setting.
Customer.card_exp_yearare all removed. Check
Customer.default_source(if it's a Card) or one of the sources in
Customer.sources(again, if it's a Card) instead.
Customer.add_invoice_itemis now named
invoiceand can be either an Invoice object or the stripe_id of an Invoice.
Event.validated_message. Just check if the event is valid
- no need to double check (we do that for you)
TransferChargeFeeis removed. It hasn't been used in a while due to a broken API version. Use
Any fields that were in
Transfer.summaryno longer exist and are therefore deprecated (unused but not removed from the database). Because of this,
TransferManagernow only aggregates
InvoiceItems are no longer created when Invoices are synced. You must now sync InvoiceItems directly.
Plan no longer has a
Plan.currencyno longer uses choices. Use the
get_supported_currency_choices()utility and create your own custom choices list instead.
Plan interval choices are now in
Subscription.is_period_current()now checks for a current trial end if the current period has ended. This change means subscriptions extended with
Subscription.extend()will now be seen as valid.
We'll sync your current records with Stripe in a migration. It will take a while, but it's the only way we can ensure data integrity. There were some fields for which we needed to temporarily add placeholder defaults, so just make sure you have a customer with ID 1 and a plan with ID 1 and you shouldn't run into any issues (create dummy values for these if need be and delete them after the migration).
BIG HUGE NOTE - DON'T OVERLOOK THIS
Subscription and InvoiceItem migration is not possible because old records don't have Stripe IDs (so we can't sync them). Our approach is to delete all local subscription and invoiceitem objects and re-sync them from Stripe.
We 100% recommend you create a backup of your database before performing this upgrade.
- Postgres users now have access to the
DJSTRIPE_USE_NATIVE_JSONFIELDsetting. (Thanks @jleclanche) #517, #523
- Charge receipts now take
DJSTRIPE_SEND_INVOICE_RECEIPT_EMAILSinto account (Thanks @r0fls)
- Clarified/modified installation documentation (Thanks @pydanny)
- Corrected and revised ANONYMOUS_USER_ERROR_MSG (Thanks @pydanny)
- Added fnmatching to
SubscriptionPaymentMiddleware.process_request()functionality broken up into multiple methods, making local customizations easier (Thanks @pydanny)
- Fully qualified events are now supported by event handlers as strings e.g. 'customer.subscription.deleted' (Thanks @lskillen) #316
- runtests now accepts positional arguments for declaring which tests to run (Thanks @lskillen) #317
- It is now possible to reprocess events in both code and the admin interface (Thanks @lskillen) #318
- The confirm page now checks that a valid card exists. (Thanks @scream4ik) #325
- Added support for viewing upcoming invoices (Thanks @lskillen) #320
- Event handler improvements and bugfixes (Thanks @lskillen) #321
- API list() method bugfixes (Thanks @lskillen) #322
- Added support for a custom webhook event handler (Thanks @lskillen) #323
- Django REST Framework contrib package improvements (Thanks @aleccool213) #334
tax_percentto CreateSubscriptionSerializer (Thanks @aleccool213) #349
- Fixed incorrectly assigned
application_feein Charge calls (Thanks @kronok) #382
- Fixed bug caused by API change (Thanks @jessamynsmith) #353
- Added inline documentation to pretty much everything and enforced docsytle via flake8 (Thanks @aleccool213)
- Fixed outdated method call in template (Thanks @kandoio) #391
- Customer is correctly purged when subscriber is deleted, regardless of how the deletion happened (Thanks @lskillen) #396
- Test webhooks are now properly captured and logged. No more bounced requests to Stripe! (Thanks @jameshiew) #408
- CancelSubscriptionView redirect is now more flexible (Thanks @jleclanche) #418
- Customer.sync_cards() (Thanks @jleclanche) #438
- Many stability fixes, bugfixes, and code cleanup (Thanks @jleclanche)
- Support syncing canceled subscriptions (Thanks @jleclanche) #443
- Improved admin interface (Thanks @jleclanche with @jameshiew) #451
- Support concurrent TEST + LIVE API keys (Fix webhook event processing for both modes) (Thanks @jleclanche) #461
- Added Stripe Dashboard link to admin change panel (Thanks @jleclanche) #465
Plan.amount_in_cents(Thanks @jleclanche) #466
Subscription.reactivate()(Thanks @jleclanche) #470
Plan.human_readable_price(Thanks @jleclanche) #498
- (Re)attach the Subscriber when we find it's id attached to a customer on Customer sync (Thanks @jleclanche) #500
- Made API version configurable (with dj-stripe recommended default) (Thanks @lskillen) #504