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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

class 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

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