djstripe.models.core

BalanceTransaction

Bases: StripeModel

A single transaction that updates the Stripe balance.

Stripe documentation: https://stripe.com/docs/api?lang=python#balance_transaction_object

amount

attribute  amount

available_on

property  available_on

currency

attribute  currency

exchange_rate

property  exchange_rate

fee

property  fee

fee_details

property  fee_details

net

property  net

reporting_category

property  reporting_category

source

attribute  source

status

property  status

stripe_class

attribute  stripe_class

type

attribute  type

get_source_class

get_source_class(self)

get_source_instance

get_source_instance(self)

get_stripe_dashboard_url

get_stripe_dashboard_url(self)

Charge

Bases: StripeModel

To charge a credit or a debit card, you create a charge object. You can retrieve and refund individual charges as well as list all charges. Charges are identified by a unique random ID.

Stripe documentation: https://stripe.com/docs/api?lang=python#charges

amount

attribute  amount

amount_captured

property  amount_captured

amount_refunded

property  amount_refunded

application

property  application

application_fee

property  application_fee

application_fee_amount

property  application_fee_amount

balance_transaction

attribute  balance_transaction

billing_details

property  billing_details

captured

property  captured

currency

attribute  currency

customer

attribute  customer

dispute

property  dispute

disputed

property  disputed

expand_fields

attribute  expand_fields

fee

property  fee

fraudulent

property  fraudulent: bool

human_readable_status

property  human_readable_status: str

invoice

attribute  invoice

objects

attribute  objects

on_behalf_of

property  on_behalf_of

outcome

property  outcome

paid

property  paid

payment_intent

attribute  payment_intent

payment_method

attribute  payment_method

payment_method_details

property  payment_method_details

receipt_email

property  receipt_email

receipt_number

property  receipt_number

receipt_url

property  receipt_url

refunded

property  refunded

shipping

property  shipping

source

attribute  source

statement_descriptor

property  statement_descriptor

statement_descriptor_suffix

property  statement_descriptor_suffix

status

attribute  status

stripe_class

attribute  stripe_class

stripe_dashboard_item_name

attribute  stripe_dashboard_item_name

transfer

property  transfer

transfer_data

property  transfer_data

transfer_group

property  transfer_group

capture

capture(self, **kwargs) -> Charge

Capture the payment of an existing, uncaptured, charge. This is the second half of the two-step payment flow, where first you created a charge with the capture option set to False.

See https://stripe.com/docs/api#capture_charge

refund

refund(self, amount: Decimal | None = None, reason: str | None = None, api_key: str | None = None, stripe_account: str | None = None) -> Refund

Initiate a refund. Returns the refund object.

:param amount: A positive decimal amount representing how much of this charge to refund. If amount is not provided, then this will be a full refund. Can only refund up to the unrefunded amount remaining of the charge. :param reason: String indicating the reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer. Specifying fraudulent as the reason when you believe the charge to be fraudulent will help Stripe improve their fraud detection algorithms.

Customer

Bases: StripeModel

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?lang=python#customers

active_subscriptions

property  active_subscriptions

Returns active subscriptions (subscriptions with an active status that end in the future).

address

property  address

balance

property  balance: int

coupon

property  coupon

credits

property  credits

The customer is considered to have credits if their balance is below 0.

currency

property  currency

date_purged

attribute  date_purged

default_payment_method

attribute  default_payment_method

default_source

property  default_source

deleted

property  deleted

delinquent

property  delinquent: bool

discount

property  discount

email

attribute  email

entitlements

property  entitlements

expand_fields

attribute  expand_fields

invoice_prefix

property  invoice_prefix: str | None

name

property  name

pending_charges

property  pending_charges

The customer is considered to have pending charges if their balance is above 0.

phone

property  phone

preferred_locales

property  preferred_locales

shipping

property  shipping

stripe_class

attribute  stripe_class

stripe_dashboard_item_name

attribute  stripe_dashboard_item_name

subscriber

attribute  subscriber

subscription

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

tax_exempt

property  tax_exempt

valid_subscriptions

property  valid_subscriptions

Returns this customer's valid subscriptions (subscriptions that aren't canceled, incomplete or incomplete_expired).

incomplete subscriptions are excluded because their initial payment has not yet succeeded (eg. subscriptions created with payment_behavior="default_incomplete"), so the customer is not yet paying for them.

add_coupon

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.

add_invoice_item

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_payment_method

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

charge

charge(self, amount: Decimal, *, application_fee: Decimal | None = None, source: str | StripeModel | None = None, **kwargs) -> Charge

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

