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.

Upgrade notes

Migration reset

The next version of dj-stripe, 1.2.0, will reset all the migrations to 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. Once on 1.2.0, you'll need to clear your migrations table of dj-stripe entries and then run manage.py migrate djstripe --fake

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 1.3.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 dj-stripe 1.3.0.

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 legacy Card object (with object IDs like card_XXXX or cc_XXXX) is not a Source object, and cannot be turned into a Source object at this time.
In order to support both Card and Source objects in ForeignKeys, a new model PaymentMethod has been devised. 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.sources expecting a queryset of Card objects should be updated to Customer.legacy_cards.
• The legacy StripeSource name refers to the Card model. This will be removed in dj-stripe 1.3.0. Update your references to either Card or Source.
• enums.SourceType has been renamed to enums.LegacySourceType. enums.SourceType now refers to the actual Stripe Source types enum.

Core fields renamed

• The numeric id field has been renamed to djstripe_id. This avoids a clash with the upstream stripe id. Accessing .id is deprecated and will reference the upstream stripe_id in dj-stripe 1.3.0 instead.
• The created field has been renamed djstripe_created.
• The modified field has been renamed djstripe_updated.
• The stripe_timestamp field has been renamed created, to match the upstream field name. stripe_timestamp is still usable, but will be removed in dj-stripe 1.3.0.

Changes to the Event model

The Event model previously hosted logic for both the stripe Event model, and whether the event had been processed from a webhook.

• Event.validate() has been moved to the new WebhookEventTrigger class, which now hosts all webhook-related logic
• Event.valid has been dropped.
• Event.processed has been dropped.
• Event.customer is no longer mutable, but instead calculated in a property.
• The signature for Event.process has changed.
• The EventProcessingException model has been dropped.
• Event.received_api_version has been renamed to Event.api_version.
• Event.webhook_message has been renamed to Event.data
• The exists_by_json() manager method has been dropped.
• views.WebHook has been renamed to views.ProcessWebhookView
• Webhook triggers that do not validate now return HTTP 400.
• If an error happens during webhook processing, an HTTP 500 will be returned.

Deprecation of djstripe.contrib.rest_framework

The django-rest-framework integration is not used by any of the dj-stripe maintainers and has become unmaintained. We are deprecating it and will most likely be removing it in dj-stripe 1.3.0.
If you are interested in maintaining it, please let us know by filing an issue so that it can be moved to its own library.

New and updated models

The following models have been added:

• BankAccount
• Dispute (Note: charge.disputed is now a property instead of a field)
• FileUpload
• Product
• Refund

The following models have been updated to (mostly) match the Stripe upstream models:

• Account
• Invoice
• Plan

New features

• Customer.add_coupon() now supports the idempotency_key argument.
• New management command: manage.py sync_plans_from_stripe syncs the plans on Stripe to dj-stripe.
• New setting: STRIPE_API_HOST. You may set it to an URL of your choice to change the Stripe API server the Stripe library talks to. This is only for local development purposes if you use something such as stripe-mock and will raise a check warning when DEBUG=False.

Minor changes

• dj-stripe now sets the Stripe app info. This means you can see your dj-stripe version in the Stripe request log dashboard.
• Added support for restricted API keys
• Card.country is now nullable. Some cards may not have a country set.
• utils.get_friendly_currency_amount() now always shows two decimals (eg. $10.00 USD).
• dj-stripe no longer attempts to handle charge.dispute.* events. This will return once it works.
• The new Customer.credits and Customer.pending_charges properties parse the multi-purpose account_balance field to return credits and pending charges, respectively.
• Transfer fields deprecated from pre-1.0 have been dropped.
• Deprecated Subscription.STATUS_* fields have been dropped.
• Deprecated Transfer.STATUS_* fields have been dropped.

We're pushing out a quick cherry-pick bugfix release to fix some blocking issues for new installations:

