Invoice: Add support for Create Preview Invoice API

The Upcoming Invoice API is deprecated and removed since API version
2025-03-31:
https://docs.stripe.com/changelog/basil/2025-03-31/invoice-preview-api-deprecations

The new Create Preview Invoice API is almost the same and only the
parameters structure changed.

Reference: https://docs.stripe.com/api/invoices/create_preview

Author: bravier

localstripe/resources.py

@@ -1602,6 +1602,40 @@ def _api_upcoming_invoice(cls, customer=None, subscription=None,
 
         return invoice
 
+    @classmethod
+    def _api_create_preview_invoice(cls, customer=None, subscription=None,
+                                    subscription_details=None):
+        try:
+            if subscription_details is not None:
+                assert type(subscription_details) is dict
+        except AssertionError:
+            raise UserError(400, 'Bad request')
+
+        details = subscription_details or {}
+        default_tax_rates = details.get('default_tax_rates')
+        items = details.get('items')
+        proration_date = details.get('proration_date')
+        trial_end = details.get('trial_end')
+
+        invoice = cls._get_next_invoice(
+            customer=customer,
+            subscription=subscription,
+            upcoming=True,
+            subscription_default_tax_rates=default_tax_rates,
+            subscription_items=items,
+            subscription_proration_date=proration_date,
+            subscription_trial_end=trial_end)
+
+        # Do not store this invoice but real Stripe server do for a limited
+        # amount of time (72 hours) which make it possible to retrieve it
+        # on route /v1/invoices/:id:
+        # https://docs.stripe.com/invoicing/preview
+        del store[cls.object + ':' + invoice.id]
+
+        invoice.id = f'upcoming_{invoice.id}'
+
+        return invoice
+
     @classmethod
     def _api_pay_invoice(cls, id):
         obj = Invoice._api_retrieve(id)
@@ -1664,6 +1698,8 @@ def _api_list_lines(cls, id, limit=None, **kwargs):
 
 extra_apis.extend((
     ('GET', '/v1/invoices/upcoming', Invoice._api_upcoming_invoice),
+    ('POST', '/v1/invoices/create_preview',
+     Invoice._api_create_preview_invoice),
     ('POST', '/v1/invoices/{id}/pay', Invoice._api_pay_invoice),
     ('POST', '/v1/invoices/{id}/void', Invoice._api_void_invoice),
     ('GET', '/v1/invoices/{id}/lines', Invoice._api_list_lines)))

test.sh

@@ -472,6 +472,11 @@ code=$(curl -sg -o /dev/null -w "%{http_code}" -u $SK: \
             $HOST/v1/invoices/upcoming?customer=$cus)
 [ "$code" = 404 ]
 
+code=$(curl -sg -o /dev/null -w "%{http_code}" -u $SK: \
+            $HOST/v1/invoices/create_preview \
+            -d customer=$cus)
+[ "$code" = 404 ]
+
 curl -sSfg -u $SK: $HOST/v1/subscriptions \
      -d customer=$cus \
      -d items[0][plan]=basique-mensuel \
@@ -492,6 +497,17 @@ curl -sSfg -u $SK: $HOST/v1/invoices/upcoming?customer=$cus\&subscription_items[
 
 curl -sSfg -u $SK: $HOST/v1/invoices/upcoming?customer=$cus\&subscription=$sub\&subscription_items[0][id]=si_RBrVStcKDimMnp\&subscription_items[0][plan]=basique-annuel\&subscription_proration_date=1504182686\&subscription_tax_percent=20
 
+curl -sSfg -u $SK: $HOST/v1/invoices/create_preview \
+     -d customer=$cus
+
+curl -sSfg -u $SK: $HOST/v1/invoices/create_preview \
+     -d customer=$cus \
+     -d subscription=$sub \
+     -d subscription_details[default_tax_rates][0]=$txr1 \
+     -d subscription_details[items][0][id]=si_RBrVStcKDimMnp \
+     -d subscription_details[items][0][plan]=basique-annuel \
+     -d subscription_details[proration_date]=1504182686
+
 curl -sSfg -u $SK: $HOST/v1/invoices/$in/lines
 
 cus=$(curl -sSfg -u $SK: $HOST/v1/customers \