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.

This feature is currently in private beta.

What are we building?

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 initial payment, the new plan should become effective.

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.

This is slightly 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 this 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 ContractTermEvents.

• 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!

Basic sample

mutation SwitchSubscriptionPlan()
  switchSubscriptionPlan(input: {
    subscriptionId: 1234,
    planId: 456
  }) {
    offer {
      id
      acceptUrl
    }
  }
}

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.

With return URLs

mutation SwitchSubscriptionPlan()
  switchSubscriptionPlan(input: {
    subscriptionId: 1234,
    planId: 456,
    successUrl: "https://myaccount.mybrand.com/upgrade/success",
    failureUrl: "https://myaccount.mybrand.com/upgrade"
  }) {
    offer {
      id
      acceptUrl
    }
  }
}

This sample will use the supplied successUrl and failureUrl to redirect the customer back to your website. The successUrl is used after the customer makes the succesful payment. The failureUrl is used when the customer goes to the offer URL after it was expired.

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.