• COMPATIBILITY: Drop support for Django 1.10
• COMPATIBILITY: Add support for Django 2.0
• Various migration fixes
• Fix python 2.7 encoding issues
• Allow restricted key (rk_*) in checks
• Use ugettext_lazy instead of ugettext in enums (#581)
• Set Stripe app_info metadata on API calls
• Do not attempt to handle charge.dispute events

Huge thanks to @jleclanche for sparing the time to get this out there.

1.0.0 (2017-08-12)

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 Jerome Leclanche (@jleclanche) for really pushing this release along.

I also want to welcome onboard two more maintainers, Jerome Leclanche (@jleclanche) and Lee Skillen (@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.

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.

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 livemode isn't set on your existing customer objects.
• All choices are now enum-based (Thanks @jleclanche, See #520). Access them from the new djstripe.enums module. 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 version 2017-04-06.

What still needs to be done (in v1.3.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 api_retrieve and 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 idempotency for 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.

SETTINGS

• The PLAN_CHOICES, PLAN_LIST, and PAYMENT_PLANS objects are removed. Use Plan.objects.all() instead.
• The plan_from_stripe_id function is removed. Use Plan.objects.get(stripe_id=)

SYNCING

• sync_plans no longer takes an api_key
• sync methods no longer take a cu parameter
• All sync methods are now private. We're in the process of building a better syncing mechanism.

UTILITIES

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

MIXINS

• The context provided by dj-stripe's mixins has changed. PaymentsContextMixin now provides STRIPE_PUBLIC_KEY and plans (changed to Plan.objects.all()). SubscriptionMixin now provides customer and is_plans_plural.
• We've removed the SubscriptionPaymentRequiredMixin. Use @method_decorator("dispatch",subscription_payment_required) instead.

MIDDLEWARE

• dj-stripe middleware doesn't support multiple subscriptions.

SIGNALS

• Local custom signals are deprecated in favor of Stripe webhooks:
• cancelled -> WEBHOOK_SIGNALS["customer.subscription.deleted"]
• card_changed -> WEBHOOK_SIGNALS["customer.source.updated"]
• subscription_made -> WEBHOOK_SIGNALS["customer.subscription.created"]

WEBHOOK EVENTS

• The Event Handlers designed by @wahuneke are the new way to handle events that come through webhooks. Definitely take a look at event_handlers.py and webhooks.py.

EXCEPTIONS

• SubscriptionUpdateFailure and SubscriptionCancellationFailure exceptions are removed. There should no longer be a case where they would have been useful. Catch native stripe errors in their place instead.

MODELS

CHARGE

• Charge.charge_created -> Charge.stripe_timestamp
• Charge.card_last_4 and Charge.card_kind are removed. Use Charge.source.last4 and Charge.source.brand (if the source is a Card)
• Charge.invoice is no longer a foreign key to the Invoice model. Invoice now has a OneToOne relationship with Charge. (Charge.invoice will still work, but will no longer be represented in the database).

CUSTOMER

• dj-stripe now supports test mode and live mode Customer objects concurrently (See #440). As a result, the <subscriber_model>.customer OneToOne reverse relationship is no longer a thing. You should now instead add a customer property 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_customers with a simple livemode= filter.
• Customer no longer has a current_subscription property. We've added a subscription property 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 Subscription.cancel() instead.
• The Customer.update_plan_quantity() method is removed. Use Subscription.update() instead.
• CustomerManager is now SubscriptionManager and works on the Subscription model instead of the Customer model.
• Customer.has_valid_card() is now Customer.has_valid_source().
• Customer.update_card() now takes an id. If the id is not supplied, the default source is updated.
• Customer.stripe_customer property is removed. Use Customer.api_retrieve() instead.
• The at_period_end parameter of Customer.cancel_subscription() now actually follows the DJSTRIPE_PRORATION_POLICY setting.
• Customer.card_fingerprint, Customer.card_last_4, Customer.card_kind, Customer.card_exp_month, Customer.card_exp_year are 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.
• The invoice_id parameter of Customer.add_invoice_item is now named invoice and can be either an Invoice object or the stripe_id of an Invoice.

EVENT

• Event.kind -> Event.type
• Removed Event.validated_message. Just check if the event is valid
  • no need to double check (we do that for you)

TRANSFER

• Removed Transfer.update_status()
• Removed Transfer.event
• TransferChargeFee is removed. It hasn't been used in a while due to a broken API version. Use Transfer.fee_details instead.
• Any fields that were in Transfer.summary no longer exist and are therefore deprecated (unused but not removed from the database). Because of this, TransferManager now only aggregates total_sum

INVOICE

• Invoice.attempts -> Invoice.attempt_count
• InvoiceItems are no longer created when Invoices are synced. You must now sync InvoiceItems directly.

INVOICEITEM

• Removed InvoiceItem.line_type

PLAN

• Plan no longer has a stripe_plan property. Use api_retrieve() instead.
• Plan.currency no longer uses choices. Use the get_supported_currency_choices() utility and create your own custom choices list instead.
• Plan interval choices are now in Plan.INTERVAL_TYPE_CHOICES

SUBSCRIPTION

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

MIGRATIONS

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

Other changes

• Postgres users now have access to the DJSTRIPE_USE_NATIVE_JSONFIELD setting. (Thanks @jleclanche) #517, #523
• Charge receipts now take DJSTRIPE_SEND_INVOICE_RECEIPT_EMAILS into account (Thanks @r0fls)
• Clarified/modified installation documentation (Thanks @pydanny)
• Corrected and revised ANONYMOUS_USER_ERROR_MSG (Thanks @pydanny)
• Added fnmatching to SubscriptionPaymentMiddleware (Thanks @pydanny)
• 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
• Added tax_percent to CreateSubscriptionSerializer (Thanks @aleccool213) #349
• Fixed incorrectly assigned application_fee in 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 cancelled 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
• Implemented Plan.amount_in_cents (Thanks @jleclanche) #466
• Implemented Subscription.reactivate() (Thanks @jleclanche) #470
• Added 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

Best way to install: pip install dj-stripe

• better plan ordering documentation (Thanks @cjrh)
• added a confirmation page when choosing a subscription (Thanks @chrissmejia, @areski)
• setup.py reverse dependency fix (#258/#268) (Thanks @ticosax)
• Dropped official support for Django 1.7 (no code changes were made)
• Python 3.5 support, Django 1.9.1 support
• Migration improvements (Thanks @michi88)
• Fixed "Invoice matching query does not exist" bug (#263) (Thanks @mthornhill)
• Fixed duplicate content in account view (Thanks @areski)

Best way to install: pip install dj-stripe

• dj-stripe now responds to the invoice.created event (Thanks @wahuneke)
• dj-stripe now cancels subscriptions and purges customers during sync if they were deleted from the stripe dashboard (Thanks @unformatt)
• dj-stripe now checks for an active stripe subscription in the update_plan_quantity call (Thanks @ctrengove)
• Event processing is now handled by "event handlers" - functions outside of models that respond to various event types and subtypes. Documentation on how to tie into the event handler system coming soon. (Thanks @wahuneke)
• Experimental Python 3.5 support
• Support for Django 1.6 and lower is now officially gone.
• Much, much more!

Best way to install: pip install dj-stripe

• Support for Django 1.6 and lower is now deprecated. Please upgrade to Django 1.8!
• Improved test harness now tests coverage and pep8
• SubscribeFormView and ChangePlanView no longer populate self.error with form errors
• InvoiceItems.plan can now be null (as it is with individual charges), resolving #140 (Thanks @awechsler and @MichelleGlauser for help troubleshooting)
• Email templates are now packaged during distribution.
• sync_plans now takes an optional api_key
• 100% test coverage
• Stripe ID is now returned as part of each model's str method (Thanks @areski)
• Customer model now stores card expiration month and year (Thanks @jpadilla)
• Ability to extend subscriptions (Thanks @benmurden)
• Support for plan heirarchies (Thanks @chrissmejia)
• Rest API endpoints for Subscriptions [contrib](Thanks @philippeluickx)
• Admin interface search by email functionality is removed (#221) (Thanks @jpadilla)

• Began deprecation of support for Django 1.6 and lower.
• Added formal support for Django 1.8.
• Removed the StripeSubscriptionSignupForm
• Removed djstripe.safe_settings. Settings are now all located in djstripe.settings
• DJSTRIPE_TRIAL_PERIOD_FOR_SUBSCRIBER_CALLBACK can no longer be a module string
• The sync_subscriber argument has been renamed from subscriber_model to subscriber
• Moved available currencies to the DJSTRIPE_CURRENCIES setting (Thanks @martinhill)
• Allow passing of extra parameters to stripe Charge API (Thanks @mthornhill)
• Support for all available arguments when syncing plans (Thanks @jamesbrobb)
• charge.refund() now returns the refunded charge object (Thanks @mthornhill)
• Charge model now has captured field and a capture method (Thanks @mthornhill)
• Subscription deleted webhook bugfix
• South migrations are now up to date (Thanks @Tyrdall)

• Formal Python 3.3+/Django 1.7 Support (including migrations)
• Removed Python 2.6 from Travis CI build. (Thanks @audreyr)
• Dropped Django 1.4 support. (Thanks @audreyr)
• Deprecated the djstripe.forms.StripeSubscriptionSignupForm. Making this form work easily with both dj-stripe *and django-allauth required too much abstraction. It will be removed in the 0.5.0 release.
• Add the ability to add invoice items for a customer (Thanks @kavdev)
• Add the ability to use a custom customer model (Thanks @kavdev)
• Added setting to disable Invoice receipt emails (Thanks Chris Halpert)
• Enable proration when customer upgrades plan, and pass proration policy and cancellation at period end for upgrades in settings. (Thanks Yasmine Charif)
• Removed the redundant context processor. (Thanks @kavdev)
• Fixed create a token call in change_card.html (Thanks @dollydagr)
• Fix charge.dispute.closed typo. (Thanks @ipmb)
• Fix contributing docs formatting. (Thanks @audreyr)
• Fix subscription cancelled_at_period_end field sync on plan upgrade (Thanks @nigma)
• Remove "account" bug in Middleware (Thanks @sromero84)
• Fix correct plan selection on subscription in subscribe_form template. (Thanks Yasmine Charif)
• Fix subscription status in account, _subscription_status, and cancel_subscription templates. (Thanks Yasmine Charif)
• Now using user.get_username() instead of user.username, to support custom User models. (Thanks @shvechikov)
• Update remaining DOM Ids for Bootstrap 3. (Thanks Yasmine Charif)
• Update publish command in setup.py. (Thanks @pydanny)
• Explicitly specify tox's virtual environment names. (Thanks @audreyr)
• Manually call django.setup() to populate apps registry. (Thanks @audreyr)

• Fully tested against Django 1.6, 1.5, and 1.4
• Fix boolean default issue in models (from now on they are all default to False).
• Replace duplicated code with djstripe.utils.user_has_active_subscription.