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

# 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

All conditions on one offer must match. 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.

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

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](/configure/activation-and-cancellation/cancellation-feedback-prevention).

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

```liquid theme={null}
{% 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](/configure/workflows/workflow-builder#use-promotional-offers-in-workflows) 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](/customer-portal-v2/components/dashboard-template#promotional_offer) 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.