Dashboard template - Firmhouse Docs

dashboard.liquid tags are grouped by default vs optional usage.

Default components are already present in the shipped dashboard.liquid template.
Optional components can be added or used to replace parts of the default layout.

Common tags are documented on Common tags: {% legacy_navbar %}.

Default components

Pause and resume actions

The default dashboard.liquid template includes pause or resume action links when subscription pausing is enabled for the project and the current subscription state allows the action. Use the same conditions in custom templates:

{% if project.self_service_center_subscription_pausing_enabled and subscription.allowed_to_pause? %}
  <a href="{{ subscription.pause_subscription_url }}">
    {{ "dashboard.pause_subscription" | t: default: "Pause subscription" }}
  </a>
{% endif %}

{% if project.self_service_center_subscription_pausing_enabled and subscription.allowed_to_resume? %}
  <a href="{{ subscription.resume_subscription_url }}">
    {{ "dashboard.resume_subscription" | t: default: "Resume subscription" }}
  </a>
{% endif %}

The action pages use the existing Customer Portal pause and resume confirmation flows.

`{% subscription_pause_resume_banner %}`

Block-style pause or resume callout. The default dashboard.liquid template includes this tag near the top of the dashboard for paused subscriptions, and below the shipment/frequency controls for active subscriptions. It renders when subscription pausing is enabled for the project and the current subscription can be paused or resumed. Active subscriptions show pause copy and a pause button. Paused subscriptions show paused-state copy and a resume button.

Parameter	Type	Default
`pause_title`	String	`"Pause your subscription"`
`pause_message`	String	Dashboard pause hint translation
`pause_button_text`	String	`"Pause subscription"`
`resume_title`	String	`"Paused"`
`resume_message`	String	Dashboard resume hint translation
`resume_button_text`	String	`"Resume subscription"`
`show_title`	Boolean	`true`

{% subscription_pause_resume_banner %}

{% subscription_pause_resume_banner pause_title: "Need a break?" pause_message: "Pause deliveries until you are ready again." %}

`{% subscription_reactivation_banner %}`

Lets customers restart a cancelled subscription from Customer Portal v2. It appears only for cancelled subscriptions when Customer Portal Subscription Reactivation is enabled in New Features. The current default dashboard.liquid template already includes this component. If your project uses a customized dashboard template, add the tag where customers should see the reactivation form:

{% if subscription.status == "cancelled" %}
  {% subscription_reactivation_banner %}
{% endif %}

The component supports optional customer-facing text:

Parameter	Type	Default
`title`	String	`"Restart your subscription"`
`message`	String	`"Continue receiving orders by reactivating this subscription."`
`button_text`	String	`"Reactivate subscription"`
`button_classes`	String	Default Customer Portal primary button classes

{% subscription_reactivation_banner title: "Welcome back" button_text: "Restart deliveries" button_classes: "rounded-lg bg-green-700 px-5 py-3 text-white" %}

For subscriptions with a flexible billing cycle or one shipment frequency for all products, customers must select the next billing date before reactivating. Plan-based subscriptions can use today, except Shopify subscriptions. Order-based and Shopify subscriptions can use tomorrow at the earliest. Plan-based projects also explain that the charge is created during the night following the selected date. After a successful reactivation, Firmhouse restores the subscription and clears its cancellation date. If the subscription cannot be reactivated, the customer stays on the dashboard and sees the reason. The default dashboard.liquid template includes a ReferralCandy banner when subscription.referral_candy.url is available for the current subscription. The default banner:

Links More info to the customer’s ReferralCandy invite page (subscription.referral_candy.url)
Copies the customer’s ReferralCandy invite link from subscription.referral_candy.url
Shows the configured advocate reward discount from subscription.referral_candy.advocate_reward_discount when Firmhouse can resolve a valid reward for the subscription
Falls back to a generic translated message when the reward discount is unavailable

If you replace the default dashboard layout, add your own ReferralCandy block if you still want customers to see their personal referral link. subscription.referral_candy.url is only available when Firmhouse can fetch an invite link from ReferralCandy for the subscription. If the ReferralCandy campaign is stopped, paused, or configured in a way that prevents invite links from being created, the value is blank and the default banner stays hidden.

{% assign referral_candy_url = subscription.referral_candy.url %}
{% if referral_candy_url %}
  {% assign reward_discount = subscription.referral_candy.advocate_reward_discount %}

  {% if reward_discount %}
    {{ "dashboard.referral_candy_banner.message_with_discount" | t: discount: reward_discount }}
  {% else %}
    {{ "dashboard.referral_candy_banner.message" | t }}
  {% endif %}
{% endif %}

`{% prepaid_renewal %}`

Prepaid renewal notice and call to action. The default dashboard.liquid template includes this tag. It renders a renewal block for prepaid subscriptions when the renewal date is coming up and the prepaid subscription was created from a regular subscription through a prepaid upgrade. Customers can open the renewal options page from this block. On that page, they can keep renewing prepaid, switch back to the original regular billing subscription, or update the renewal payment date without changing their renewal option.

{% prepaid_renewal %}

<div id="sscv2_prepaid_renewal">
  <h3>Prepaid renewal coming up</h3>
  <p>Your prepaid subscription will renew on March 12, 2026</p>
  <a href="/self-service/subscription/prepaid_renewal/new">Choose renewal option</a>
</div>

`{% simple_next_billing_date_with_confirm %}`

Inline editable next billing date control.

Parameter	Type	Default
`show_label`	Boolean	`false`

{% simple_next_billing_date_with_confirm show_label: true %}

<span id="subscription_123_simple_next_billing_date_with_confirm">
  <span class="text-sm">Next order date</span>
  <span class="font-semibold">March 12, 2026</span>
</span>

`{% simple_plan_switch_with_confirm %}`

Inline plan switch select with confirmation modal.

Parameter	Type	Default
`label_format`	String (`"frequency"`, `"plan_name"`, `"both"`)	`"frequency"`

{% simple_plan_switch_with_confirm label_format: "plan_name" %}

<div id="subscription_123_simple_plan_switch_with_confirm">
  <select name="plan_switch[plan_id]">
    <option value="12" selected>Basic Plan</option>
    <option value="13">Premium Plan</option>
  </select>
</div>

Using label_format: "both" combines plan name and frequency:

<option value="12" selected>Basic Plan - Every 2 weeks</option>

`{% manage_products %}`

Primary CTA to manage existing products.

Parameter	Type	Default
`size`	String (`"small"`/`"large"`)	`"small"`
`button_text`	String	`"Manage products"`

{% manage_products size: "small" %}

<div data-role="manage_products">
  <a id="sscv2_manage_products" href="/self-service/additions/edit" class="button">
    Manage products
  </a>
</div>

`{% product_quantity_progress %}`

Progress and status widget for plan-based product quantity rules. This component only renders when the active plan has a minimum and/or maximum product quantity configured.
The default dashboard.liquid already includes this tag, and you can move or add it elsewhere in the template.

Parameter	Type	Default
`rail_background_color`	String (CSS color)	`#E5E7EB`
`rail_fill_color`	String (CSS color)	`nil` (auto based on state)
`ready_fill_color`	String (CSS color)	`#16A34A`
`pending_fill_color`	String (CSS color)	`#F59E0B`
`over_limit_fill_color`	String (CSS color)	`#EF4444`

Sample scenarios:

{% product_quantity_progress %}

{% product_quantity_progress rail_background_color: "#F3F4F6", ready_fill_color: "#16A34A", pending_fill_color: "#F59E0B", over_limit_fill_color: "#EF4444" %}

{% product_quantity_progress rail_background_color: "#E2E8F0", rail_fill_color: "#0EA5E9" %}

<div id="sscv2_product_quantity_progress" class="bg-white border rounded-xl p-6">
  <h2>Add 2 more items to receive your upcoming order</h2>
  <p>3 / 5+</p>
  <div class="h-4 rounded-full" style="background-color: #E5E7EB;">
    <div style="width: 60%; background-color: #F59E0B;"></div>
  </div>
</div>

`{% product_listing %}`

Main list of active ordered products.

Parameter	Type	Default
`show_delete_button`	Boolean	`true`
`show_quantity_selector`	Boolean	`true`
`show_swap_button`	Boolean	`true`

{% product_listing show_quantity_selector: false %}

<div id="sscv2_product_listing" class="divide-y">
  <div id="ordered_product_501_sscv2" class="py-6">
    <h3 class="font-medium">Protein Bar Box</h3>
    <p class="text-sm">Quantity: 2</p>
    <button type="button">Delete</button>
  </div>
</div>

`{% product_listing_filtered %}`

Filtered list of active ordered products. Use this tag when you want to split the dashboard product list into separate groups. If you do not pass a filter parameter, it renders the same active ordered products as the regular listing.

Parameter	Type	Default
`shipment_schedule`	String (`"recurring"`/`"one_time_purchase"`)	`nil`
`filter_by`	String	`nil`
`filter_value`	String	`nil`
`title`	String	`nil`
`show_add_button`	Boolean	`false`
`show_delete_button`	Boolean	`true`
`show_quantity_selector`	Boolean	`true`
`show_swap_button`	Boolean	`true`
`show_replacement_button`	Boolean	`false`
`hide_replacement_price`	Boolean	`false`
`show_empty_state`	Boolean	`false`

shipment_schedule groups products by shipment schedule:

"recurring" shows products that ship more than once.
"one_time_purchase" shows products where the effective interval is only_once.

The filter is optional and only applies when shipment_schedule is passed.

{% product_listing_filtered shipment_schedule: "recurring", title: "Subscription products" %}
{% product_listing_filtered shipment_schedule: "one_time_purchase", title: "One-time products" %}

You can combine shipment_schedule with a metadata filter:

{% product_listing_filtered shipment_schedule: "recurring", filter_by: "group", filter_value: "Meals", title: "Recurring meals" %}

Set show_replacement_button: true when customers should be able to replace products from that list. Replacement flows only swap the selected product and keep the existing ordered product quantity. Use hide_replacement_price: true when the replacement catalog and confirmation page should not show replacement prices.

{% product_listing_filtered shipment_schedule: "recurring", title: "Subscription products", show_replacement_button: true, hide_replacement_price: true %}

<section class="bg-white border rounded-xl p-4">
  <header class="flex justify-between items-center mb-4">
    <h2 class="text-lg font-semibold text-gray-900">Subscription products</h2>
  </header>
  <div class="divide-y">
    <div class="py-4">1x Tomato Soup</div>
    <div class="py-4">2x Wholegrain Bread</div>
  </div>
</section>

`{% next_order_price_overview %}`

Core upcoming-order summary card.

Parameter	Type	Default
`items`	String or Array	`recurring_subtotal,one_time_subtotal,discount,shipping,total`
`show_discount_code_entry`	Boolean	`true`

When show_discount_code_entry is enabled, the component shows a discount code field below the order summary. Customers can enter an active Firmhouse discount code and apply it to their subscription. After a valid code is applied, the upcoming order totals refresh automatically.

Enable discount code entry

Turn on Discount Codes in Customer Portal v2 in New Features for the project. The default Customer Portal v2 dashboard currently renders this component with show_discount_code_entry: false. Remove that parameter or set it to true in your custom dashboard.liquid template if customers should be able to apply discount codes from the portal. Firmhouse only shows the discount code field when the subscription does not already have an active promotion that blocks manual discount codes. Accepted discount codes must meet these conditions:

The discount code is active and has not reached its usage limit.
The linked promotion is active and available for the customer’s country.
The subscription has no active manual discount, including a promotion that was applied by another discount code.
Any active automatic discount on the subscription allows combining with manual discounts. In the discount settings, enable Allow this automatic discount to be combined with manual discounts.
The code is not a referral discount code. Referral codes are intended for new customer signup and first-order discounts, not recurring orders for existing customers.
For Shopify subscription contracts, the promotion should have simple rules to be synced to Shopify as a subscription contract discount. Codes for more complex Firmhouse-only advanced promotion rules are not supported yet.

If a subscription has an active manual discount, or an active automatic discount that does not allow combining with manual discounts, the discount code field stays hidden. Submitted discount codes are rejected with the existing active-discount message in the same situations. When one promotion with a public description is active on the subscription, the discount row shows that public description. When multiple promotions are active, or the active promotion has no public description, the row keeps the generic discount label. To control the customer-facing discount text, go to Discounts, open the order or billing cycle discount, and fill in Public description. Use wording that makes sense to customers, such as “10% off your next 2 orders”.

