Skip to main content
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. To let customers accept an offer after initially declining it, select Allow customers to reconsider declined offers. The offer remains available only while the customer is eligible and the acceptance window is open.
  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 Customer Portal → Churn prevention (or Settings → Churn prevention for the legacy portal). 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. When Allow customers to reconsider declined offers is selected, customers can open the same eligible offer again and accept it before its acceptance window closes. 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.
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.

​
Find customers by offer interaction

On Offers, click an offer’s issued, accepted, or declined subscription count to open the matching Customers list. Each count represents distinct subscriptions: a subscription that received the same offer several times appears once in that list. You can also open Customers and add these filters:
  1. Offer: Choose the offer, including an archived offer with history.
  2. Offer interaction: Choose Issued, Accepted, or Declined. Selecting only an offer defaults to Issued.
  3. Offer interaction date: Optionally choose when the interaction happened. The dates include the whole selected day in Firmhouse’s Amsterdam timezone.
Accepted means the offer was successfully accepted. Declined also includes choosing another action during cancellation; it does not include expiry, leaving the page, or an offer cancelled by the system. Issued means an offer instance was saved, not that an email was delivered or the customer saw it. These filters use historical interactions across all revisions of the offer. A customer who accepted and later cancelled remains in the accepted group. Add a subscription status filter to inspect their current status. A subscription can appear in both accepted and declined groups if it received separate offers. Use the existing customer export or save the filters as a view. Saved views run the filters again when opened. Fixed dates keep the same historical period; a preset such as This month moves with the calendar. Customer rows represent subscriptions, so a person with several subscriptions may have several rows.

​
Analyze the group with Claude or Oppy

Connect your agent to Firmhouse MCP, then ask:
Find subscriptions that accepted [offer name] between September 1 and September 30. Show their orders after acceptance and their current subscription status. For repeat acceptances, use the first acceptance in that period as the starting point and state that choice.
The GraphQL API provides offerDefinitions to find the offer, subscriptions for distinct subscriptions, and promotionalOffers for the matching offer instances and timestamps. Both connections accept offerDefinitionId, offerEvent, offerEventSince, and offerEventUntil as direct filter arguments. Queries do not issue offers or require tags. Use the same offer filters for the subscription list and offer history, and paginate both connections. The API event REJECTED corresponds to Declined in the admin. Selecting only offerDefinitionId includes all issued offers, regardless of their current status. Event filters require an offer definition, and date filters require an explicit offerEvent. To retrieve issued-offer history without selecting a particular event or offer, query promotionalOffers without offer filters; optionally use subscriptionId to restrict it to one subscription. For example, after finding the offer ID:
API date ranges include the start and exclude the end. Subscription results count subscriptions; offer history results count individual offer instances. The customer admin lists completed signups and customers pending completion; the API defaults to all non-draft subscriptions, so these populations can differ for incomplete signups. Group by subscriptionAccountId only when you want account-level analysis instead of subscription-level analysis. Recorded viewedAt timestamps and the API’s VIEWED filter have incomplete historical coverage. Some portal offers can be displayed without a saved offer record. An absent view timestamp does not prove the customer never saw the offer, and an issued count is not a shown count.

​
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.