Some companies start their own users on a free plan. Within Stripe, this means that you could have users who have a subscription record, but the product and price within the subscription is for $0. When a customer on the free tier wants to upgrade to a paid plan to be paid through Loop, this is how you can handle that scenario. You will need to construct a checkout session with specific body parameters.

Please note, the directions below are for when the customer is subscribed to a free product in Stripe and did not sign up for the free plan using a Loop checkout page. If it is the case that the customer is already set up with Loop, then you need to follow the upgrade and/or adding items flow.

Process for upgrading from free tier to paid plan

1. Fetch the subscription details from Stripe
   1. You will need to retrieve the subscription ID from the customer who is on the free tier.
   2. Subscription IDs start with a prefix sub_ (example: sub_1RUTXtD7oqbPtWsfxDBWTsMJ)
2. Construct the request to generate a checkout session in Loop
   1. Use the Create Checkout Session endpoint.
   2. At a minimum, you need to update the following body parameters in the request.
      1. externalPriceId - this is the price ID from Stripe of the paid tier that you want to upgrade the customer to
      2. externalSubscriptionId - this is the subscription ID you retrieved from Stripe in step 1
      3. upgradeSubscription - se the boolean value as True
         Here is an example request:

      curl --request POST \
           --url http://staging.api.loopcrypto.xyz/api/v1/checkout-session \
           --header 'accept: application/json' \
           --header 'api-key: XXXXXXX' \
           --header 'content-type: application/json' \
           --header 'entity-id: XXXXXXXXX' \
           --data '
      {
        "elements": [
          {
            "externalPriceId": "price_1RU8NRD7oqbPtWsfDIUS9rgj"
          }
        ],
        "externalSubscriptionId": "sub_1RUTXtD7oqbPtWsfxDBWTsMJ",
        "upgradeSubscription": true
      }
      '

      
      
3. Generate the checkout link from the configured session.
4. User visits the checkout link and completes payment.
   1. The subscription record will be updated in Stripe.
   2. You will see the relevant invoice marked as paid in Stripe as well.

Notes on functionality of this feature

This flow supports upgrades from a free trial product to a paid product only. The parameter upgradeSubscription cannot currently be used for paid-to-paid product upgrades. See this page on upgrades for handling that scenario.