{% next_order_price_overview items: "recurring_subtotal,shipping,total" show_discount_code_entry: false %}

<div id="subscription_123_next_order_price_overview" class="border rounded-xl p-6">
  <h3>Order summary</h3>
  <div class="flex justify-between"><span>Recurring subtotal</span><span>EUR 29.00</span></div>
  <div class="flex justify-between"><span>Shipping</span><span>Free</span></div>
  <div class="flex justify-between font-semibold"><span>Total</span><span>EUR 29.00</span></div>
</div>

To show the discount code entry:

{% next_order_price_overview show_discount_code_entry: true %}

`{% minimum_order_amount_warning %}`

Warning shown when the next order preview does not meet the project’s minimum order amount. The default dashboard.liquid template includes this tag before the product list. It renders a warning only when all of these conditions are true:

The project is a dynamic subscription project.
The subscription is active.
Firmhouse can calculate the next order preview.
The next order subtotal before shipping and discounts is below the configured minimum order amount for the subscription country.

When customers add, remove, or update products from Customer Portal v2, the warning refreshes automatically together with the order summary.

{% minimum_order_amount_warning %}

<div id="minimum_order_amount_warning_subscription_123">
  <div class="rounded-xl border border-amber-300 bg-amber-50 p-4">
    <p>The minimum order amount is EUR 35.00</p>
    <p>Your next expected order's subtotal before shipping and discounts is EUR 29.00 and is lower than the required minimum order amount.</p>
  </div>
</div>

The component uses the minimum order amount configured in Settings > Subscription. If you use country-specific minimum order amounts, Firmhouse uses the amount for the subscription’s country.

`{% add_product %}`

Secondary CTA to browse catalog and add products.

Parameter	Type	Default
`size`	String (`"small"`/`"large"`)	`"large"`
`button_text`	String	`"Add product"` (`size: "large"`), `"Add products"` (`size: "small"`)

{% add_product size: "small" button_text: "Add meal" %}

<div data-role="add_product">
  <a id="sscv2_add_product" href="/self-service/additions/new" class="button">
    Add meal
  </a>
</div>

Optional components

`{% asset_purchase_offers %}`

Shows every asset on the subscription that the customer is currently eligible to purchase. The component renders nothing when no purchase offers are available. This component has no parameters.

{% asset_purchase_offers %}

<div id="sscv2_asset_purchase_offers_subscription_123" class="space-y-3">
  <form action="/self-service/asset-ownerships/456/offers" method="post">
    <button id="sscv2_asset_purchase_offer_asset_ownership_456" type="submit">
      <span>Buy your Coffee Machine</span>
      <span>Buy now</span>
    </button>
  </form>
</div>

`{% asset_purchase_offer %}`

Renders one asset purchase offer from an asset ownership Liquid object. Prefer asset_purchase_offers when Firmhouse should find and render every eligible offer automatically.

Parameter	Type	Default
`asset_ownership`	Asset ownership Liquid object	`nil`
`blocked_by_outstanding_invoices`	Boolean	`false`

{% for asset_ownership in subscription.asset_ownerships %}
  {% asset_purchase_offer asset_ownership: asset_ownership, blocked_by_outstanding_invoices: false %}
{% endfor %}

<form action="/self-service/asset-ownerships/456/offers" method="post">
  <button id="sscv2_asset_purchase_offer_asset_ownership_456" type="submit">
    <span>Buy your Coffee Machine</span>
    <span>Buy now</span>
  </button>
</form>

`{% non_paying_banner %}`

Displays an account warning when the subscription is marked as non-paying. It renders nothing for subscriptions in good payment standing.

Parameter	Type	Default
`title`	String	Translated default title
`message`	String	Translated default message
`paused_orders_message`	String	Translated paused-orders message
`view_invoices_label`	String	Translated invoices link label
`render_icon`	Boolean	`true`

{% non_paying_banner title: "Payment needed" render_icon: true %}

<div id="sscv2_non_paying_banner" class="rounded-xl border border-red-200 bg-red-50 px-5 py-4">
  <p class="text-sm font-semibold text-red-900">Payment needed</p>
  <p class="mt-1 text-sm text-red-800">Please resolve the outstanding payment.</p>
  <a href="/self-service/invoices">View invoices</a>
</div>

`{% latest_orders %}`