create

create(cls, subscriber, idempotency_key = None, stripe_account = None, livemode: bool | None = djstripe_settings.STRIPE_LIVE_MODE, api_key = None, metadata = None, **kwargs)

Create a dj-stripe customer for the given subscriber.

:param metadata: A set of key/value pairs to store on the Stripe Customer. The configured SUBSCRIBER_CUSTOMER_KEY is always set to the subscriber's pk and takes precedence over a value supplied here, as dj-stripe relies on it to link the Customer to the subscriber. :type metadata: dict

Any additional keyword arguments are forwarded to the Stripe Customer create call, saving a round-trip vs. creating then updating.

get_or_create

get_or_create(cls, subscriber, livemode = djstripe_settings.STRIPE_LIVE_MODE, stripe_account = None, api_key = None, **kwargs)

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

Any additional keyword arguments (eg. metadata) are passed through to :meth:create and on to the Stripe Customer create call when a new customer has to be created.

has_any_active_subscription

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.

is_subscribed_to

is_subscribed_to(self, product: Product | str) -> bool

Checks to see if this customer has an active subscription to the given product.

:param product: The product for which to check for an active subscription. :type product: Product or string (product ID)

:returns: True if there exists an active subscription, False otherwise.

purge

purge(self)

Customers are soft deleted as deleted customers are still accessible by the Stripe API and sync for all RelatedModels would fail

send_invoice

send_invoice(self, **kwargs)

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

subscribe

subscribe(self, *, items = None, price = None, **kwargs)

Subscribes this customer to all the prices in the items dict (Recommended).

:param items: A list of up to 20 subscription items, each with an attached price :type list: :param items: A dictionary of Price (or Price ID) :type dict: The price to which to subscribe the customer.

:param price: The price to which to subscribe the customer. :type price: Price or string (price ID)

upcoming_invoice

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.

Dispute

Bases: StripeModel

A dispute occurs when a customer questions your charge with their card issuer. When this happens, you're given the opportunity to respond to the dispute with evidence that shows that the charge is legitimate

Stripe documentation: https://stripe.com/docs/api?lang=python#disputes

amount

property  amount: int

balance_transaction

attribute  balance_transaction

balance_transactions

property  balance_transactions

charge

attribute  charge

currency

property  currency

evidence

property  evidence

evidence_details

property  evidence_details

is_charge_refundable

property  is_charge_refundable

payment_intent

attribute  payment_intent

reason

property  reason

status

property  status

stripe_class

attribute  stripe_class

stripe_dashboard_item_name

attribute  stripe_dashboard_item_name

get_stripe_dashboard_url

get_stripe_dashboard_url(self) -> str

Get the stripe dashboard url for this object.

Event

Bases: StripeModel

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?lang=python

api_version

attribute  api_version

customer

property  customer

data

attribute  data

idempotency_key

attribute  idempotency_key

request_id

attribute  request_id

stripe_class

attribute  stripe_class

stripe_dashboard_item_name

attribute  stripe_dashboard_item_name

type

attribute  type

category

category(self)

Gets the event category string (e.g. 'customer').

invoke_webhook_handlers

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

parts(self)

Gets the event category/verb as a list of parts.

process

process(cls, data, api_key = None)

verb

verb(self)

Gets the event past-tense verb string (e.g. 'updated').

File

Bases: StripeModel

This is an object representing a file hosted on Stripe's servers. The file may have been uploaded by yourself using the create file request (for example, when uploading dispute evidence) or it may have been created by Stripe (for example, the results of a Sigma scheduled query).

Stripe documentation: https://stripe.com/docs/api/files?lang=python

filename

property  filename

purpose

property  purpose

size

property  size

stripe_class

attribute  stripe_class

type

property  type

url

property  url

is_valid_object

is_valid_object(cls, data)

FileLink

Bases: StripeModel

To share the contents of a File object with non-Stripe users, you can create a FileLink. FileLinks contain a URL that can be used to retrieve the contents of the file without authentication.

Stripe documentation: https://stripe.com/docs/api/file_links?lang=python

expires_at

property  expires_at

file

attribute  file

stripe_class

attribute  stripe_class

url

property  url

Mandate

Bases: StripeModel

A Mandate is a record of the permission a customer has given you to debit their payment method.

https://stripe.com/docs/api/mandates

customer_acceptance

property  customer_acceptance

multi_use

property  multi_use

payment_method

attribute  payment_method

payment_method_details

property  payment_method_details

single_use

property  single_use

status

property  status

stripe_class

