> For the complete documentation index, see [llms.txt](https://help.smartrr.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartrr.com/docs/getting-started/implementation/installing-smartrr-on-a-custom-shopify-theme-guided-install.md).
# Installing Smartrr on a custom Shopify theme (Guided Install)
Implementing Smartrr on storefronts with modified Shopify themes or custom liquid themes
{% hint style="info" %}
Coming from our app? [Click here](#guided-install) to skip directly to guided install instructions.
{% endhint %}
{% hint style="warning" %}
**Note:** Before implementing Smartrr, it's important to [review Shopify's subscription requirements](https://help.shopify.com/en/manual/products/purchase-options/subscriptions/shopify-subscriptions/considerations) to determine your eligibility for offering subscriptions on your storefront. In the linked article, Shopify confirms what payment gateways are supported, and lists all other considerations to keep in mind before offering subscriptions.
{% endhint %}
If your store is using [one of Shopify’s 2.0 free themes](https://themes.shopify.com/themes/dawn/styles/default), and have not [made any customizations your your theme’s source code](https://help.shopify.com/en/manual/online-store/themes/customizing-themes/edit-code/edit-theme-code), you’re eligible for our simple one-click automated install of Smartrr via our in-app Setup page.
{% hint style="info" %}
**Smartrr works with New customer accounts, with one difference:** Smartrr's modern account portal doesn't replace Shopify's account page. Instead, you link customers to it from a menu, in one of two ways:
* **Link the app proxy URL (no theme edits needed).** Add your store's Smartrr proxy URL as a menu item in the New customer accounts menu or your store's main menu. For new installs, the proxy path is `/a/subscriptions/customer-portal`, for example `https://yourstore.com/a/subscriptions/customer-portal`. To confirm your store's path, open Shopify's app settings and find the proxy URL in Smartrr's app details.
* **Render the portal on its own page.** Create a page that displays the portal, then link that page from a menu. [\[See how to set up the Smartrr account portal on its own page →\]](https://relay-commerce.notion.site/How-to-Use-New-Customer-Accounts-public-facing-2a21e0df860a8053a66bd5294384a769)
{% endhint %}
Within the Smartrr app navigate to **Setup** under RESOURCES in the left-hand menu.
## Subscription setup
### 1. Set up a subscription program
Subscription Programs are the heart of the Smartrr app. If you're just getting started with subscriptions, we can create a demo program for you by clicking **Use a demo program**. This will automatically create a "Subscribe & Save 10%" program for your shop.
Alternatively, you can create a new program from scratch by pressing **Create my own program**. You'll be redirected to our Subscription Program tab to complete this step. [Learn more about setting up a Subscription Program here. ](/docs/support/subscription-setup/subscription-programs.md)
### 2. Select subscription products
Now that your Subscription Program is created, your next step is to assign a product/s to this program.
Similarly to above, Smartrr can create a demo product for you if you press **Use a demo product**. This will create a *Smartrr Snack Cookie (Demo)* in your Shopify shop. You can use this demo product for previewing purposes, and will be able to delete it at a later date directly within your Shopify admin.
{% hint style="warning" %}
**Note:** If you select to create a Demo Product, it won't appear in previews or in your storefront until you go to your Shopify admin and set the product sales channel availability to "Online Store".
{% endhint %}
If you want to start with one of the existing products in your shop, press **Select from existing products**. You can select one or multiple products from the modal that appears.
{% hint style="warning" %}
**Note:** We recommend always using [variants](https://help.shopify.com/en/manual/products/variants) for your Shopify products when offering subscriptions, even if there is only one option for your product. Shopify auto-assigns a "Default variant" to a product that does not have any variants associated with it. If you decide to add variants to a product at a later date, and subscriptions are already running with the "Default variant", then those subscriptions will fail and will need to be re-mapped.
{% endhint %}
### *Optional:* Smartrr optimizations
Now that you've completed the required Subscription setup steps, explore the remaining cards on this tab for ways you can further optimize your subscription business:
* [Setup subscription loyalty rewards & referrals](/docs/support/admin-portal/loyalty.md)
* [Create dedicated shipping profiles for subscription purchases](/docs/support/subscription-setup/shipping-methods.md)
* Customize the look and feel of your customer account portal
* [Enable a passwordless login experience](/docs/support/admin-portal/passwordless-login.md)
* [Set rules around failed payment attempts](/docs/support/transactions/failed-payments.md)
* [Integrate with the ecosystem’s best](/docs/support/integrations/available-integrations-with-smartrr.md)
## On-site setup
### 1. Install Smartrr snippets
{% hint style="warning" %}
**Warning:** To prevent Smartrr from showing up on your site before you're ready to launch, we recommend navigating back to Shopify’s Themes to duplicate a copy of your current theme (Actions > Duplicate). Name it something that is easily recognizable, such as **\[Your Store] Smartrr Integration Copy \[Date]** so that when you modify the below code, you know you are updating the correct theme.
{% endhint %}
Select the Shopify theme you'd like Smartrr snippets to be in stalled on. Smartrr Snippets are files that are injected into your code base and will *not* modify any existing liquid files. These are required in order to render Smartrr on your storefront. There are five files that will be added under the **Snippets** section in your theme's liquid code.
{% hint style="info" %}
Note: If you're planning on using [Smartrr's subscription widget](#2.-add-smartrr-subscription-widget), leave the ***I'm planning on using Smartrr's subscription widget box*** checked. If you're *not* using a liquid Shopify theme compatible with app blocks, *and/or* are planning to manually render subscription options on your shop's PDPs with the assistance of a developer, uncheck this box. \
\
If you're unsure, no worries. You can always duplicate a clean version of your Shopify theme and re-install Smartrr snippets again.
{% endhint %}
### 2. Add Smartrr subscription widget (Guided install)
Smartrr's subscription widget is an app block that can be added to your Default product page from your Shopify theme's online customizer. However, if you're *not* using a liquid Shopify theme compatible with app blocks, *and/or* are planning to manually render subscription options on your shop's PDPs with the assistance of a developer, you'll need to use our guided install process.
#### 1. Modifying the Product Page
In your duplicated theme’s liquid code files, find the liquid file where your site’s product form information is being stored. This is usually called **main-product.liquid** or **product.liquid**. This file is typically located under either the **Sections** (for Online Store 2.0) or **Templates** (for older Shopify themes) heading.
Once you’ve opened the file, search for the product form {%- form 'product'}, paste the following Smartrr snippet inside the form. We typically recommend placing between the variant selector and the quantity selector, but you can place in any order you see fit.
```
{% render 'smartrr-product' %}
```
When added, the product form should look something like this:
Save the file. You should be able to preview Smartrr on your site upon successfully modifying this product form. Having trouble? Skip to [**Troubleshooting**](#troubleshooting) steps.
#### 2. Modifying the Customer Account Page
In your duplicated theme’s code base, find the liquid file for your store’s account page. This is usually called **main-account.liquid** or **customers/account.liquid**. This file is typically located under either the **Templates** heading.
At the very beginning of the file, paste the following snippet:
```
{% render 'smartrr-account' %}
{{ 'customer.css' | asset_url | stylesheet_tag }}
```
The file should look like this:
Save the file.
#### 3. Modifying the Order Status Page
If you would like to display a link to your customer’s Account Portal from the order status page, please email us at and we will assist you.
## Troubleshooting
#### Why don't I see Smartrr on my theme once I preview?
Whether you've created a demo Subscription Program or made a new program from scratch, you may need to double check and make sure your program details have been successfully "saved". To do this, go to **Subscription Programs** > **Manage Program**. Check and see if there is a Discard / Save banner at the top, and click the green **Save** button.
{% hint style="info" %}
Still having trouble installing and don’t have access to a developer? We partner with a handful of excellent agencies. We also offer full white-glove onboarding support with our [Grow and Excel plans.](http://smartrr.com/pricing)
{% endhint %}
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://help.smartrr.com/docs/getting-started/implementation/installing-smartrr-on-a-custom-shopify-theme-guided-install.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
Once you’ve opened the file, search for the product form {%- form 'product'}, paste the following Smartrr snippet inside the form. We typically recommend placing between the variant selector and the quantity selector, but you can place in any order you see fit.
```
{% render 'smartrr-product' %}
```
When added, the product form should look something like this:
