Update documentation to mention subscription using PaymentMethod (dj-…

…stripe#1083) Also added Customer.add_payment_method to model docs, and fixed a doc formatting issue. Resolves dj-stripe#1049, dj-stripe#1047.
ryancausey · Dec 21, 2019 · 9264d6f · 9264d6f
1 parent d5a9e86
commit 9264d6f
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 6 deletions.
diff --git a/djstripe/models/core.py b/djstripe/models/core.py
@@ -916,8 +916,8 @@ def add_payment_method(self, payment_method, set_default=True):
         :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: bool
-        :return:
+        :type set_default: bool
+        :rtype: PaymentMethod
         """
         from .payment_methods import PaymentMethod
 

diff --git a/docs/reference/models.rst b/docs/reference/models.rst
@@ -59,6 +59,7 @@ Customer
 .. automethod:: djstripe.models.Customer.charge
 .. automethod:: djstripe.models.Customer.add_invoice_item
 .. automethod:: djstripe.models.Customer.add_card
+.. automethod:: djstripe.models.Customer.add_payment_method
 .. automethod:: djstripe.models.Customer.purge
 .. automethod:: djstripe.models.Customer.has_active_subscription
 .. automethod:: djstripe.models.Customer.has_any_active_subscription

diff --git a/docs/usage/subscribing_customers.rst b/docs/usage/subscribing_customers.rst
@@ -1,17 +1,18 @@
 Subscribing a customer to a plan
 ================================
 
-For your convenience, dj-stripe provides a ``Customer.subscribe()`` method that
-will try to charge the customer immediately unless you specify ``charge_immediately=False``
+For your convenience, dj-stripe provides a :meth:`djstripe.models.Customer.subscribe`
+method that will try to charge the customer immediately unless you specify
+``charge_immediately=False``
 
 .. code-block:: python
 
     plan = Plan.objects.get(nickname="one_plan")
     customer = Customer.objects.first()
     customer.subscribe(plan)
 
-However in some cases ``Customer.subscribe()`` might not support all the arguments
-you need for your implementation. When this happens you can just call the
+However in some cases :meth:`djstripe.models.Customer.subscribe` might not support all
+the arguments you need for your implementation. When this happens you can just call the
 official ``stripe.Customer.subscribe()``.
 
 See this example from ``tests.apps.example.views.PurchaseSubscriptionView.form_valid``
@@ -21,3 +22,21 @@ See this example from ``tests.apps.example.views.PurchaseSubscriptionView.form_v
    :start-after: User.objects.create
    :end-before: self.request.subscription
    :dedent: 2
+
+
+Note that PaymentMethods can be used instead of Cards/Source by substituting
+
+.. code-block:: python
+
+    # Add the payment method customer's default
+    customer.add_payment_method(payment_method)
+
+instead of
+
+.. code-block:: python
+
+    # Add the source as the customer's default card
+    customer.add_card(stripe_source)
+
+
+in the above example.  See :meth:`djstripe.models.Customer.add_payment_method`.