dj-stripe 2.10.0 (2025-08-11)

IMPORTANT: Migrations have been reset. You MUST upgrade to dj-stripe 2.9.x before upgrading to dj-stripe 2.10.x.

This release of dj-stripe continues the philosophy of becoming a more generalized layer over the Stripe SDK.

In this version, we are removing many more database fields from the dj-stripe models, replacing them by property accessors to stripe_data instead (or dropping support for them altogether).

Why we are doing this: Supporting the Stripe data models manually has become impossible due to the pace at which they are implementing new fields, changing old ones, or adding new mechanisms. We are therefore planning to improve a tighter integration with the Stripe SDK, and we are currently working on designing a more better model that allows for storing and accessing Stripe objects in the database in a convenient, scalable way.

This release is meant to be a compatibility step towards that end goal. We previously tried to work on a large 3.0 breaking change, but we now believe this to be too much of a hassle for developers to deal with; we will therefore be stepping into it gradually, which unfortunately means more breaking changes every release.

Where reasonable, we have added @property style accessors to the models. Which means that most changes should be backwards-compatible if you are only directly accessing the attributes on the models. What changes is how to filter the models, as the columns no longer exist. The stripe_data field that was added to all Stripe models continuously stores the full Stripe model as it was last seen. This is a JSONField, and on our supported database backends, it is possible to filter directly into it. For example, where you might have done Refund.objects.filter(receipt_number="XYZ"), you may replace that with: Refund.objects.filter(stripe_data__receipt_number="XYZ").

We endeavour to keep the most important columns in each model. The ones that are dropped are those that were part of our previous goal of having a 1:1 column mapping of Stripe models, which is clearly no longer a reasonable goal.

Version support

Support for Python versions older than 3.11 has been dropped.
Support for Django versions older than 5.0 has been dropped.
Migrations have been fully reset. You MUST upgrade to dj-stripe 2.9.x before upgrading to dj-stripe 2.10.x.

Breaking Changes

Customer.subscribe() no longer takes its deprecated plan argument; use price.
Disputes no longer actively sync their linked files.

The following deprecated models have been removed:

UsageRecord
UsageRecordSummary

The following fields have been removed:

Account: All fields have been removed (no foreign keys in this model)
BalanceTransaction: available_on, exchange_rate, fee, fee_details, net, reporting_category, status
BankAccount: All fields except account, customer, and fingerprint
Card: All fields except account, customer, and fingerprint
Charge: calculated_statement_descriptor, failure_code, failure_message, fraud_details, source_transfer
Coupon: applies_to, amount_off, currency, duration, duration_in_months, max_redemptions, name, percent_off, redeem_by, times_redeemed
Customer: coupon_end, coupon_start, legacy_cards, currency, default_source, deleted, coupon, name, entitlements
Invoice: application_fee_amount, auto_advance, account_country, account_name, amount_paid, amount_remaining, attempted, collection_method, customer_address, customer_email, customer_name, customer_phone, customer_shipping, customer_tax_exempt, default_source, discount, discounts, ending_balance, plan, post_payment_credit_notes_amount, pre_payment_credit_notes_amount, starting_balance, status_transitions, subscription_proration_date, threshold_reason
Mandate: customer_acceptance, payment_method_details, status, type, multi_use, single_use
PaymentMethod: All payment method fields have been removed.
PaymentIntent: All non-foreignkey fields have been removed
Product: attributes, caption, deactivate_on, images, package_dimensions, shippable, statement_descriptor, url, unit_label
Session: All fields except foreign keys (customer, payment_intent, setup_intent, subscription)
SetupIntent: All non-foreignkey fields have been removed
Source: All fields except customer

The following fields have been replaced by property accessors:

