Promotional offers

Configure targeted offers that customers can accept during cancellation, from Customer Portal v2, or through a secure link sent by a workflow.

Promotional offers let you define a reusable retention or loyalty offer, choose which subscriptions qualify, and control what happens when a customer accepts it. Firmhouse saves the exact copy, benefit, and commitment shown to each customer, so later edits apply only to newly issued offers.

Enable promotional offers

Promotional offers are part of the Workflow Builder preview.

1. In your Firmhouse project, open New Features.
2. Enable Workflow Builder.
3. Open Offers from the sidebar.

Projects without this preview enabled cannot open offer-management pages, show promotional offers, or issue them through GraphQL.

Create an offer

1. Open Offers and select New offer.
2. Enter an internal name and choose whether the offer is a draft, active, or archived.
3. Set its priority and acceptance window.
4. Add the customer-facing headline, explanation, and benefit summary for every language enabled on the project.
5. Add any eligibility conditions.
6. Choose one benefit and, optionally, a minimum term.
7. Save the offer and make it active when it is ready for customers.

Draft and archived offers are not issued. When several active offers match, Firmhouse uses their priority to select the first eligible offer.

Choose who qualifies

You can target an offer using:

• Cancellation reason
• Subscription status
• Number of completed deliveries
• Revenue for the current subscription
• Current plan
• Current products
• Synchronized subscription segments
• Shopify order tags

For each condition, choose Require this condition to match or Exclude when this condition matches. Customers must meet every required condition. Matching any exclusion makes them ineligible. Create separate prioritized offers when you want to address alternative audiences. The segment condition is available only when the project has synchronized subscription segments.

Firmhouse checks eligibility again when the customer accepts. An expired offer or one that no longer applies cannot grant its benefit.

Exclude subscriptions from an offer

In the Eligibility tab, add a condition and choose Exclude when this condition matches:

• Exclude a prepaid plan: Choose Current plan, then select the prepaid plan under Plan is. Add a separate exclusion for each plan. New prepaid plans are not excluded automatically.
• Exclude subscriptions that already have a product: Choose Current products, select Has any of, and choose the products. Having any selected product active on the subscription makes it ineligible.

The exclusion applies to the complete rule. For example, excluding Current products → Has none of makes subscriptions without those products ineligible. To exclude subscriptions that have the products, use Has any of with the exclusion choice, or keep Has none of as a required condition.

Issued offers keep the conditions saved when they were issued. Editing an offer’s conditions generally affects newly issued offers only, but changing a cancellation-reason condition can also make an issued cancellation offer unavailable. Saved conditions are checked against the subscription’s current state, so switching to an excluded plan or adding an excluded product can make an issued offer unavailable.

An excluded Cancellation reason allows the offer for other cancellation reasons. Offers with a cancellation-reason condition remain limited to cancellation flows; they do not appear in the regular portal where no cancellation reason exists.

Target subscriptions using Shopify order tags

Choose Shopify order tags as a condition, then search and select one or more tags in the dropdown. The choices come from Shopify tags synchronized to this project’s orders. For example, select SUMMER_SALE to target subscriptions with an order carrying that campaign tag. Tags already saved on the offer remain selected even if they no longer appear on an order.

A subscription qualifies when any of its orders has any of the entered tags. Tags match exactly, including capitalization. Orders from another subscription do not qualify it, even when both subscriptions use the same email address.

Firmhouse synchronizes tags from Shopify when an order is linked and when Shopify sends an order update. Removing a tag can make the offer unavailable, including for a link sent earlier. Previously linked orders need their tags synchronized before they can qualify; contact Firmhouse if historical campaign orders are missing tags.

For a campaign shown only in the second-order reminder, use the order number to control the email block. Add an order-count condition to the offer only if acceptance should also stop after that order.

Choose the benefit

Each active offer has one benefit:

• Apply an existing active promotion
• Add a complimentary one-off product
• Swap a current product
• Switch to another plan in the same plan group

You can also add a minimum term in days, weeks, months, or years. Customers see this commitment before accepting. Products added as complimentary gifts keep their price and quantity locked.

Show offers during cancellation

After a customer selects a cancellation reason, Firmhouse can show the first matching promotional offer before the normal churn-prevention action. The customer can accept or decline the offer, or choose the existing pause, skip, postponement, discount, or cancellation option shown with it.

In the offer editor’s Eligibility tab, add a Cancellation reason condition to show an offer during cancellation for that reason. The selected reason shows its configured alternative action and an Edit cancellation reason link. Offers without a cancellation-reason condition are not shown during cancellation.

You can also start from Settings → Churn prevention. Open a reason, check Create an offer for this reason, and choose Save and create offer to open a draft with that reason preselected. Save the offer to return to the reason. Existing offers can be edited from the same reason screen.

Only active, automatic offers are selected automatically during cancellation. Draft, archived, and manual offers are not. Inactive or deleted cancellation reasons cannot be selected by customers, and pause-flow reasons do not trigger promotional offers.

The reason’s Alternative action is independent of offer eligibility. Pause or skip remains available alongside an eligible promotional offer and when the offer is unavailable or declined. Continue to cancellation adds no pause or skip alternative; it does not prevent a promotional offer from appearing.

Accepted offers apply their configured benefit and optional minimum term, and record the churn request as prevented. Declining returns the customer to the normal cancellation flow.

For the surrounding cancellation setup, see Cancellation feedback and winback flows.

Share an offer outside cancellation

Workflow Builder and the GraphQL API can issue a customer-specific offer and return its plain acceptance URL. In a Liquid email or notification, pipe that URL through ssc_hotlink before sending it to a customer. Configure the project’s public URL before sending offer links.

{% assign offer_url = "{{ steps.issue_offer.createPromotionalOffer.promotionalOffer.acceptUrl }}" %}
<a href="{{ offer_url | ssc_hotlink }}">Review your offer</a>

Opening the signed link authenticates the customer for that subscription with limited hotlink access. Customers who already have full Customer Portal access can also open the offer from their dashboard. An unsigned offer URL redirects to Customer Portal login. Accepting requires an explicit confirmation, so an email link scanner cannot accept the offer automatically. Reusing the same idempotency key returns the same issued offer instead of creating a duplicate.

See Workflow Builder for the workflow setup.

Show offers in Customer Portal v2

The default Customer Portal v2 dashboard shows the highest-priority pending eligible offer. Custom dashboard templates can use {% promotional_offer %} or loop over subscription.eligible_promotional_offers.

See the dashboard template reference for Liquid examples.

Review issued offers

Open a subscription in Firmhouse to review its issued promotional offers and their current status. An issued offer records whether it was viewed, accepted, rejected, or expired.

Troubleshooting

• Offers is missing from the sidebar: Enable Workflow Builder under New Features.
• No offer is shown: Confirm that the offer is active, has not expired, and that every condition and selected benefit applies to the subscription.
• A segment condition is unavailable: Confirm that subscription segments have been synchronized for the project.
• An offer hotlink cannot be created: Configure the project’s public URL, ensure the issuing project has Workflow Builder enabled, and apply ssc_hotlink to the returned acceptance URL in Liquid.