How do I collect and attach payment details when upgrading a Stripe subscription from Free to Paid?

Below is the recommended approach:

1. Collect and Attach a Payment Method First
   Instead of trying to upgrade the subscription without a payment source, first use a SetupIntent to securely collect the payment details. This can be done with Stripe Elements (or another UI kit) as part of your custom flow. The SetupIntent confirms and automatically attaches the new PaymentMethod to your Customer.

   For example, on the backend create a SetupIntent:

   PYTHONCopied
   setup_intent = stripe.SetupIntent.create(
       customer=customer_id,
       usage='off_session',  # or 'on_session' per your flow
   )

   Then on the frontend, use Stripe Elements with the returned client secret from setup_intent.client_secret and call stripe.confirmCardSetup to collect and confirm the payment details. Once confirmation succeeds, the PaymentMethod is attached to the customer.

2. Set the Payment Method as Default
   After the PaymentMethod is attached, update the customer's default payment method so that it’s used for subscriptions and invoices. You can do this by updating the Customer’s invoice_settings.default_payment_method:

   PYTHONCopied
   stripe.Customer.modify(
       customer_id,
       invoice_settings={
           'default_payment_method': payment_method_id,
       }
   )

3. Upgrade the Subscription
   Now that the customer has a valid and attached PaymentMethod, you can update the subscription to switch to the Paid plan. When updating the subscription, if necessary you can specify the payment method to use (for example, via the payment_settings[default_payment_method] parameter) or rely on the customer’s default payment method that you just set.

   For example, to update the subscription:

   PYTHONCopied
   stripe_client.subscriptions.update(
       subscription_id,
       {
           "expand": ["latest_invoice.payment_intent"],
           "items": [
               {
                   "id": subscription_item_id,
                   "price": paid_price_id,  # new paid plan price
                   "quantity": quantity,
               }
           ],
           # Optionally, you can also pass the default payment method:
           "payment_settings": {
               "default_payment_method": payment_method_id,
           },
       },
   )

By following this three‐step approach, you ensure that when the user upgrades from a free to a paid plan:

• Their card details are collected securely using a SetupIntent.
• The PaymentMethod is attached to the customer and set as default.
• The subscription update call subsequently finds a valid payment source to charge.

This aligns with the recommended best practices in Stripe’s documentation for saving payment methods for future usage.