Recent orders list.

Parameter	Type	Default
`limit`	Number	`3`

{% latest_orders limit: 2 %}

<div id="sscv2_latest_orders">
  <article class="border rounded-xl p-4">
    <p class="text-xs">Jan 12, 2026 | Order #9876</p>
    <p class="text-sm font-semibold">2x Matcha Pods</p>
    <span class="pill pill--green">confirmed</span>
  </article>
</div>

`{% next_order_preview %}`

Upcoming order preview card.

{% next_order_preview %}

<div class="bg-white border rounded-xl p-4">
  <p class="text-sm font-semibold">Upcoming order</p>
  <p class="text-sm">Scheduled for March 12, 2026</p>
  <div class="flex justify-between mt-2">
    <span>2x Oat Drink</span>
    <span>EUR 14.00</span>
  </div>
</div>

Advanced `product_listing_filtered` patterns

Filtered product list card (for segmented subscriptions).

Parameter	Type	Default
`filter_by`	String	`nil`
`filter_value`	String	`nil`
`title`	String	`nil`
`show_add_button`	Boolean	`false`
`add_button_text`	String	`nil`
`show_manage_button`	Boolean	`false`
`manage_button_text`	String	`nil`
`title_class`	String	`"text-gray-900"`
`show_delete_button`	Boolean	`true`
`show_quantity_selector`	Boolean	`true`
`show_swap_button`	Boolean	`true`
`show_replacement_button`	Boolean	`false`
`hide_replacement_price`	Boolean	`false`
`show_empty_state`	Boolean	`false`

{% product_listing_filtered filter_by: "person" filter_value: "mom" title: "Menu for mom" show_manage_button: true %}
{% product_listing_filtered filter_by: "person" filter_value: "mom" title: "Menu for mom" title_class: "text-green-800" %}

When show_replacement_button is enabled, customers can replace products in that filtered list. Replacement keeps the current ordered product quantity. Set hide_replacement_price: true if replacement prices should stay hidden in the catalog and confirmation step.

<section class="bg-white border rounded-xl p-4">
  <header class="flex justify-between items-center mb-4">
    <h2 class="text-lg font-semibold text-gray-900">Menu for mom</h2>
    <a id="sscv2_manage_products" href="/self-service/additions/edit">Manage products</a>
  </header>
  <div class="divide-y">
    <div class="py-4">1x Tomato Soup</div>
    <div class="py-4">2x Wholegrain Bread</div>
  </div>
</section>

Dynamic groups based on ordered product metadata

If your filter_value should adapt to subscriber-specific metadata (for example names like "Veronika" or "Michiel"), you can build the group list from subscription.ordered_products and then render product_listing_filtered in a loop.

How are dynamic values fetched?

You can do this directly in dashboard.liquid; no custom backend endpoint is required.

subscription.ordered_products is available in SSCv2 Liquid context.
Each ordered_product includes metadata.
Reading ordered_product.metadata.group gives the current subscription’s group value for that ordered product (or use ordered_product.metadata.person if your project still uses the legacy key).
Pass filter_by with the same metadata key (group or person) that produced the value.
Looping over ordered products lets you discover all group values present on the active subscription at render time.

So the template itself can fetch values for the current subscription and render sections dynamically. If you need a list of possible groups that are not yet present on the subscription (for example, a global project-wide list), that is not available from this template context alone and should be handled outside the template (for example by pre-populating metadata values via your own flows). In this pattern:

hardcoded sections stay explicit (Add-ons, Gifts, One-time extras)
dynamic sections include only metadata values currently present on the subscription
hardcoded values are excluded from the dynamic loop
exclusions and de-duplication are done case-insensitively (downcase)

{% assign excluded_groups_normalized = "add-ons|gifts|one-time extras" | split: "|" %}
{% assign seen_groups_normalized = "" %}

