Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.firmhouse.com/llms.txt

Use this file to discover all available pages before exploring further.

Use this guide when you want to offer customers an upgrade or plan switch from a headless storefront, Magento account area, Salesforce Commerce Cloud account area, or another external customer experience. This flow is useful when the new plan should only become active after the customer pays an initial amount. A common example is upgrading from a monthly recurring plan to a prepaid 6-month plan with a lower monthly equivalent price.
Paid plan switch offers are currently in private beta.

​
How it works

  1. You build the upgrade promotion UI in your own storefront or account area.
  2. When the customer accepts the offer, your app calls switchSubscriptionPlan.
  3. Firmhouse creates an Offer and returns an acceptUrl.
  4. You redirect the customer to acceptUrl.
  5. The customer completes payment through your configured payment provider.
  6. Firmhouse records the payment, finalizes the invoice, switches the subscription to the new plan, and creates related records.
  7. Firmhouse redirects the customer to your success or failure URL if you passed those URLs to the mutation.
  8. You can listen for webhooks to know when the offer was accepted.
For simple plan changes that should take effect immediately and do not require payment first, use updateSubscribedPlan instead.

​
Create the upgrade UI

Create a section in your storefront or account area that explains the upgrade and why it is useful to the customer. This can be:
  • a dashboard widget
  • a modal behind an Upgrade button
  • a plan comparison screen
  • a campaign landing page for logged-in customers
The call to action should trigger your backend or frontend integration code that calls switchSubscriptionPlan.

​
Start the paid switch flow

Call switchSubscriptionPlan with the current subscription ID and the target plan ID. 
mutation SwitchSubscriptionPlan {
  switchSubscriptionPlan(input: {
    subscriptionId: 1234,
    planId: 456
  }) {
    offer {
      id
      acceptUrl
    }
  }
}
Redirect the customer to offer.acceptUrl. Firmhouse opens the payment flow for the requested initial payment. Offer URLs expire after 30 minutes. Create the offer when the customer explicitly starts the upgrade flow, not ahead of time.

​
Redirect customers back to your site

Pass successUrl and failureUrl if you want customers to return to your own website after the payment flow. 
mutation SwitchSubscriptionPlan {
  switchSubscriptionPlan(input: {
    subscriptionId: 1234,
    planId: 456,
    successUrl: "https://myaccount.example.com/upgrade/success",
    failureUrl: "https://myaccount.example.com/upgrade"
  }) {
    offer {
      id
      acceptUrl
    }
  }
}
Use:
  • successUrl after the customer successfully pays and accepts the offer.
  • failureUrl when the offer URL has expired or the offer cannot be accepted.

​
Listen for accepted offers

When the customer accepts the offer, Firmhouse marks the offer as completed and emits an offer_completed webhook. Use that webhook to update your external customer account area, analytics, CRM, or marketing automation.

​
Emails

When an offer is accepted, Firmhouse can send project notifications and customer email notifications. Configure the customer-facing email in Email Configuration in your Firmhouse project.

​
Limitations

Customers cannot enter discount codes in this paid plan switch flow yet, and the API does not support supplying a discount code for the offer.