Loop allows you to take a payment and modify a subscription in one action. For example, some companies start users on a free plan in Stripe and then upgrade that subscription by modifying the products to a paid plan and want that payment to be made through Loop.

To do this, you will need to construct a checkout session with specific body parameters.

Please note, 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 and switching to pay by Loop

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 new product 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 - set 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.