djstripe.models.billing
BaseInvoice
Bases: StripeModel
The abstract base model shared by Invoice and UpcomingInvoice
Note: Most fields are defined on BaseInvoice so they're available to both models. ManyToManyFields are an exception, since UpcomingInvoice doesn't exist in the db.
amount_due
property amount_due: int
attempt_count
property attempt_count: int
billing_reason
property billing_reason: str
charge
attribute charge
currency
property currency
customer
attribute customer
default_payment_method
attribute default_payment_method
discounts
property discounts
The discounts applied to the invoice.
due_date
property due_date
expand_fields
attribute expand_fields
footer
property footer: str
hosted_invoice_url
property hosted_invoice_url: str
invoice_pdf
property invoice_pdf: str
number
property number
paid
property paid: bool
payment_intent
attribute payment_intent
period_end
property period_end
period_start
property period_start
receipt_number
property receipt_number
status
property status
stripe_class
attribute stripe_class
stripe_dashboard_item_name
attribute stripe_dashboard_item_name
subscription
attribute subscription
subtotal
property subtotal
tax
property tax
tax_percent
property tax_percent
total
property total
webhooks_delivered_at
property webhooks_delivered_at: int | None
The date and time the invoice was last attempted to be paid. This is the time when the last webhook was successfully sent.
retry
retry(self, **kwargs)
Retry payment on this invoice if it isn't paid.
upcoming
upcoming(cls, api_key = djstripe_settings.STRIPE_SECRET_KEY, customer = None, subscription = None, **kwargs) -> Optional[UpcomingInvoice]
Gets the upcoming preview invoice (singular) for a customer.
At any time, you can preview the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discount that is applicable to the customer. (Source: https://stripe.com/docs/api#upcoming_invoice)
.. important:: Note that when you are viewing an upcoming invoice, you are simply viewing a preview.
:param customer: The identifier of the customer whose upcoming invoice you'd like to retrieve. :type customer: Customer or string (customer ID) :param coupon: The code of the coupon to apply. :type coupon: str :param subscription: The identifier of the subscription to retrieve an invoice for. :type subscription: Subscription or string (subscription ID)
Coupon
Bases: StripeModel
A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons may be applied to invoices or orders. Coupons do not work with conventional one-off charges.
Stripe documentation: https://stripe.com/docs/api/coupons?lang=python
amount_off
property amount_off
applies_to
property applies_to
currency
property currency
duration
property duration
duration_in_months
property duration_in_months
expand_fields
attribute expand_fields
human_readable
property human_readable
human_readable_amount
property human_readable_amount
id
attribute id
max_redemptions
property max_redemptions
name
property name
percent_off
property percent_off
redeem_by
property redeem_by
stripe_class
attribute stripe_class
stripe_dashboard_item_name
attribute stripe_dashboard_item_name
times_redeemed
property times_redeemed
Discount
Bases: StripeModel
A discount represents the actual application of a coupon or promotion code. It contains information about when the discount began, when it will end, and what it is applied to.
Stripe documentation: https://stripe.com/docs/api/discounts
customer
attribute customer
expand_fields
attribute expand_fields
invoice
attribute invoice
promotion_code
attribute promotion_code
stripe_class
attribute stripe_class
subscription
attribute subscription
is_valid_object
is_valid_object(cls, data)
Returns whether the data is a valid object for the class
Invoice
Bases: BaseInvoice
Invoices are statements of what a customer owes for a particular billing period, including subscriptions, invoice items, and any automatic proration adjustments if necessary.
Once an invoice is created, payment is automatically attempted. Note that the payment, while automatic, does not happen exactly at the time of invoice creation. If you have configured webhooks, the invoice will wait until one hour after the last webhook is successfully sent (or the last webhook times out after failing).
Any customer credit on the account is applied before determining how much is due for that invoice (the amount that will be actually charged). If the amount due for the invoice is less than 50 cents (the minimum for a charge), we add the amount to the customer's running account balance to be added to the next invoice. If this amount is negative, it will act as a credit to offset the next invoice. Note that the customer account balance does not include unpaid invoices; it only includes balances that need to be taken into account when calculating the amount due for the next invoice.
Stripe documentation: https://stripe.com/docs/api?lang=python#invoices
default_tax_rates
attribute default_tax_rates: models.ManyToManyField[TaxRate, Any]
InvoiceItem
Bases: StripeModel
Sometimes you want to add a charge or credit to a customer but only actually charge the customer's card at the end of a regular billing cycle. This is useful for combining several charges to minimize per-transaction fees or having Stripe tabulate your usage-based billing totals.
Stripe documentation: https://stripe.com/docs/api?lang=python#invoiceitems
amount
property amount
Amount invoiced (as decimal).
currency
property currency
Currency code.
customer
attribute customer
date
property date
The date on the invoiceitem.
discountable
property discountable
If True, discounts will apply to this invoice item. Always False for prorations.
discounts
property discounts
The discounts which apply to the invoice item. Item discounts are applied before invoice discounts.
expand_fields
attribute expand_fields
invoice
attribute invoice
period
property period
Period information.
period_end
property period_end
Might be the date when this invoiceitem's invoice was sent.
period_start
property period_start
Might be the date when this invoiceitem was added to the invoice.
price
attribute price
proration
property proration
Whether or not the invoice item was created automatically as a proration adjustment when the customer switched plans.
quantity
property quantity
If the invoice item is a proration, the quantity of the subscription for which the proration was computed.
stripe_class
attribute stripe_class
subscription
attribute subscription
tax_rates
attribute tax_rates: models.ManyToManyField[TaxRate, Any]
unit_amount
property unit_amount
Unit amount (in the currency specified) of the invoice item.
unit_amount_decimal
property unit_amount_decimal
Same as unit_amount, but contains a decimal value with at most 12 decimal places.
api_retrieve
api_retrieve(self, *args, **kwargs)
get_stripe_dashboard_url
get_stripe_dashboard_url(self)
LineItem
Bases: StripeModel
The individual line items that make up the invoice.
Stripe documentation: https://stripe.com/docs/api/invoices/line_item
amount
property amount
The amount, in cents.
amount_excluding_tax
property amount_excluding_tax
The integer amount in cents representing the amount for this line item, excluding all tax and discounts.
currency
property currency
Currency code.
discount_amounts
property discount_amounts
The amount of discount calculated per discount for this line item.
discountable
property discountable
If True, discounts will apply to this line item. Always False for prorations.
discounts
property discounts
The discounts applied to the invoice line item. Line item discounts are applied before invoice discounts.
expand_fields
attribute expand_fields
invoice_item
attribute invoice_item
period
property period
The period this line_item covers.
period_end
property period_end
The end of the period, which must be greater than or equal to the start.
period_start
property period_start
The start of the period.
price
property price
The price of the line item.
proration
property proration
Whether or not the invoice item was created automatically as a proration adjustment when the customer switched plans.
proration_details
property proration_details
Additional details for proration line items.
quantity
property quantity
The quantity of the subscription, if the line item is a subscription or a proration.
stripe_class
attribute stripe_class
subscription
attribute subscription
subscription_item
attribute subscription_item
tax_amounts
property tax_amounts
The amount of tax calculated per tax rate for this line item.
tax_rates
property tax_rates
The tax rates which apply to the line item.
type
property type
Type of line item.
unit_amount_excluding_tax
property unit_amount_excluding_tax
The amount in cents representing the unit amount for this line item, excluding all tax and discounts.
api_list
api_list(cls, api_key = djstripe_settings.STRIPE_SECRET_KEY, **kwargs)
Call the stripe API's list operation for this model. Note that we only iterate and sync the LineItem associated with the passed in Invoice.
Upcoming invoices are virtual and are not saved and hence their line items are also not retrieved and synced
:param api_key: The api key to use for this request. Defaults to djstripe_settings.STRIPE_SECRET_KEY. :type api_key: string
See Stripe documentation for accepted kwargs for each object.
:returns: an iterator over all items in the query
PromotionCode
Bases: StripeModel
This is an object representing a Promotion Code.
A Promotion Code represents a customer-redeemable code for a coupon. It can be used to create multiple codes for a single coupon.
Stripe documentation: https://stripe.com/docs/api/promotion_codes?lang=python
active
property active: str
code
property code: str
max_redemptions
property max_redemptions: int | None
stripe_class
attribute stripe_class
times_redeemed
property times_redeemed: int
ShippingRate
Bases: StripeModel
Shipping rates describe the price of shipping presented to your customers and can be applied to Checkout Sessions to collect shipping costs.
Stripe documentation: https://stripe.com/docs/api/shipping_rates
active
property active
Whether the shipping rate can be used for new purchases. Defaults to true.
delivery_estimate
property delivery_estimate
The estimated range for how long shipping will take, meant to be displayable to the customer. This will appear on CheckoutSessions.
description
attribute description
display_name
property display_name
The name of the shipping rate, meant to be displayable to the customer. This will appear on CheckoutSessions.
fixed_amount
property fixed_amount
Describes a fixed amount to charge for shipping. Must be present if type is fixed_amount.
stripe_class
attribute stripe_class
stripe_dashboard_item_name
attribute stripe_dashboard_item_name
tax_behavior
property tax_behavior
Specifies whether the rate is considered inclusive of taxes or exclusive of taxes.
tax_code
attribute tax_code
type
property type
The type of calculation to use on the shipping rate. Can only be fixed_amount for now.
Subscription
Bases: StripeModel
Subscriptions allow you to charge a customer's card on a recurring basis. A subscription ties a customer to a particular plan you've created.
A subscription still in its trial period is trialing and moves to active
when the trial period is over.
When payment to renew the subscription fails, the subscription becomes past_due.
After Stripe has exhausted all payment retry attempts, the subscription ends up
with a status of either canceled or unpaid depending on your retry settings.
Note that when a subscription has a status of unpaid, no subsequent invoices
will be attempted (invoices will be created, but then immediately
automatically closed.
Additionally, updating customer card details will not lead to Stripe retrying the latest invoice.). After receiving updated card details from a customer, you may choose to reopen and pay their closed invoices.
Stripe documentation: https://stripe.com/docs/api?lang=python#subscriptions
application_fee_percent
property application_fee_percent
A non-negative decimal between 0 and 100, with at most two decimal places.
automatic_tax
property automatic_tax
Automatic tax settings for this subscription.
billing_cycle_anchor
property billing_cycle_anchor
Determines the date of the first full invoice.
billing_thresholds
property billing_thresholds
Define thresholds at which an invoice will be sent.
cancel_at
property cancel_at
A date in the future at which the subscription will automatically get canceled.
cancel_at_period_end
property cancel_at_period_end
If the subscription has been canceled with the at_period_end flag set to true.
canceled_at
property canceled_at
If the subscription has been canceled, the date of that cancellation.
collection_method
property collection_method
Either charge_automatically, or send_invoice.
current_period_end
property current_period_end
End of the current period that the subscription has been invoiced for.
current_period_start
property current_period_start
Start of the current period that the subscription has been invoiced for.
customer
attribute customer
days_until_due
property days_until_due
Number of days a customer has to pay invoices generated by this subscription.
default_payment_method
property default_payment_method
ID of the default payment method for the subscription.
default_source
property default_source
ID of the default payment source for the subscription.
default_tax_rates
property default_tax_rates
The tax rates that will apply to any subscription item that does not have tax_rates set.
discount
property discount
Describes the current discount applied to this subscription, if there is one.
ended_at
property ended_at
If the subscription has ended, the date the subscription ended.
items
property items
List of subscription items, each with an attached price.
latest_invoice
property latest_invoice
The most recent invoice this subscription has generated.
next_pending_invoice_item_invoice
property next_pending_invoice_item_invoice
Specifies the date on which the next invoice will be generated.
objects
attribute objects
pause_collection
property pause_collection
If specified, payment collection for this subscription will be paused.
payment_settings
property payment_settings
Payment settings passed on to invoices created by the subscription.
pending_invoice_item_interval
property pending_invoice_item_interval
Specifies an interval for how often to invoice for any pending invoice items.
pending_setup_intent
property pending_setup_intent
ID of a setup intent for this subscription if one exists.
pending_update
property pending_update
If specified, pending updates that will be applied to the subscription.
plan
property plan
The plan the customer is subscribed to. Only set if single plan.
quantity
property quantity
The quantity of the plan to which the customer is subscribed.
schedule
property schedule
The schedule attached to the subscription.
start_date
property start_date
Date when the subscription was created.
status
property status
The status of this subscription.
stripe_class
attribute stripe_class
stripe_dashboard_item_name
attribute stripe_dashboard_item_name
test_clock
property test_clock
ID of the test clock this subscription belongs to.
transfer_data
property transfer_data
The account (if any) the subscription's payments will be attributed to.
trial_end
property trial_end
If the subscription has a trial, the end of that trial.
trial_start
property trial_start
If the subscription has a trial, the beginning of that trial.
api_list
api_list(cls, api_key = djstripe_settings.STRIPE_SECRET_KEY, **kwargs)
Call the stripe API's list operation for this model. :param api_key: The api key to use for this request. Defaults to djstripe_settings.STRIPE_SECRET_KEY. :type api_key: string See Stripe documentation for accepted kwargs for each object. :returns: an iterator over all items in the query
cancel
cancel(self, at_period_end: bool = False, **kwargs)
Cancels this subscription. If you set the at_period_end parameter to true, the subscription will remain active until the end of the period, at which point it will be canceled and not renewed. By default, the subscription is terminated immediately. In either case, the customer will not be charged again for the subscription. Note, however, that any pending invoice items or metered usage will still be charged at the end of the period unless manually deleted.
Depending on how proration_behavior is set, any pending prorations will
also be left in place and collected at the end of the period.
However, if the subscription is set to cancel immediately, you can pass the
prorate and invoice_now flags in kwargs to configure how the pending
metered usage is invoiced and how proration must work.
By default, all unpaid invoices for the customer will be closed upon subscription cancellation. We do this in order to prevent unexpected payment retries once the customer has canceled a subscription. However, you can reopen the invoices manually after subscription cancellation to have us proceed with automatic retries, or you could even re-attempt payment yourself on all unpaid invoices before allowing the customer to cancel the subscription at all.
:param at_period_end: A flag that if set to true will delay the cancellation of the subscription until the end of the current period. Default is False. :type at_period_end: boolean
.. important:: If a subscription is canceled during a trial period, the at_period_end flag will be overridden to False so that the trial ends immediately and the customer's card isn't charged.
extend
extend(self, delta)
Extends this subscription by the provided delta.
:param delta: The timedelta by which to extend this subscription. :type delta: timedelta
is_period_current
is_period_current(self)
Returns True if this subscription's period is current, false otherwise.
is_status_current
is_status_current(self)
Returns True if this subscription's status is current (active or trialing), false otherwise.
is_status_temporarily_current
is_status_temporarily_current(self)
A status is temporarily current when the subscription is canceled with the
at_period_end flag.
The subscription is still active, but is technically canceled and we're just
waiting for it to run out.
You could use this method to give customers limited service after they've canceled. For example, a video on demand service could only allow customers to download their libraries and do nothing else when their subscription is temporarily current.
is_valid
is_valid(self)
Returns True if this subscription's status and period are current, false otherwise.
reactivate
reactivate(self)
Reactivates this subscription.
If a customer's subscription is canceled with at_period_end set to True and
it has not yet reached the end of the billing period, it can be reactivated.
Subscriptions canceled immediately cannot be reactivated.
(Source: https://stripe.com/docs/billing/subscriptions/cancel)
.. warning:: Reactivating a fully canceled Subscription will fail silently. Be sure to check the returned Subscription's status.
update
update(self, **kwargs)
See Customer.subscribe() <#djstripe.models.Customer.subscribe>__
.. important:: Updating a subscription by changing the price or quantity creates a new Subscription in Stripe (and dj-stripe).
SubscriptionItem
Bases: StripeModel
Subscription items allow you to create customer subscriptions with more than one plan, making it easy to represent complex billing relationships.
Stripe documentation: https://stripe.com/docs/api?lang=python#subscription_items
billing_thresholds
property billing_thresholds
Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period.
price
attribute price
proration_behavior
property proration_behavior
Determines how to handle prorations when the billing cycle changes.
proration_date
property proration_date
If set, the proration will be calculated as though the subscription was updated at the given time.
quantity
property quantity
The quantity of the plan to which the customer should be subscribed.
stripe_class
attribute stripe_class
subscription
attribute subscription
tax_rates
attribute tax_rates: models.ManyToManyField[TaxRate, Any]
SubscriptionSchedule
Bases: StripeModel
Subscription schedules allow you to create and manage the lifecycle of a subscription by predefining expected changes.
Stripe documentation: https://stripe.com/docs/api/subscription_schedules?lang=python
canceled_at
attribute canceled_at
completed_at
attribute completed_at
current_phase
attribute current_phase
customer
attribute customer
default_settings
attribute default_settings
end_behavior
attribute end_behavior
phases
attribute phases
released_at
attribute released_at
released_subscription
attribute released_subscription
status
attribute status
stripe_class
attribute stripe_class
stripe_dashboard_item_name
attribute stripe_dashboard_item_name
subscription
attribute subscription
cancel
cancel(self, api_key = None, stripe_account = None, **kwargs)
Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an active subscription). A subscription schedule can only be canceled if its status is not_started or active and returns the Canceled SubscriptionSchedule. :param api_key: The api key to use for this request. Defaults to djstripe_settings.STRIPE_SECRET_KEY. :type api_key: string :param stripe_account: The optional connected account for which this request is being made. :type stripe_account: string
release
release(self, api_key = None, stripe_account = None, **kwargs)
Releases the subscription schedule immediately, which will stop scheduling of its phases, but leave any existing subscription in place. A schedule can only be released if its status is not_started or active. If the subscription schedule is currently associated with a subscription, releasing it will remove its subscription property and set the subscription’s ID to the released_subscription property and returns the Released SubscriptionSchedule. :param api_key: The api key to use for this request. Defaults to djstripe_settings.STRIPE_SECRET_KEY. :type api_key: string :param stripe_account: The optional connected account for which this request is being made. :type stripe_account: string
update
update(self, api_key = None, stripe_account = None, **kwargs)
Updates an existing subscription schedule and returns the updated SubscriptionSchedule. :param api_key: The api key to use for this request. Defaults to djstripe_settings.STRIPE_SECRET_KEY. :type api_key: string :param stripe_account: The optional connected account for which this request is being made. :type stripe_account: string
TaxCode
Bases: StripeModel
Tax codes classify goods and services for tax purposes.
Stripe documentation: https://stripe.com/docs/api/tax_codes
metadata
attribute metadata
name
property name
A short name for the tax code.
stripe_class
attribute stripe_class
TaxId
Bases: StripeModel
Add one or multiple tax IDs to a customer. A customer's tax IDs are displayed on invoices and credit notes issued for the customer.
Stripe documentation: https://stripe.com/docs/api/customer_tax_ids?lang=python
country
property country
Two-letter ISO code representing the country of the tax ID.
customer
attribute customer
description
attribute description
metadata
attribute metadata
stripe_class
attribute stripe_class
type
property type
The type of tax ID.
value
property value
Value of the tax ID.
verification
property verification: dict | None
TaxRate
Bases: StripeModel
Tax rates can be applied to invoices and subscriptions to collect tax.
Stripe documentation: https://stripe.com/docs/api/tax_rates?lang=python
active
property active
Defaults to true. When set to false, this tax rate cannot be applied to objects in the API, but will still be applied to subscriptions and invoices that already have it set.
country
property country
Two-letter country code.
display_name
property display_name
The display name of the tax rates as it will appear to your customer on their receipt email, PDF, and the hosted invoice page.
inclusive
property inclusive
This specifies if the tax rate is inclusive or exclusive.
jurisdiction
property jurisdiction
The jurisdiction for the tax rate.
percentage
property percentage
This represents the tax rate percent out of 100.
state
property state
ISO 3166-2 subdivision code, without country prefix.
stripe_class
attribute stripe_class
stripe_dashboard_item_name
attribute stripe_dashboard_item_name
tax_type
property tax_type
The high-level tax type, such as vat, gst, sales_tax or custom.
UpcomingInvoice
Bases: BaseInvoice
The preview of an upcoming invoice - does not exist in the Django database.
See BaseInvoice.upcoming()
Logically it should be set abstract, but that doesn't quite work since we do actually want to instantiate the model and use relations.
default_tax_rates
property default_tax_rates
Gets the default tax rates associated with this upcoming invoice. :return:
id
property id
invoiceitems
property invoiceitems
Gets the invoice items associated with this upcoming invoice.
This differs from normal (non-upcoming) invoices, in that upcoming invoices are in-memory and do not persist to the database. Therefore, all of the data comes from the Stripe API itself.
Instead of returning a normal queryset for the invoiceitems, this will return a mock of a queryset, but with the data fetched from Stripe - It will act like a normal queryset, but mutation will silently fail.
lineitems
property lineitems
Gets the line items associated with this upcoming invoice.
This differs from normal (non-upcoming) invoices, in that upcoming invoices are in-memory and do not persist to the database. Therefore, all of the data comes from the Stripe API itself.
Instead of returning a normal queryset for the lineitems, this will return a mock of a queryset, but with the data fetched from Stripe - It will act like a normal queryset, but mutation will silently fail.
get_stripe_dashboard_url
get_stripe_dashboard_url(self)
save
save(self, *args, **kwargs)