Skip to main content
In Firmhouse, you can enable the Cancellation and Churn Prevention flow. This feature allows you to better collect feedback and prevent immediate churn by offering a winback during the cancellation steps in the subscription my account portal. The new Cancellation Feedback and Prevention flow offers a few steps in the customer journey when cancelling:
  1. Customer clicks cancel from their dashboard
  2. Chooses from one of the predefined cancellation reasons (if available)
  3. Gets offered a winback
  4. Takes the winback offer or proceeds to cancel and gives feedback

​
Enable the new Cancellation flow

​
Steps

  1. Go to your project in Firmhouse and click New Features from the sidebar.
  2. On this page, enable Cancellation Reasons and Winback Offers.
Enable Cancellation Reasons and Winback Offers in New Features Customer Portal v2 projects show Churn prevention under Customer Portal in the sidebar. Projects using the legacy portal show it under Settings. If the Customer Portal v2 cancellation preview is enabled, open Customer Portal > Cancellation to arrange reason-specific responses and publish a flow. Until you publish, customers keep using the existing reason-and-feedback flow. New reasons added there are immediately available in the subscription account portal. Each response can be limited to matching subscriptions with the same conditions used by Components, including current products, plan, completed deliveries, revenue, segment, status, and Shopify order tags. Responses are checked in order and skipped when their conditions do not match. Product selection uses search, so the builder does not load the full catalog for projects with many SKUs. Leave eligibility empty to make a response the fallback for everyone.

​
Add a cancellation reason and winback offer

​
Steps

  1. In your Firmhouse project, go to Customer Portal > Churn prevention. For the legacy portal, go to Settings > Churn prevention.
  2. Click Add Reason.
  3. Fill out a Reporting title, which is the language-independent title of this reason to be used in reporting exports and dashboards.
  4. Fill out the Customer-facing cancellation reason, which is the text that people will see in the Cancellation flow.
  5. Under What customers see, choose an Alternative action: Continue to cancellation, offer to pause for 1–3 months, or offer to skip 1–3 orders.
  6. Enable or disable the reason with the Status checkbox.
  7. Click Save.
Add cancellation reason form For reusable offers with customer targeting, benefits such as complimentary products or plan swaps, and optional minimum terms, see Promotional offers.

​
Connect a promotional offer to a reason

When the Workflow Builder preview is enabled, What customers see lets you expand the promotional offers linked to a saved reason. Only offers with an explicit condition targeting this reason can appear during cancellation. Every other eligibility condition must still match the customer. If several offers qualify, the offer with the lowest priority number is checked first. Expand Linked offers and choose an offer to review its conditions. To create one, check Create an offer for this reason, then choose Save and create offer to open a draft with that reason preselected. After saving the offer, you return to the reason. The list shows each offer’s status and omits archived offers. An eligible promotional offer appears first. The configured pause or skip alternative is shown alongside it and remains available when no offer is available or the customer declines it. Continue to cancellation adds no pause or skip alternative; it does not disable promotional offers.

​
Record a reason when cancelling or pausing for a customer

When your team performs the action from a customer’s subscription page, the cancellation or pause form shows the active reasons configured for that flow. By default, selecting a reason is optional: select the reason the customer gave you, or leave it blank for an internal action where no customer reason should be recorded. To require reasons for team actions:
  1. Enable Cancellation Reasons and Winback Offers and Pause Reasons and Winback Offers in New Features.
  2. Add at least one active reason for each flow in Customer Portal > Churn prevention (or Settings > Churn prevention for the legacy portal).
  3. Go to Settings > Subscription model and enable Require a reason when team members cancel or pause subscriptions.
With this setting enabled, team members must select a configured reason before starting a cancellation. For pauses, they must select either a configured customer reason or Internal pause (no reason). The initial Select a pause reason placeholder cannot be submitted. Cancellation notes alone do not satisfy the cancellation requirement. Confirming a cancellation that is already in progress does not ask for another reason. Use Internal pause (no reason) for operational holds, such as a subscription switch. This option is available only to your team, including when no configured pause reasons are available. It saves a completed internal pause in subscription history and keeps the customer reason blank in Liquid and webhook data. It does not automatically suppress emails: an external email workflow can use the blank reason to exclude internal pauses. The setting is off by default and applies only to team actions from the subscription page. Customer portal flows, API calls, and automated actions keep their existing behavior. Only project managers and users with permission to update the project can change this setting. Both reason features must be enabled before turning it on. If either feature is later disabled, you can still turn the requirement off in Subscription model settings. An admin-selected reason is included in churn history, reporting, Liquid templates, and webhook payloads. Because the customer does not see the portal flow, Firmhouse records the action as completed without presenting or reporting a winback offer. Pause reasons are available in the admin pause form only while the Pause Reasons and Winback Offers preview is enabled.

​
Start a cancellation or pause with a known reason