{% for ordered_product in subscription.ordered_products %}
  {% assign group_name = ordered_product.metadata.group | strip %}
  {% assign group_filter_key = "group" %}
  {% if group_name == blank %}
    {% assign group_name = ordered_product.metadata.person | strip %}
    {% assign group_filter_key = "person" %}
  {% endif %}
  {% assign normalized_group_name = group_name | strip | downcase %}

  {% if group_name != blank %}
    {% unless excluded_groups_normalized contains normalized_group_name %}
      {% capture marker %}|{{ normalized_group_name }}|{% endcapture %}

      {% unless seen_groups_normalized contains marker %}
        {% capture seen_groups_normalized %}{{ seen_groups_normalized }}{{ marker }}{% endcapture %}
        {% assign group_title = group_name | capitalize %}

        {% product_listing_filtered
        filter_by: group_filter_key,
        filter_value: group_name,
        title: group_title,
        show_add_button: true,
        show_manage_button: false,
        show_delete_button: false,
        show_quantity_selector: false,
        show_swap_button: false
      %}
      {% endunless %}
    {% endunless %}
  {% endif %}
{% endfor %}

{% product_listing_filtered filter_by: "group", filter_value: "Add-ons", title: "Add-ons", show_add_button: true, show_manage_button: false, show_delete_button: false, show_quantity_selector: false, show_swap_button: false %}
{% product_listing_filtered filter_by: "group", filter_value: "Gifts", title: "Gifts", show_add_button: true, show_manage_button: false, show_delete_button: false, show_quantity_selector: false, show_swap_button: false %}
{% product_listing_filtered filter_by: "group", filter_value: "One-time extras", title: "One-time extras", show_add_button: false, show_manage_button: false, show_delete_button: false, show_quantity_selector: false, show_swap_button: false %}

If your project stores group values under a different metadata key, replace ordered_product.metadata.group (and optional ordered_product.metadata.person fallback) with your key and pass that same key to filter_by.

Shopify instalment progress from ordered products

If your Shopify subscription setup uses instalment billing, you can render progress directly from the ordered products in dashboard.liquid.

ordered_product.instalment_current_number returns the current instalment number for that subscription line.
ordered_product.instalment_total_count returns the total instalment count from the subscription’s active plan.
subscription.active_plan.instalments is also available when you want to render plan-level instalment details outside the ordered product loop.

Example:

{% if subscription.active_plan.instalments %}
  <div class="space-y-3">
    {% for ordered_product in subscription.ordered_products %}
      {% assign instalment_number = ordered_product.instalment_current_number | plus: 0 %}
      {% if instalment_number > 0 %}
        <div class="rounded-xl border border-gray-200 p-4">
          <p class="text-sm font-medium">{{ ordered_product.localized_title }}</p>
          <p class="text-sm text-gray-600">
            Instalment {{ instalment_number }} of {{ ordered_product.instalment_total_count }}
          </p>
        </div>
      {% endif %}
    {% endfor %}
  </div>
{% endif %}

`{% next_shipment_date %}`

Localized next shipment date text.

{% next_shipment_date %}

Next shipment on March 12, 2026

`{% minimum_contract_duration %}`

Commitment/contract duration block.

Parameter	Type	Default
`variant`	String (`"full"`, `"label"`, `"date"`)	`"full"`

{% minimum_contract_duration variant: "label" %}

<span id="subscription_123_minimum_contract_duration_label">
  Committed until April 1, 2026
</span>

`{% billing_and_shipping_breakdown %}`

Billing interval breakdown text.

{% billing_and_shipping_breakdown %}

<span id="subscription_123_billing_and_shipping_breakdown">
  Monthly billing, weekly delivery
</span>

​Default components

​Pause and resume actions

​{% subscription_pause_resume_banner %}

​{% subscription_reactivation_banner %}

​ReferralCandy banner

​{% prepaid_renewal %}

​{% simple_next_billing_date_with_confirm %}

​{% simple_plan_switch_with_confirm %}

​{% manage_products %}

​{% product_quantity_progress %}

​{% product_listing %}

​{% product_listing_filtered %}

​{% next_order_price_overview %}

​Enable discount code entry

​{% minimum_order_amount_warning %}

​{% add_product %}

​Optional components

​{% asset_purchase_offers %}

​{% asset_purchase_offer %}

​{% non_paying_banner %}

​{% latest_orders %}

​{% next_order_preview %}

​Advanced product_listing_filtered patterns

​Dynamic groups based on ordered product metadata

​How are dynamic values fetched?

​Shopify instalment progress from ordered products

​{% next_shipment_date %}

​{% minimum_contract_duration %}

​{% billing_and_shipping_breakdown %}