All Stripe models: description
Account: All fields (business_profile, business_type, charges_enabled, country, company, default_currency, details_submitted, email, individual, payouts_enabled, product_description, requirements, settings, type, tos_acceptance)
ApplicationFee: amount, amount_refunded, currency, refunded
ApplicationFeeRefund: amount, currency
BalanceTransaction: available_on, exchange_rate, fee, fee_details, net, reporting_category, status
BankAccount: account_holder_name, account_holder_type, bank_name, country, currency, default_for_currency, last4, routing_number, status
BaseInvoice: currency, due_date, number, period_end, period_start, receipt_number, status, subtotal, tax, tax_percent, total
Card: address_city, address_country, address_line1, address_line1_check, address_line2, address_state, address_zip, address_zip_check, brand, country, cvc_check, default_for_currency, dynamic_last4, exp_month, exp_year, funding, last4, name, tokenization_method
Charge: amount_captured, amount_refunded, application, application_fee, application_fee_amount, billing_details, captured, dispute, disputed, on_behalf_of, outcome, paid, payment_method_details, receipt_email, receipt_number, receipt_url, refunded, shipping, statement_descriptor, statement_descriptor_suffix, transfer, transfer_data, transfer_group
Coupon: applies_to, amount_off, currency, duration, duration_in_months, max_redemptions, name, percent_off, redeem_by, times_redeemed
Customer: currency, default_source, deleted, coupon, name, entitlements, discount
Discount: invoice_item
Dispute: amount, balance_transactions, currency, evidence, evidence_details, is_charge_refundable,, reason, status
File: filename, purpose, size, type, url
FileLink: expires_at, url
Invoice: amount_due, attempt_count, billing_reason, footer, invoice_pdf, hosted_invoice_url, paid, statement_descriptor, webhooks_delivered_at
InvoiceItem: amount, currency, date, discountable, discounts, period, period_end, period_start, proration, quantity, unit_amount, unit_amount_decimal
LineItem: amount, amount_excluding_tax, currency, discount_amounts, discountable, discounts, period, period_end, period_start, price, proration, proration_details, tax_amounts, tax_rates, type, unit_amount_excluding_tax, quantity
Mandate: customer_acceptance, payment_method_details, status, type, multi_use, single_use
PaymentMethod: billing_details, type
Payout: amount, arrival_date, automatic, failure_code, failure_message, method, source_type, statement_descriptor, status, type
Plan: active, aggregate_usage, amount, amount_decimal, billing_scheme, currency, interval, interval_count, nickname, product, tiers, tiers_mode, transform_usage, trial_period_days, usage_type
Price: billing_scheme, recurring, tiers, tiers_mode, transform_quantity, type, unit_amount, unit_amount_decimal
Product: default_price, type, url, unit_label
Refund: failure, reason, receipt_number, status
Session: amount_total, amount_subtotal, billing_address_collection, cancel_url, client_reference_id, currency, customer_email, display_items, line_items, locale, mode, payment_method_types, payment_status, shipping_address_collection, shipping_cost, shipping_details, shipping_options, status, submit_type, success_url, total_details, url
ShippingRate: active, display_name, fixed_amount, type, delivery_estimate, tax_behavior
Source: amount, client_secret, currency, flow, owner, statement_descriptor, status, type, usage, code_verification, receiver, redirect, source_data
Subscription: application_fee_percent, automatic_tax, billing_cycle_anchor, billing_thresholds, cancel_at, cancel_at_period_end, canceled_at, collection_method, current_period_end, current_period_start, days_until_due, default_payment_method, default_source, default_tax_rates, discount, ended_at, items, latest_invoice, next_pending_invoice_item_invoice, pause_collection, payment_settings, pending_invoice_item_interval, pending_setup_intent, pending_update, plan, quantity, schedule, start_date, status, test_clock, transfer_data, trial_end, trial_start
SubscriptionItem: billing_thresholds, proration_behavior, proration_date, quantity
TaxCode: name
TaxId: country, type, value
TaxRate: active, country, display_name, inclusive, jurisdiction, percentage, state, tax_type
Transfer: amount, amount_reversed, currency, destination, destination_payment, reversed, source_transaction, source_type, transfer_group
TransferReversal: amount, currency

Deprecations

InvoiceOrLineItemForeignKey is deprecated and will be removed next release.

New features

New management command: stripe_listen. This command creates a temporary webhook endpoint and runs the stripe CLI stripe listen command to forward incoming webhooks to it, allowing developers to listen to events on local instances. The Stripe CLI must be installed to run this command.
New model: PricingTable. This is a model which implements the pricing table object that is only available through private Stripe APIs.
Add support for Customer entitlements via the Customer.entitlements list.

Bugfixes