attribute  stripe_class

type

property  type

PaymentIntent

Bases: StripeModel

A PaymentIntent guides you through the process of collecting a payment from your customer. We recommend that you create exactly one PaymentIntent for each order or customer session in your system. You can reference the PaymentIntent later to see the history of payment attempts for a particular session.

A PaymentIntent transitions through multiple statuses throughout its lifetime as it interfaces with Stripe.js to perform authentication flows and ultimately creates at most one successful charge.

Stripe documentation: https://stripe.com/docs/api?lang=python#payment_intents

customer

attribute  customer

on_behalf_of

attribute  on_behalf_of

payment_method

attribute  payment_method

stripe_class

attribute  stripe_class

stripe_dashboard_item_name

attribute  stripe_dashboard_item_name

update

update(self, api_key = None, stripe_account = None, **kwargs)

Call the stripe API's modify operation for this model and sync the result.

:param api_key: The api key to use for this request. Defaults to djstripe_settings.STRIPE_SECRET_KEY. :type api_key: string :param stripe_account: The optional connected account for which this request is being made. :type stripe_account: string

Payout

Bases: StripeModel

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?lang=python#payouts

amount

property  amount

arrival_date

property  arrival_date

automatic

property  automatic

balance_transaction

attribute  balance_transaction

currency

attribute  currency

destination

attribute  destination

expand_fields

attribute  expand_fields

failure_balance_transaction

attribute  failure_balance_transaction

failure_code

property  failure_code

failure_message

property  failure_message

method

property  method

original_payout

attribute  original_payout

reversed_by

attribute  reversed_by

source_type

property  source_type

statement_descriptor

property  statement_descriptor

status

property  status

stripe_class

attribute  stripe_class

stripe_dashboard_item_name

attribute  stripe_dashboard_item_name

type

property  type

Price

Bases: StripeModel

Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products.

Prices replace the legacy Plans API, which was removed in dj-stripe 2.11.

Stripe documentation:

• https://stripe.com/docs/api/prices
• https://stripe.com/docs/billing/prices-guide

active

attribute  active

billing_scheme

property  billing_scheme

currency

attribute  currency

expand_fields

attribute  expand_fields

human_readable_price

property  human_readable_price

lookup_key

attribute  lookup_key

nickname

attribute  nickname

product

attribute  product

recurring

property  recurring

stripe_class

attribute  stripe_class

stripe_dashboard_item_name

attribute  stripe_dashboard_item_name

tiers

property  tiers

tiers_mode

property  tiers_mode

transform_quantity

property  transform_quantity

type

property  type

unit_amount

property  unit_amount

unit_amount_decimal

property  unit_amount_decimal

create

create(cls, **kwargs)

get_or_create

get_or_create(cls, **kwargs)

Get or create a Price.

Product

Bases: StripeModel

Products describe the specific goods or services you offer to your customers. For example, you might offer a Standard and Premium version of your goods or service; each version would be a separate Product. They can be used in conjunction with Prices to configure pricing in Payment Links, Checkout, and Subscriptions.

Stripe documentation: https://stripe.com/docs/api?lang=python#products

active

attribute  active

default_price

property  default_price: Union[Price, None]

name

attribute  name

stripe_class

attribute  stripe_class

stripe_dashboard_item_name

attribute  stripe_dashboard_item_name

type

property  type

unit_label

property  unit_label

url

property  url

Refund

Bases: StripeModel

Refund objects allow you to refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged.

Stripe documentation: https://stripe.com/docs/api?lang=python#refund_object

amount

attribute  amount

balance_transaction

attribute  balance_transaction

charge

attribute  charge

currency

attribute  currency

failure_balance_transaction

attribute  failure_balance_transaction

failure_reason

property  failure_reason

reason

property  reason

receipt_number

property  receipt_number

status

property  status

stripe_class

attribute  stripe_class

get_stripe_dashboard_url

get_stripe_dashboard_url(self)

SetupIntent

Bases: StripeModel

A SetupIntent guides you through the process of setting up a customer's payment credentials for future payments. For example, you could use a SetupIntent to set up your customer's card without immediately collecting a payment. Later, you can use PaymentIntents to drive the payment flow.

NOTE: You should not maintain long-lived, unconfirmed SetupIntents. For security purposes, SetupIntents older than 24 hours may no longer be valid.

Stripe documentation: https://stripe.com/docs/api?lang=python#setup_intents

customer

attribute  customer

on_behalf_of

attribute  on_behalf_of

payment_method

attribute  payment_method

stripe_class

attribute  stripe_class