When another system already knows why a customer wants to cancel or pause, add the active reason ID to the flow URL as the churn_reason_id query parameter:
For a pause, include both parameters:
Firmhouse records the supplied reason, skips the reason selection and winback steps, and shows the customer a confirmation step. After the customer confirms, Firmhouse performs the cancellation or pause and takes them to the completion step. The subscription’s normal eligibility rules still apply, including its status, cancellation strategy, commitment terms, and whether customer pausing is enabled. Opening the link does not cancel or pause the subscription by itself. This makes the link safe to preview or retry and ensures the customer deliberately confirms the change. The reason must be active, belong to the same Firmhouse project, and be configured for the requested flow. If the ID is invalid or does not meet these conditions, Firmhouse shows the normal reason selection instead. If the subscription is not eligible for the requested action, Firmhouse does not initiate the churn request and continues with the standard eligibility flow.

​
Complete a custom cancellation flow without another confirmation

If your Customer Portal v2 template already asks the customer to confirm, submit that confirmation directly to subscription.complete_churn_request_url. This skips the Firmhouse confirmation page while keeping the change behind an authenticated, CSRF-protected POST request.
For a custom pause flow, add <input type="hidden" name="flow" value="pause"> and use a reason configured for pauses. Only use this endpoint for a customer action that has already presented a clear confirmation. A GET request never completes the change. Firmhouse still verifies that the reason is active and belongs to the current project and flow, and rechecks the subscription’s cancellation or pause eligibility before applying it. An invalid reason returns the customer to the standard reason-selection flow.

​
Record a save in a fully custom cancellation flow

If your Customer Portal v2 template handles retention actions outside the native Firmhouse flow, use window.Firmhouse.churnRequests to record the outcome through the customer’s portal session. It handles the portal URL and CSRF token. Do not put a project access token in template JavaScript. For other Customer Portal v2 JSON endpoints, window.Firmhouse.request(url, { method, body }) provides the same authenticated, same-origin request handling. The churn methods use it and add the churn-request lifecycle checks. Start a cancellation request when the customer enters your custom flow. An active cancellation reason ID is optional. Keep the returned request ID for this attempt.
If the customer selects a reason later, call startCancellation again with that reason; it updates the initiated request. After an intentional Keep plan choice or a successful custom retention action, record prevention and await the response before showing a saved confirmation or leaving the page.
The result has status prevented and follow-up action custom_retention. It contributes to Analytics → Metrics → Churn Prevention for the period when the request was created. Retrying prevent with the same request ID returns the existing outcome. A completed cancellation cannot be changed to prevented. The subscription must still be active or paused when you record the save. Both methods return promises. If either rejects, do not show a saved confirmation. You can retry startCancellation while the request is initiated, or retry prevent with the same request ID if its result is uncertain. Only record a save after the customer deliberately keeps the plan or a retention action succeeds. Navigating back, closing the page, or merely clicking through to a skip or postpone confirmation is not a saved outcome. The portal endpoint only records the outcome. It does not change a plan, skip an order, pause a subscription, apply a discount, or undo a cancellation. Handle those changes separately and record prevention only after they succeed. If the customer proceeds to cancellation, use the authenticated confirmation flow described above.

​
Pause Reasons and Winback Offers

The same churn prevention flow is available when customers pause their subscription. Instead of pausing immediately, the flow asks customers why they are pausing, can respond with a winback offer, and collects feedback after the pause.

​
Enable

  1. Go to your project in Firmhouse and click New Features from the sidebar.
  2. On this page, enable Pause Reasons and Winback Offers.
Subscription pausing itself needs to be enabled in your customer portal settings for the pause button to appear.

​
Add a pause reason

  1. In your Firmhouse project, go to Customer Portal > Churn prevention. For the legacy portal, go to Settings > Churn prevention.
  2. Click Add reason and set Shown before to Customer pauses their subscription.
  3. Fill out the reason the same way as a cancellation reason. The Alternative action options are: Continue to pause, offer to pause for 1–3 months with an automatic resume date, and offer to skip 1–3 orders. Promotional offers are only shown during cancellation, so pause reasons do not show the promotional-offer section.
Pause reasons are only shown in the pause flow, and cancellation reasons only in the cancellation flow. The Shown before column on the Churn prevention page shows which flow each reason belongs to. When a customer proceeds with pausing, they can leave feedback just like with cancellations. On the Metrics > Churn Prevention page, use the Cancellations / Pauses toggle to view prevention rates, winback breakdowns, and customer feedback for each flow separately.

​
View Cancellation feedback and Winback results per customer

When a customer completes a Cancellation flow - either by taking a winback offer or by cancelling - their choices and feedback can be seen on the Customer detail page in the Firmhouse admin portal. Customer cancellation feedback on detail page

​
View Cancellation and Churn Prevention metrics

In your Firmhouse project, navigate to Metrics in the sidebar. Then click the Churn Prevention tab to view aggregated metrics about cancellation reasons and winback offer acceptance rates. Churn Prevention metrics dashboard

​
Export churn feedback

To export the reasons and feedback customers submitted during cancellation and pause requests:
  1. In your Firmhouse project, go to Analytics > Reports.
  2. Open Churn feedback.
  3. Set Created after and Created before to choose the reporting period.
  4. Under Request type, select cancellation, pause, or both. Both request types are selected by default.
  5. Choose the fields to include and click Generate report.
The flow field identifies whether each exported row came from a cancellation or pause request. Only completed requests are included. When Pause Reasons and Winback Offers is not enabled, this report is named Cancellation feedback and only includes cancellations. The Request type filter and flow field are available after enabling pause reasons.