Stripe Invoice.Upcoming changes: model switching from monthly to yearly

Alexander Baumann — Mon, 16 Dec 2024 22:22:59 +0000

How to use the Python SDK stripe.Invoice.upcoming call to preview a new invoice using a different quantity and plan?

There is a reference in the Stripe Invoice docs stating values can be passed when retrieving the upcoming invoice to model what-if scenarios

https://docs.stripe.com/billing/invoices/subscription#previewing:~:text=When%20fetching%20the,Adding%20a%20coupon.
ex: you can pass a different subscription_quantity or subscription_plan

When fetching the preview, you can also model what the invoice would look like if you changed the subscription in one of these ways:

Swapping the underlying price.
Altering the quantity.
Applying a trial period.
Adding a coupon.

There isn't enough information in the API or SDK changelogs to determine how to replace the deprecated params we use with new ones

Old:

return stripe.Invoice.upcoming(
        customer=customer_id,
        subscription=stripe_subscription_id,
        subscription_quantity=quantity_to_calculate_with, # if None, defaults to current
        subscription_proration_date=proration_date_as_unix_seconds,  
        subscription_plan=plan_to_calculate_with, # if None, defaults to current  
    )

Attempted New:

subscription_details = dict(
proration_date=proration_date_as_unix_seconds, 
items=[
     {
     'quantity': quantity_to_calculate_with, 
     'plan': plan_to_calculate_with
     }
])

return stripe.Invoice.upcoming(
        customer=customer_id,
        subscription=stripe_subscription_id,
        subscription_details=subscription_details
)

I can set the price to the plan id I was using before, the problem I have now is that I cannot model the new invoice price when switching from a monthly to a yearly plan. The error:

All prices on a subscription must have the same recurring.interval and recurring.interval_count. If you meant to update an existing subscription item instead of creating a new one, make sure to include the subscription item ID in your request. See examples at https://stripe.com/docs/billing/subscriptions/upgrade-downgrade#changing.

DEV Community: Alexander Baumann

Stripe Invoice.Upcoming changes: model switching from monthly to yearly