> For the complete documentation index, see [llms.txt](https://docs.roadmap.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roadmap.so/subscriptions/storefront-and-accounts/adding-the-subscription-widget-to-your-product-pages.md).

# Adding the subscription widget to your product pages

Place the Roadmap Product Subscription block on the product templates where customers should see subscribe-and-save options.

The Product Subscription widget shows the subscribe-and-save options on a product page. Adding it is a Shopify theme-editor step, not a Roadmap admin step — Roadmap provides the block, but the theme editor decides which product templates it appears on.

This article walks through adding the block, picking the right templates, and the most common reason a widget doesn't show up where you'd expect.

#### What the widget does at runtime

Roadmap's **Product Subscription** block controls the purchase-option area on the product page — the radio or dropdown that lets customers choose between one-time purchase and subscribe and save `(every X)`. It doesn't replace, restyle, or inject the **Add to Cart** button — that stays whatever your theme provides. Roadmap's block sits cleanly above, or wherever you place it, and feeds the customer's selection into the **Add to Cart** action.

This means a customer flow looks like:

1. Customer lands on a product page.
2. The Roadmap block shows the available frequency options for the plan attached to this product.
3. Customer picks one-time or a frequency. If they pick a frequency, the displayed price reflects the plan's discount.
4. Customer clicks the theme's **Add to Cart** button — the same one that exists for non-subscription products.
5. Cart and checkout proceed normally. Shopify recognizes the subscription selling plan attached.

#### Before you start

* Have at least one subscription plan configured in Roadmap, with the products you want to offer subscriptions for assigned to it. See Subscription plan settings, field by field.
* Open Shopify and identify which product template your subscription products use. Most stores use the default product template, but stores often have multiple, for example `product`, `product.bundle`, and `product.gift-card`. Each template that should show the widget needs the block added separately.

#### Add the block to a product template

{% stepper %}
{% step %}
**Open the theme editor**

In Shopify admin, go to **Online Store → Themes → Customize** on your live theme.
{% endstep %}

{% step %}
**Switch the editor to a product template**

Use the template picker at the top center of the theme editor. Choose **Products → Default product** or whichever template you want to add the widget to.
{% endstep %}

{% step %}
**Add the Product Subscription block**

In the left sidebar, find the area on the product page where the purchase options should appear — typically just above or below the price, before the **Add to Cart** button. Click the **+ Add block** option in that section.

The block picker opens. Switch to the **App** tab. Pick **Product Subscription** — Roadmap's block.

The block drops in. The preview on the right shows the widget rendering using a sample plan.
{% endstep %}

{% step %}
**Keep "configuration from admin"**

The block has a settings panel with two modes: **Use Config From: From Admin** — the default and what most stores want — or per-instance overrides. Leave it on **From Admin** so the widget's labels, frequency display, colors, fonts, and spacing are all driven by your settings in **Roadmap → Subscriptions → Edit Subscription Widget**. Per-instance overrides exist if you have a specific reason to differ on one template, but they make later style changes harder to manage.
{% endstep %}

{% step %}
**Save the theme**

Click **Save** in the top-right of the theme editor.
{% endstep %}

{% step %}
**Verify on the storefront**

Open a product page on your live storefront for a product that's attached to a subscription plan. The widget should now show the available frequency options. If you see the price and **Add to Cart** but no purchase-option block above them, the most likely cause is the template not being the one you edited — see **Troubleshooting**.
{% endstep %}
{% endstepper %}

#### Repeat for every product template that needs subscriptions

If your store has multiple product templates — gift card, bundle, special-edition, and so on — repeat the steps above for each template that should show the widget. Stores often have `2–4` templates, and the widget needs to be added to each one separately.

To check how many templates you have, in the theme editor's template picker click **Products** — every entry under it is a template you may need to add the block to.

#### Editing the widget's appearance

You don't edit the widget's styling from the theme editor — that all lives in Roadmap. To change colors, labels, frequency display — radio versus dropdown — font sizes, spacing, or border radius, go to **Roadmap → Subscriptions** and click **Edit Subscription Widget** in the top-right. See Configuring the Product Page subscription widget for the field-by-field reference.

Changes saved in Roadmap apply to every theme template that uses configuration from admin. You don't need to re-touch the theme editor.

{% hint style="info" %}
For a shared brand base across Roadmap's blocks in one action (colors, border radius, typography, spacing), use the [Universal Styler](/getting-started/how-the-universal-styler-works.md), opened from the top of the Subscriptions page. The Product Subscription widget is joining the Universal Styler shortly; until then its styling lives in **Edit Subscription Widget** as described above.
{% endhint %}

#### Troubleshooting

**The widget isn't appearing on a product page**

The most common cause is the block not being added to the template assigned to that product. Check:

* Open the product in Shopify admin and look at the **Theme template** dropdown in the right rail. Note which template it uses.
* Open the theme editor and switch to that exact template. If the **Product Subscription** block isn't in the layout, add it.
* Confirm the product is on a subscription plan. The widget only renders for products attached to at least one plan — open **Roadmap → Subscriptions → Plans** and check the product is listed in the relevant plan's **Subscription Products**.

**The widget appears but shows no frequencies**

* The plan attached to the product has no delivery frequencies configured. Go to **Roadmap → Subscriptions → Plans → \[the plan]** and add at least one row under **Delivery options & discounts**.

**Frequency option titles are wrong**

Frequency option titles come from the plan, not from the widget editor. To change them, edit the plan in **Roadmap → Subscriptions → Plans → \[the plan]**, and update the **Plan name** column on each frequency row, for example `Delivered every month` or `Delivered every 2 months`.

**The Add to Cart button looks different on subscription products**

It shouldn't — Roadmap doesn't modify **Add to Cart**. If it looks different, the change is happening in your theme. Check whether your theme has any subscription-aware logic that re-styles or relabels the cart button conditionally.

#### Frequently asked questions

<details>

<summary>Do I need to add the widget to non-subscription product templates?</summary>

No. The widget only renders for products attached to a subscription plan. On a product without a plan, the block is silent — but it's still cleaner to keep the block out of templates used only for non-subscription products.

</details>

<details>

<summary>Can I have different widget styling on different product templates?</summary>

Yes — set the block to per-instance overrides on a specific template instead of configuration from admin. The trade-off: when you later update the global widget settings in Roadmap, that template won't pick up the change. Use per-instance only when you have a specific design reason.

</details>

<details>

<summary>Will the widget work in Shopify checkout?</summary>

The widget itself is a product-page component — it doesn't render in checkout. The customer's selection, one-time versus subscription, flows through to checkout via Shopify's selling-plan mechanism, so checkout shows the right pricing and signs the customer up for the subscription on completion. No additional setup is needed for checkout.

</details>

#### Related guides

* Configuring the Product Page subscription widget
* Subscription plan settings, field by field
* Getting started with subscriptions
* [Universal Styler](/getting-started/how-the-universal-styler-works.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.roadmap.so/subscriptions/storefront-and-accounts/adding-the-subscription-widget-to-your-product-pages.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.