Models

def __str__(self):
    return f"{self.human_readable_amount} ({enums.BalanceTransactionStatus.humanize(self.status)})"

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def get_source_class(self):
    try:
        return apps.get_model("djstripe", self.type)
    except LookupError:
        raise

def get_source_instance(self):
    return self.get_source_class().objects.get(id=self.source)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def get_stripe_dashboard_url(self):
    return self.get_source_instance().get_stripe_dashboard_url()

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def __str__(self):
    amount = self.human_readable_amount
    status = self.human_readable_status
    return "{amount} ({status})".format(amount=amount, status=status)

def 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
    """

    captured_charge = self.api_retrieve().capture(**kwargs)
    return self.__class__.sync_from_stripe_data(captured_charge)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def refund(self, amount: Decimal = None, reason: str = None) -> "Charge":
    """
    Initiate a refund. Returns the charge 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.
    """
    charge_obj = self.api_retrieve().refund(
        amount=self._calculate_refund_amount(amount=amount), reason=reason
    )
    return self.__class__.sync_from_stripe_data(charge_obj)

def __str__(self):
    if self.subscriber:
        return str(self.subscriber)

    return self.name or self.description or self.id

def 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

    """
    from .payment_methods import DjstripePaymentMethod

    stripe_customer = self.api_retrieve()
    new_stripe_payment_method = stripe_customer.sources.create(source=source)

    if set_default:
        stripe_customer.default_source = new_stripe_payment_method["id"]
        stripe_customer.save()

    new_payment_method = DjstripePaymentMethod.from_stripe_object(
        new_stripe_payment_method
    )

    # Change the default source
    if set_default:
        self.default_source = new_payment_method
        self.save()

    return new_payment_method.resolve()

def 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.
    """
    if isinstance(coupon, StripeModel):
        coupon = coupon.id

    stripe_customer = self.api_retrieve()
    stripe_customer["coupon"] = coupon
    stripe_customer.save(idempotency_key=idempotency_key)
    return self.__class__.sync_from_stripe_data(stripe_customer)

def 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
    """
    from .billing import InvoiceItem

    if not isinstance(amount, Decimal):
        raise ValueError("You must supply a decimal value representing dollars.")

    # Convert Invoice to id
    if invoice is not None and isinstance(invoice, StripeModel):
        invoice = invoice.id

    # Convert Subscription to id
    if subscription is not None and isinstance(subscription, StripeModel):
        subscription = subscription.id

    stripe_invoiceitem = InvoiceItem._api_create(
        amount=int(amount * 100),  # Convert dollars into cents
        currency=currency,
        customer=self.id,
        description=description,
        discountable=discountable,
        invoice=invoice,
        metadata=metadata,
        subscription=subscription,
    )

    return InvoiceItem.sync_from_stripe_data(stripe_invoiceitem)

def 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
    """
    from .payment_methods import PaymentMethod

    stripe_customer = self.api_retrieve()
    payment_method = PaymentMethod.attach(payment_method, stripe_customer)

    if set_default:
        stripe_customer["invoice_settings"][
            "default_payment_method"
        ] = payment_method.id
        stripe_customer.save()

        # Refresh self from the stripe customer, this should have two effects:
        # 1) sets self.default_payment_method (we rely on logic in
        # Customer._manipulate_stripe_object_hook to do this)
        # 2) updates self.invoice_settings.default_payment_methods
        self.sync_from_stripe_data(stripe_customer)
        self.refresh_from_db()

    return payment_method

def can_charge(self):
    """Determines if this customer is able to be charged."""

    return (
        self.has_valid_source() or self.default_payment_method is not None
    ) and self.date_purged is None

def charge(
    self,
    amount: Decimal,
    *,
    application_fee: Decimal = None,
    source: Union[str, StripeModel] = 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
    """

    if not isinstance(amount, Decimal):
        raise ValueError("You must supply a decimal value representing dollars.")

    # Convert Source to id
    if source and isinstance(source, StripeModel):
        source = source.id

    stripe_charge = Charge._api_create(
        customer=self.id,
        amount=int(amount * 100),  # Convert dollars into cents
        application_fee=int(application_fee * 100)
        if application_fee
        else None,  # Convert dollars into cents
        source=source,
        **kwargs,
    )

    return Charge.sync_from_stripe_data(stripe_charge)

@classmethod
def create(cls, subscriber, idempotency_key=None, stripe_account=None):
    metadata = {}
    subscriber_key = djstripe_settings.SUBSCRIBER_CUSTOMER_KEY
    if subscriber_key not in ("", None):
        metadata[subscriber_key] = subscriber.pk

    stripe_customer = cls._api_create(
        email=subscriber.email,
        idempotency_key=idempotency_key,
        metadata=metadata,
        stripe_account=stripe_account,
    )
    customer, created = Customer.objects.get_or_create(
        id=stripe_customer["id"],
        defaults={
            "subscriber": subscriber,
            "livemode": stripe_customer["livemode"],
            "balance": stripe_customer.get("balance", 0),
            "delinquent": stripe_customer.get("delinquent", False),
        },
    )

    return customer

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

