Repository: dj-stripe/dj-stripe

Issue:
API change for Subscription in version 2020-08-27
**Changelog Link**
- [changelog](https://stripe.com/docs/upgrades#2020-08-27)

**Describe the Change**
- This affects the [Subscription model](https://github.com/dj-stripe/dj-stripe/blob/master/djstripe/models/billing.py#L1216)
- The `prorate` parameter is deprecated in favor of `proration_behavior`.
- Affects dj-stripe v2.4.1 and Stripe API 2020-08-27

The Subscription [update method](https://github.com/dj-stripe/dj-stripe/blob/master/djstripe/models/billing.py#L1440) currently passes the `prorate` parameter to `self._api_update()` and results in an `InvalidRequestError` from Stripe.

```
...
File "/usr/local/lib/python3.8/site-packages/djstripe/models/billing.py", line 1476, in update
    stripe_subscription = self._api_update(plan=plan, prorate=prorate, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/djstripe/models/base.py", line 236, in _api_update
    return instance.request("post", instance.instance_url(), params=kwargs)
  File "/usr/local/lib/python3.8/site-packages/stripe/stripe_object.py", line 243, in request
    response, api_key = requestor.request(method, url, params, headers)
  File "/usr/local/lib/python3.8/site-packages/stripe/api_requestor.py", line 122, in request
    resp = self.interpret_response(rbody, rcode, rheaders)
  File "/usr/local/lib/python3.8/site-packages/stripe/api_requestor.py", line 373, in interpret_response
    self.handle_error_response(rbody, rcode, resp.data, rheaders)
  File "/usr/local/lib/python3.8/site-packages/stripe/api_requestor.py", line 152, in handle_error_response
    raise err
stripe.error.InvalidRequestError: Request req_EvwnuCgvDqq4zU: Received unknown parameter: prorate
```

I believe this parameter should be either removed or updated to the new `proration_behavior` spec. If you want to go with updating it, the [PRORATION_POLICY setting](https://github.com/dj-stripe/dj-stripe/blob/master/djstripe/settings.py#L68) will need to be changed from a Boolean to a String. An equivalent default here for the new Stripe API version would be `"none"`

Notes on the `proration_behavior` field from Stripe docs:
"Determines how to handle prorations resulting from the billing_cycle_anchor. Valid values are create_prorations or none.

Passing create_prorations will cause proration invoice items to be created when applicable. Prorations can be disabled by passing none. If no value is passed, the default is create_prorations."

If you provide some guidance on whether you'd like to remove the old param or update it to use the new parameter I can submit a PR for the changes.


Discussion:
@hyshka I've hit this issue today too and I've prepared a pull request. Could you review it? https://github.com/dj-stripe/dj-stripe/pull/1300

Resolving patch:
diff --git a/djstripe/models/billing.py b/djstripe/models/billing.py
--- a/djstripe/models/billing.py
+++ b/djstripe/models/billing.py
@@ -1440,7 +1440,7 @@ def __str__(self):
     def update(
         self,
         plan: Union[StripeModel, str] = None,
-        prorate=djstripe_settings.PRORATION_POLICY,
+        prorate: bool = None,
         **kwargs,
     ):
         """
@@ -1461,7 +1461,23 @@ def update(
         if plan is not None and isinstance(plan, StripeModel):
             plan = plan.id
 
-        stripe_subscription = self._api_update(plan=plan, prorate=prorate, **kwargs)
+        if "proration_behavior" not in kwargs:
+            if prorate is not None:
+                warnings.warn(
+                    "The `prorate` parameter to Subscription.update() is deprecated "
+                    "by Stripe. Use `proration_behavior` instead.\n"
+                    "Read more: "
+                    "https://stripe.com/docs/billing/subscriptions/prorations"
+                )
+            else:
+                prorate = djstripe_settings.PRORATION_POLICY
+
+            if prorate:
+                kwargs.setdefault("proration_behavior", "create_prorations")
+            else:
+                kwargs.setdefault("proration_behavior", "none")
+
+        stripe_subscription = self._api_update(plan=plan, **kwargs)
 
         return Subscription.sync_from_stripe_data(stripe_subscription)
 
@@ -1483,7 +1499,7 @@ def extend(self, delta):
 
         period_end += delta
 
-        return self.update(prorate=False, trial_end=period_end)
+        return self.update(proration_behavior="none", trial_end=period_end)
 
     def cancel(self, at_period_end=djstripe_settings.CANCELLATION_AT_PERIOD_END):
         """


Test patch: