You can upgrade customers to Prepaid plans via our special plan switch flow. The plan switch flow in Firmhouse is a simplified checkout where customers only need to make a one-time payment. After they make the payment, their plan is upgraded to the selected Prepaid plan.

Offering an upgrade to prepaid plans is a great way to retain your loyal customers and give them a price discount while you're at it. For you as a merchant, this brings in up-front cash so you can grow your business.

This flow currently is available through the API and you can read our guide in our Developer Docs to learn how to initiate the flow from your own app, Storefront, or custom My Account.

This article will show you what the customer will go through and what things are triggered and happen that you need to be aware of as a merchant.

In Firmhouse, create the Plans that you want to offer as upgrade options. You can also use Plans that you're already using to offer a prepaid subscription at Checkout.

The are currently two restrictions:

Make note of the IDs of the Plans you want to offer upgrades to. You will later use the ID of a Plan in the API call to initiate a plan switch flow for a customer.

First off, you'll need to have some user interface in your own My Account, website, or app so that people are made aware of the pre-paid options.

For example you can have a list or cards of upgrade options you offer showing the one-time price that someone will pay, but also how that will result in an effective discount on their monthly price. In each option you show a button that your customer can click to go into the plan switch flow.

The button in your user interface should then make an API call to the Firmhouse API to create a plan switch offer for the given subscription and the new plan. This API call will return an Offer object with a URL where the customer can accept the offer and make their payment.

Take a look at the switchSubscriptionPlan mutation in our Developer Docs to learn how to make this API call.

After being redirect to the link returned by our API, Firmhouse will immediately initiate the payment flow for the Plan's configured initial amount. So typically the customer will see a page like the following where the amount is shown and they can continue to choose a payment method or enter their card details:

If you want to show a little bit information about the upgrade first, you can remove the ?auto_submit=true from the link so that your customer first sees a page like the following:

There are a few things that will happen after the payment was made by your customer.

When the upgrade offer was successfully paid by the customer they will see a screen similar to the following:

Optionally it is also possible to fully skip this screen by passing in the successUrl parameter in the switchSubscriptionPlan API call that initiates the plan switch flow.

By redirecting back to your website, you can show a nicely branded and integrated message to congratulate your customer that they successfully upgraded to their new plan.

The current active plan of the customer will switch to the new plan immediately and will show up in the Firmhouse Portal as their active plan.

The customer's next billing date will stay the same if you look at it on the customer's detail page in Firmhouse Portal. O their next usual billing date, the new prepaid plan's frequency becomes effective.

How this works is that under the hood is that we already prepare the next billing cycle and attach the invoice of the prepaid payment to it. So on their next billing cycle there will be no charge and invoice as they've already pre-paid for that.

This billing cycle will then be recalculated to the next billing date depending on the plan that's active. This could be next month for a monthly billing cycle. But it could also be in 6 months or a year, depending on what the Plan is set to as recurring billing frequency.

You can set up the Offer completed email template in your Firmhouse project to configure the email that gets sent out when a customer upgrades their subscription. You can use the appropriate liquid tags in that email to include information about the customer, like their new plan.

Whenever an offer is completed we also send out webhook notifications for the offer_completed event so that you can trigger any follow-up steps in external systems or integrations.