@classmethod
def get_or_create(
    cls,
    subscriber,
    livemode=djstripe_settings.STRIPE_LIVE_MODE,
    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
    """

    try:
        return Customer.objects.get(subscriber=subscriber, livemode=livemode), False
    except Customer.DoesNotExist:
        action = "create:{}".format(subscriber.pk)
        idempotency_key = djstripe_settings.get_idempotency_key(
            "customer", action, livemode
        )
        return (
            cls.create(
                subscriber,
                idempotency_key=idempotency_key,
                stripe_account=stripe_account,
            ),
            True,
        )

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)

def 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.
    """

    return len(self._get_valid_subscriptions()) != 0

def has_valid_source(self):
    """Check whether the customer has a valid payment source."""
    return self.default_source is not None

def is_subscribed_to(self, product: Union[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.
    """

    if isinstance(product, StripeModel):
        product = product.id

    for subscription in self._get_valid_subscriptions():
        for item in subscription.items.all():
            if item.price and item.price.product.id == product:
                return True
    return False

def purge(self):
    """Customers are soft deleted as deleted customers are still accessible by the
    Stripe API and sync for all RelatedModels would fail"""
    try:
        self._api_delete()
    except InvalidRequestError as exc:
        if "No such customer:" in str(exc):
            # The exception was thrown because the stripe customer was already
            # deleted on the stripe side, ignore the exception
            pass
        else:
            # The exception was raised for another reason, re-raise it
            raise

    # toggle the deleted flag on Customer to indicate it has been
    # deleted upstream in Stripe
    self.deleted = True

    if self.subscriber:
        # Delete the idempotency key used by Customer.create()
        # So re-creating a customer for this subscriber before the key expires
        # doesn't return the older Customer data
        idempotency_key_action = "customer:create:{}".format(self.subscriber.pk)
        IdempotencyKey.objects.filter(action=idempotency_key_action).delete()

    self.subscriber = None

    # Remove sources
    self.default_source = None
    for source in self.legacy_cards.all():
        source.remove()

    for source in self.sources.all():
        source.detach()

    self.date_purged = timezone.now()
    self.save()

def retry_unpaid_invoices(self):
    """Attempt to retry collecting payment on the customer's unpaid invoices."""

    self._sync_invoices()
    for invoice in self.invoices.filter(auto_advance=True).exclude(status="paid"):
        try:
            invoice.retry()  # Always retry unpaid invoices
        except InvalidRequestError as exc:
            if str(exc) != "Invoice is already paid":
                raise

def 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).
    """
    from .billing import Invoice

    try:
        invoice = Invoice._api_create(customer=self.id)
        invoice.pay()
        return True
    except InvalidRequestError:  # TODO: Check this for a more
        #                           specific error message.
        return False  # There was nothing to invoice

def subscribe(self, *, items=None, price=None, plan=None, **kwargs):
    """
    Subscribes this customer to all the prices or plans 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 Plan (or Plan ID) or Price (or Price ID)
        :type dict:  The price or plan to which to subscribe the customer.

    :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)
    """
    from .billing import Subscription

    products_lst = []

    if (items and price) or (items and plan) or (price and plan):
        raise TypeError("Please define only one of items, price or plan arguments.")

    if items:
        for item in items:
            price = item.get("price", "")
            plan = item.get("plan", "")

            price, kwargs = self._sanitise_price(price, plan, **kwargs)

            # todo override Subscription.sync_from_stripe_data to attach all subscriptions to the customer using bulk updates
            stripe_subscription = Subscription._api_create(
                items=[item], customer=self.id, **kwargs
            )

            Subscription.sync_from_stripe_data(stripe_subscription)

            # get associated product
            product_name = Price.objects.get(id=price).product.name
            # keep count of products subscribed to
            products_lst.append(product_name)

    else:
        warnings.warn(
            "The Customer.subscribe() method will not be accepting price (or price id)"
            " or plan (or plan id) arguments and support will be removed in dj-stripe 2.5+."
            " Please default to using the items dictionary which will allow you to subscribe"
            " the given customer to one or more than one plan in one go.",
            DeprecationWarning,
        )

        price, kwargs = self._sanitise_price(price, plan, **kwargs)

        stripe_subscription = Subscription._api_create(
            items=[{"price": price}], customer=self.id, **kwargs
        )

        Subscription.sync_from_stripe_data(stripe_subscription)

        # get associated product
        product_name = Price.objects.get(id=price).product.name
        # keep count of products subscribed to
        products_lst.append(product_name)

    return f"Subscribed {self} to {' and '.join(products_lst)}"

def 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.
    """
    from .billing import Invoice

    kwargs["customer"] = self
    return Invoice.upcoming(**kwargs)

def __str__(self):
    return f"{self.human_readable_amount} ({enums.DisputeStatus.humanize(self.status)}) "

def _method(cls_or_self, /, *args, **keywords):
    keywords = {**self.keywords, **keywords}
    return self.func(cls_or_self, *self.args, *args, **keywords)