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, this is how you can handle that scenario with Loop Crypto. You will need to construct a checkout session with specific body parameters.

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.