Models
Models hold the bulk of the functionality included in the dj-stripe package. Each model is tied closely to its corresponding object in the stripe dashboard. Fields that are not implemented for each model have a short reason behind the decision in the docstring for each model.
Core Resources
Balance Transaction
djstripe.models.BalanceTransaction
(*args, **kwargs)A single transaction that updates the Stripe balance.
Stripe documentation: https://stripe.com/docs/api#balance_transaction_object
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Charge
djstripe.models.Charge :docstring: :members: api_list api_retrieve get_stripe_dashboard_url disputed refund capture sync_from_stripe_data
Customer
djstripe.models.Customer
(*args, **kwargs)Customer objects allow you to perform recurring charges and track multiple charges that are associated with the same customer.
Stripe documentation: https://stripe.com/docs/api/python#customers
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
get_or_create
(subscriber, livemode=False, stripe_account=None)Get or create a dj-stripe customer.
:param subscriber: The subscriber model instance for which to get or create a customer. :type subscriber: User
:param livemode: Whether to get the subscriber in live or test mode. :type livemode: bool
legacy_cards
Accessor to the related objects manager on the reverse side of a many-to-one relation.
In the example::
class Child(Model):
parent = ForeignKey(Parent, related_name='children')
Parent.children
is a ReverseManyToOneDescriptor
instance.
Most of the implementation is delegated to a dynamically defined manager
class built by create_forward_many_to_many_manager()
defined below.
credits
The customer is considered to have credits if their balance is below 0.
customer_payment_methods
An iterable of all of the customer's payment methods (sources, then legacy cards)
pending_charges
The customer is considered to have pending charges if their balance is above 0.
subscribe
(self, price=None, plan=None, charge_immediately=True, **kwargs)Subscribes this customer to a price. NOTE: Only one item is supported at the moment.
:param price: The price to which to subscribe the customer. :type price: Price or string (price ID) :param plan: The plan to which to subscribe the customer. :type plan: Plan or string (plan ID) :param charge_immediately: Whether or not to charge for the subscription upon creation. If False, an invoice will be created at the end of this period. :type charge_immediately: boolean
.. Notes:
.. charge_immediately
is only available on Customer.subscribe()
.. if you're using Customer.subscribe()
.. instead of Customer.subscribe()
, plan
can only be a string
charge
(self, amount, *, application_fee=None, source=None, **kwargs)Creates a charge for this customer.
:param amount: The amount to charge. :type amount: Decimal. Precision is 2; anything more will be ignored. :param source: The source to use for this charge. Must be a source attributed to this customer. If None, the customer's default source is used. Can be either the id of the source or the source object itself. :type source: string, Source
add_invoice_item
(self, amount, currency, description=None, discountable=None, invoice=None, metadata=None, subscription=None)Adds an arbitrary charge or credit to the customer's upcoming invoice. Different than creating a charge. Charges are separate bills that get processed immediately. Invoice items are appended to the customer's next invoice. This is extremely useful when adding surcharges to subscriptions.
:param amount: The amount to charge.
:type amount: Decimal. Precision is 2; anything more will be ignored.
:param currency: 3-letter ISO code for currency
:type currency: string
:param description: An arbitrary string.
:type description: string
:param discountable: Controls whether discounts apply to this invoice item.
Defaults to False for prorations or negative invoice items,
and True for all other invoice items.
:type discountable: boolean
:param invoice: An existing invoice to add this invoice item to.
When left blank, the invoice item will be added to the next upcoming scheduled invoice. Use this when adding invoice items in response to an invoice.created
webhook. You cannot add an invoice item to an invoice that has already been paid, attempted or closed.
:type invoice: Invoice or string (invoice ID)
:param metadata: A set of key/value pairs useful for storing
additional information.
:type metadata: dict
:param subscription: A subscription to add this invoice item to.
When left blank, the invoice item will be be added to the next upcoming scheduled invoice. When set, scheduled invoices for subscriptions other than the specified subscription will ignore the invoice item. Use this when you want to express that an invoice item has been accrued within the context of a particular subscription.
:type subscription: Subscription or string (subscription ID)
.. Notes:
.. if you're using Customer.add_invoice_item()
instead of
.. Customer.add_invoice_item()
, invoice
and subscriptions
.. can only be strings
add_card
(self, source, set_default=True)Adds a card to this customer's account.
:param source: Either a token, like the ones returned by our Stripe.js, or a dictionary containing a user's credit card details. Stripe will automatically validate the card. :type source: string, dict :param set_default: Whether or not to set the source as the customer's default source :type set_default: boolean
add_payment_method
(self, payment_method, set_default=True)Adds an already existing payment method to this customer's account
:param payment_method: PaymentMethod to be attached to the customer :type payment_method: str, PaymentMethod :param set_default: If true, this will be set as the default_payment_method :type set_default: bool :rtype: PaymentMethod
purge
(self)has_active_subscription
(self, plan=None)Checks to see if this customer has an active subscription to the given plan.
:param plan: The plan for which to check for an active subscription. If plan is None and there exists only one active subscription, this method will check if that subscription is valid. Calling this method with no plan and multiple valid subscriptions for this customer will throw an exception. :type plan: Plan or string (plan ID)
:returns: True if there exists an active subscription, False otherwise.
:throws: TypeError if plan
is None and more than one active subscription
exists for this customer.
has_any_active_subscription
(self)Checks to see if this customer has an active subscription to any plan.
:returns: True if there exists an active subscription, False otherwise.
active_subscriptions
Returns active subscriptions (subscriptions with an active status that end in the future).
valid_subscriptions
Returns this customer's valid subscriptions (subscriptions that aren't canceled or incomplete_expired).
subscription
Shortcut to get this customer's subscription.
:returns: None if the customer has no subscriptions, the subscription if
the customer has a subscription.
:raises MultipleSubscriptionException: Raised if the customer has multiple
subscriptions.
In this case, use Customer.subscriptions
instead.
can_charge
(self)Determines if this customer is able to be charged.
send_invoice
(self)Pay and send the customer's latest invoice.
:returns: True if an invoice was able to be created and paid, False otherwise (typically if there was nothing to invoice).
retry_unpaid_invoices
(self)Attempt to retry collecting payment on the customer's unpaid invoices.
has_valid_source
(self)Check whether the customer has a valid payment source.
add_coupon
(self, coupon, idempotency_key=None)Add a coupon to a Customer.
The coupon can be a Coupon object, or a valid Stripe Coupon ID.
upcoming_invoice
(self, **kwargs)Gets the upcoming preview invoice (singular) for this customer.
See Invoice.upcoming() <#djstripe.Invoice.upcoming>
__.
The customer
argument to the upcoming()
call is automatically set
by this method.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Dispute
djstripe.models.Dispute
(*args, **kwargs)Stripe documentation: https://stripe.com/docs/api#disputes
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Event
djstripe.models.Event
(*args, **kwargs)Events are Stripe's way of letting you know when something interesting happens in your account. When an interesting event occurs, a new Event object is created and POSTed to the configured webhook URL if the Event type matches.
Stripe documentation: https://stripe.com/docs/api/events
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
process
(data)invoke_webhook_handlers
(self)Invokes any webhook handlers that have been registered for this event based on event type or event sub-type.
See event handlers registered in the djstripe.event_handlers
module
(or handlers registered in djstripe plugins or contrib packages).
parts
Gets the event category/verb as a list of parts.
category
Gets the event category string (e.g. 'customer').
verb
Gets the event past-tense verb string (e.g. 'updated').
customer
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
File Upload
djstripe.models.FileUpload
(*args, **kwargs)Stripe documentation: https://stripe.com/docs/api#file_uploads
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Payout
djstripe.models.Payout
(*args, **kwargs)A Payout object is created when you receive funds from Stripe, or when you initiate a payout to either a bank account or debit card of a connected Stripe account.
Stripe documentation: https://stripe.com/docs/api#payouts
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
PaymentIntent
djstripe.models.PaymentIntent
(*args, **kwargs)Stripe documentation: https://stripe.com/docs/api#payment_intents
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Price
djstripe.models.Price
(*args, **kwargs)Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products.
Price and Plan objects are the same, but use a different representation. Creating a recurring Price in Stripe also makes a Plan available, and vice versa. This is not the case for a Price with interval=one_time.
Price objects are a more recent API representation, support more features and its usage is encouraged instead of Plan objects.
Stripe documentation: - https://stripe.com/docs/api/prices - https://stripe.com/docs/billing/prices-guide
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
get_or_create
(**kwargs)Get or create a Price.
human_readable_price
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Product
djstripe.models.Product
(*args, **kwargs)Stripe documentation: - https://stripe.com/docs/api#products - https://stripe.com/docs/api#service_products
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Refund
djstripe.models.Refund
(*args, **kwargs)Stripe documentation: https://stripe.com/docs/api#refund_object
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Payment Methods
BankAccount
djstripe.models.BankAccount
(*args, **kwargs)BankAccount(djstripe_id, id, djstripe_owner_account, livemode, created, metadata, description, djstripe_created, djstripe_updated, account, account_holder_name, account_holder_type, bank_name, country, currency, customer, default_for_currency, fingerprint, last4, routing_number, status)
api_list
(api_key='', **kwargs)api_retrieve
(self, **kwargs)get_stripe_dashboard_url
(self)sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Card
djstripe.models.Card
(*args, **kwargs)You can store multiple cards on a customer in order to charge the customer later.
This is a legacy model which only applies to the "v2" Stripe API (eg. Checkout.js). You should strive to use the Stripe "v3" API (eg. Stripe Elements). Also see: https://stripe.com/docs/stripe-js/elements/migrating When using Elements, you will not be using Card objects. Instead, you will use Source objects. A Source object of type "card" is equivalent to a Card object. However, Card objects cannot be converted into Source objects by Stripe at this time.
Stripe documentation: https://stripe.com/docs/api/python#cards
api_list
(api_key='', **kwargs)api_retrieve
(self, api_key=None, stripe_account=None)get_stripe_dashboard_url
(self)remove
(self)Removes a legacy source from this customer's account.
create_token
(number, exp_month, exp_year, cvc, api_key='', **kwargs)Creates a single use token that wraps the details of a credit card. This token can be used in place of a credit card dictionary with any API method. These tokens can only be used once: by creating a new charge object, or attaching them to a customer. (Source: https://stripe.com/docs/api/python#create_card_token)
:param number: The card number without any separators (no spaces) :param exp_month: The card's expiration month. (two digits) :param exp_year: The card's expiration year. (four digits) :param cvc: Card security code. :param api_key: The API key to use
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
PaymentMethod
djstripe.models.PaymentMethod
(*args, **kwargs)Stripe documentation: https://stripe.com/docs/api#payment_methods
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
attach
(payment_method, customer, api_key='')Attach a payment method to a customer
detach
(self)Detach the payment method from its customer.
:return: Returns true if the payment method was newly detached, false if it was already detached :rtype: bool
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Source
djstripe.models.Source
(*args, **kwargs)Stripe documentation: https://stripe.com/docs/api#sources
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
detach
(self)Detach the source from its customer.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Billing
Coupon
djstripe.models.Coupon
(*args, **kwargs)Coupon(djstripe_id, djstripe_owner_account, livemode, created, metadata, description, djstripe_created, djstripe_updated, id, amount_off, currency, duration, duration_in_months, max_redemptions, name, percent_off, redeem_by, times_redeemed)
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
human_readable_amount
human_readable
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Invoice
djstripe.models.Invoice
(*args, **kwargs)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/python#invoices
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)upcoming
(api_key='', customer=None, coupon=None, subscription=None, subscription_plan=None, subscription_prorate=None, subscription_proration_date=None, subscription_quantity=None, subscription_trial_end=None, **kwargs)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) :param subscription_plan: If set, the invoice returned will preview updating the subscription given to this plan, or creating a new subscription to this plan if no subscription is given. :type subscription_plan: Plan or string (plan ID) :param subscription_prorate: If previewing an update to a subscription, this decides whether the preview will show the result of applying prorations or not. :type subscription_prorate: bool :param subscription_proration_date: If previewing an update to a subscription, and doing proration, subscription_proration_date forces the proration to be calculated as though the update was done at the specified time. :type subscription_proration_date: datetime :param subscription_quantity: If provided, the invoice returned will preview updating or creating a subscription with that quantity. :type subscription_quantity: int :param subscription_trial_end: If provided, the invoice returned will preview updating or creating a subscription with that trial end. :type subscription_trial_end: datetime :returns: The upcoming preview invoice.
retry
(self)Retry payment on this invoice if it isn't paid or uncollectible.
plan
Gets the associated plan for this invoice.
In order to provide a consistent view of invoices, the plan object should be taken from the first invoice item that has one, rather than using the plan associated with the subscription.
Subscriptions (and their associated plan) are updated by the customer and represent what is current, but invoice items are immutable within the invoice and stay static/unchanged.
In other words, a plan retrieved from an invoice item will represent the plan as it was at the time an invoice was issued. The plan retrieved from the subscription will be the currently active plan.
:returns: The associated plan for the invoice.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
InvoiceItem
djstripe.models.InvoiceItem
(*args, **kwargs)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/python#invoiceitems
api_list
(api_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
api_retrieve
(self, *args, **kwargs)get_stripe_dashboard_url
(self)sync_from_stripe_data
(data)Plan
djstripe.models.Plan
(*args, **kwargs)A subscription plan contains the pricing information for different products and feature levels on your site.
Stripe documentation: https://stripe.com/docs/api/plans
NOTE: The Stripe Plans API has been deprecated in favor of the Prices API. You may want to upgrade to use the Price model instead of the Plan model.
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
get_or_create
(**kwargs)Get or create a Plan.
amount_in_cents
human_readable_price
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Subscription
djstripe.models.Subscription
(*args, **kwargs)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/python#subscriptions
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
update
(self, plan=None, prorate=None, **kwargs)See Customer.subscribe() <#djstripe.models.Customer.subscribe>
__
:param plan: The plan to which to subscribe the customer. :type plan: Plan or string (plan ID)
.. note:: The default value for prorate
is the DJSTRIPE_PRORATION_POLICY setting.
.. important:: Updating a subscription by changing the plan or quantity creates a new Subscription
in Stripe (and dj-stripe).
extend
(self, delta)Extends this subscription by the provided delta.
:param delta: The timedelta by which to extend this subscription. :type delta: timedelta
cancel
(self, at_period_end=True)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 that you've created will still be charged for at the end of the period unless manually deleted. If you've set the subscription to cancel at period end, any pending prorations will also be left in place and collected at the end of the period, but if the subscription is set to cancel immediately, pending prorations will be removed.
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.
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/subscriptions/canceling-pausing)
.. warning:: Reactivating a fully canceled Subscription will fail silently. Be sure to check the returned Subscription's status.
is_period_current
(self)Returns True if this subscription's period is current, false otherwise.
is_status_current
(self)Returns True if this subscription's status is current (active or trialing), false otherwise.
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
(self)Returns True if this subscription's status and period are current, false otherwise.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
SubscriptionItem
djstripe.models.SubscriptionItem
(*args, **kwargs)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#subscription_items
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
TaxRate
djstripe.models.TaxRate
(*args, **kwargs)Tax rates can be applied to invoices and subscriptions to collect tax.
Stripe documentation: https://stripe.com/docs/api/tax_rates
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
UpcomingInvoice
djstripe.models.UpcomingInvoice
(*args, **kwargs)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.
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)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.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
UsageRecord
djstripe.models.UsageRecord
(*args, **kwargs)Usage records allow you to continually report usage and metrics to Stripe for metered billing of plans.
Stripe documentation: https://stripe.com/docs/api#usage_records
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Connect
Account
djstripe.models.Account
(*args, **kwargs)Stripe documentation: https://stripe.com/docs/api#account
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
get_connected_account_from_token
(access_token)get_default_account
()sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Application Fee
djstripe.models.ApplicationFee
(*args, **kwargs)When you collect a transaction fee on top of a charge made for your user (using Connect), an ApplicationFee is created in your account.
Stripe documentation: https://stripe.com/docs/api#application_fees
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Country Spec
djstripe.models.CountrySpec
(*args, **kwargs)Stripe documentation: https://stripe.com/docs/api#country_specs
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Transfer
djstripe.models.Transfer
(*args, **kwargs)When Stripe sends you money or you initiate a transfer to a bank account, debit card, or connected Stripe account, a transfer object will be created.
Stripe documentation: https://stripe.com/docs/api/python#transfers
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Transfer Reversal
djstripe.models.TransferReversal
(*args, **kwargs)Stripe documentation: https://stripe.com/docs/api#transfer_reversals
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Fraud
TODO
Orders
TODO
Sigma
ScheduledQueryRun
djstripe.models.ScheduledQueryRun
(*args, **kwargs)Stripe documentation: https://stripe.com/docs/api#scheduled_queries
api_list
(api_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
api_retrieve
(self, api_key=None, stripe_account=None)Call the stripe API's retrieve operation for this model.
:param api_key: The api key to use for this request. Defaults to 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
get_stripe_dashboard_url
(self)Get the stripe dashboard url for this object.
sync_from_stripe_data
(data)Syncs this object from the stripe data provided.
Foreign keys will also be retrieved and synced recursively.
:param data: stripe object :type data: dict :rtype: cls
Webhooks
WebhookEventTrigger
djstripe.models.WebhookEventTrigger
(*args, **kwargs)An instance of a request that reached the server endpoint for Stripe webhooks.
Webhook Events are initially UNTRUSTED, as it is possible for any web entity to post any data to our webhook url. Data posted may be valid Stripe information, garbage, or even malicious. The 'valid' flag in this model monitors this.
json_body
is_test_event
from_request
(request)Create, validate and process a WebhookEventTrigger given a Django request object.
The process is three-fold: 1. Create a WebhookEventTrigger object from a Django request. 2. Validate the WebhookEventTrigger as a Stripe event using the API. 3. If valid, process it into an Event object (and child resource).