Build a switch/upgrade plan flow that requires payment
Let your customers switch from their current plan to a new plan by making an initial payment.
Offer upgrades to prepaid plans
You want to offer your customers to change to a different plan as part of an upsell or upgrade campaign. For this you want to make them an offer, and only if they accept the upgrade offer with an up-front payment, the new plan should become effective.
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.
Read more about the full setup here in our Help Center: Upgrades to Prepaid plans
A very typical use case for this is that if customers are currently on a monthly recurring plan, you want to offer them to upgrade to a 6 month prepaid plan, which has a discounted per-month price. Part of the flow would be that the customer needs to pay the 6 month price up-front before the plan change comes into effect.
Let's get on to implementation with the Firmhouse API.
What are we building?
Implementing the plan switch flow is different from just updating someone's plan immediately, which is a more simple operation and can be done with the updateSubcribedPlan
mutation.
Here's how the plan switch flow will work:
In your own Headless Storefront or My Account section you build something that promotes the upgrade offer and explain how it will benefit the customer.
From this promotion section you provide a link or button with logic that calls the
switchSubscriptionPlan
mutation at Firmhouse with the subscription and plan to upgrade to.The
switchSubscriptionPlan
mutation will create a special "offer" flow in Firmhouse and will return a URL to you that you need to redirect your customer to make a payment and in doing so accept the offer.The customer then continues to make the payment for the offer.
When the payment is received, Firmhouse will record the payment, finalize an invoice, switch the Subscription to the appropriate plan, and generates any other objects like
ContractTermEvent
s.The customer is then optionally redirected back to a success URL that you passed in when calling the
switchSubscriptionPlan
mutation.You can subscribe to webhooks to recognize if an offer was accepted and a plan switch was applied.
Creating upsell or promotion UI on your website
First you need to have a piece of UI in your own Storefront or My Account that promotes upgrading or switching to the new plan. This can be some kind of widget on the my account dashboard. Or for example some kind of modal window that pops up when someone clicks some kind of "Upgrade" or "Change plan" button.
In this piece of UI you probably will have a link or button that will initiate the upgrade and payment flow so the customer can complete the payment and make the plan change effective.
Initiating the plan switch offer flow
To create the plan switch offer and ask the customer for payment, call theswitchSubscriptionPlan
mutation.
The following query examples will initiate a plan switch offer payment flow for subscription 1234 and plan 456. Under the hood an Offer
object is generated by Firmhouse. Please note that an Offer expires after 30 minutes!
Redirect the customer to the returned offer.acceptUrl
to immediately open a payment flow for the requested payment via your standard payment provider configuration. This is the same payment flow as if they would be paying for an open or outstanding invoice.
Catching accepted offers via webhook
When an Offer
is accepted by the customer, the offer status is marked as completed. In addition, an offer_completed webhook is emitted.
Emails triggered
When an Offer
is accepted by the customer. Email notifications also sent out via project notifications and to the customer. The email notification to your customer can be configured in the Email Configuration of your project in the Firmhouse portal.
FAQ
Can I supply via the API or can customers enter a discount codes?
Not yet. This is one of the things we have ideas for improving on. But currently we do not yet allow any type of discount code to be supplied or filled out by the customer in this flow.
Last updated