> 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/support/subscription-setup/subscription-programs.md).

# Subscription Programs

A Subscription Program is the heart of the Smartrr app. Subscription Programs control which products are available for subscription purchase.

## What is a Subscription Program?

Subscription Plans, products, and variants are objects within a Subscription Program. You may set up one or multiple Subscription Plans per shop. The default behavior of the subscription widget is to display cards for:

* The subscription program/s the product/variant is included in (display can be handled using CSS or JS).
* Plus the one time purchase card.

{% embed url="<https://www.figma.com/file/TtNdGS3WCqpODHuwoUKwY2/Subscription-Programs-%26-Plans?node-id=0%3A1>" %}
Subscription Program's high-level chart: The subscription program packages subscription plans/selling plans and products/variants. Each subscription plan includes the billing policy, delivery frequency and discounts.
{% endembed %}

Two examples for the same store are provided below:&#x20;

* **Example 1:** You would like to offer a discount for customers who elect to subscribe to your product vs. make a one-time purchase.&#x20;
* **Example 2:** You would like to offer a variety-pack product with *only* a monthly subscription cadence, but the individual products within the product are available on both a bi-weekly and monthly cadence.&#x20;

Both above examples are possible to execute within the same storefront by creating multiple Subscription Plans within a Subscription Program.&#x20;

## Creating a Subscription Program

Under Configuration in the left-hand menu, click on **Subscription Programs**. Click on the button **Create program**.

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2F0YkO2QzWdXathyxQeVk4%2FScreenshot%202024-03-26%20at%2008.48.44.png?alt=media&amp;token=4065f7b9-b7c6-474c-8982-03a364b1b37a" alt="&#x22;Create program&#x22; button highlighted on the &#x22;Subscription Programs&#x22; menu in the Smartrr admin portal."><figcaption></figcaption></figure>

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2F0Pwnm40mlXey96uNEheN%2FScreenshot%202024-03-26%20at%2008.49.44.png?alt=media&amp;token=5189e79c-6112-476b-a193-acad6d95f741" alt="View of a blank/new subscription program."><figcaption></figcaption></figure>

First, add all required information to your **Subscription Program**:

* <mark style="color:purple;">**Storefront label:**</mark> Title of the Subscription Program on your product page, ex. “Subscribe & Save 10%”
* <mark style="color:purple;">**Storefront option label:**</mark> Cadence text to display next to plan selector on your product page, ex. “Subscribe & Save 10%'', “Deliver every”, or “Frequency”. Onsite example: ![Display of subscription programs listed on a product page; the product displays only subscription programs that it's included in.](https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FvMBxStLFdJXzQqop4wlH%2FScreenshot%202023-02-27%20at%2008.22.11.png?alt=media\&token=c0b0f137-c4ef-4166-8de4-1e8eba1ed298)
* <mark style="color:purple;">**Admin label:**</mark> *Optional*—if you would like your Subscription Program to have a different name in your Smartrr app

Next, add all required information for each **Subscription Plan** within your **Subscription Program**:&#x20;

* <mark style="color:purple;">**Display:**</mark> Label of the plan frequency selection on the product page, ex. “Every 2 Weeks”. You are able to add multiple selection options. Onsite example: ![Display of the frequency/selling plan dropdown selector in the subscription widget.](https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FuJRx9y7nCBFvj5rdP7pl%2FScreenshot%202023-02-27%20at%2008.22.50.png?alt=media\&token=5371c063-5a35-448b-ab4e-909293e46944)
* <mark style="color:purple;">**Cart & Checkout label:**</mark> Label displayed alongside the product once it’s been added to cart and on the checkout page, ex. “Delivered Every 2 Weeks”. Replace with a "{{H}} " to hide this label from customers.
* <mark style="color:purple;">**Category:**</mark> Shopify [<mark style="color:blue;">requires a category</mark>](https://shopify.dev/docs/api/admin-graphql/2022-07/enums/SellingPlanCategory) to be assigned to each Subscription Program (selling plan). We recommend always leaving this set to "Subscription".&#x20;
* <mark style="color:purple;">**Billing Schedule:**</mark> Indicate the number of intervals between billings as a numerical value (ex. “2”) and the interval type (Days, Weeks, Months, or Years)
* <mark style="color:purple;">**Discount Incentive:**</mark> Percentage or fixed amount discount that a customer receives with this Subscription Plan. You can also opt to change the discount percentage after a certain number of subscription orders.

For advanced subscriptions, the following options are available for merchants on Grow and Excel plans:

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FafK8eWv1VnOS9Bo961CF%2FScreenshot%202023-02-27%20at%2008.28.20.png?alt=media&amp;token=e963ed89-d52c-4a61-8905-80f2a180e5f7" alt="Each selling plan card includes tabs for Prepaid, Max/Min and Anchor settings."><figcaption><p>Advanced Subscription Program settings tabs</p></figcaption></figure>

* <mark style="color:purple;">**Prepaid:**</mark> If applicable, indicate the number of intervals between billings as a numerical value (ex. “2”) and the interval type will set automatically based on the interval type in the plan's Basic details tab.
* <mark style="color:purple;">**Max/Min:**</mark> Used when you'd like a subscription to end after a certain number of billing cycles.
* <mark style="color:purple;">**Anchor:**</mark> Used to set a day on which billing interval calculations should be made. Learn more about anchor dates and why you might use them here

Once all required information has been completed, click **Save.**

{% hint style="danger" %}
**Warning:** To ensure the best experience for your customers, we **don’t recommend** adding or deleting products or variants from a Subscription Program once it’s set up and active in your store. Only delete a product from a Subscription Program if there are no active subscriptions associated with the Subscription Program.

If you change a discount in a Subscription Plan, the discount will only go into effect for **new** subscriptions created. The discount will not be retroactively updated for existing discounts.
{% endhint %}

## Portal Add-ons

Portal add-ons are accessible by the customer via the Account Portal. Customers can add products to their subscription orders as one-time add ons at a discounted price.

To configure add-ons, navigate to **Subscription Programs** and then click on the **Portal Add-ons** tab.

Click on Browse to select one or multiple products/variants to be available to customers as add-ons.

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FvqwQUnk0o0Cvlr6XPHS2%2FScreenshot%202024-03-26%20at%2008.50.38.png?alt=media&amp;token=09984c18-4db1-4ed8-aa48-4348db20455f" alt="Image of the &#x22;Portal Add-ons&#x22; menu page in the Smartrr admin portal."><figcaption></figcaption></figure>

Products that are selected here will be visible to your customers in their account here:&#x20;

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FlHWCjdGpzf44olUY96aD%2FScreenshot%202024-03-26%20at%2008.51.33.png?alt=media&amp;token=fe96ad00-f7a1-492d-8970-bc7c8e241d2a" alt="The products added in the &#x22;Portal Add-ons&#x22; list are shown in the Smartrr account portal, next to the &#x22;Next Order&#x22;/&#x22;Subscriptions&#x22; card."><figcaption></figcaption></figure>

Note: At this time, it's not possible to add different add-ons per subscription program, or to offer different discounts per product in the add-ons section. To stay up-to-date with new features we release, you can follow our [<mark style="color:blue;">changelog</mark>](https://changelog.smartrr.com/?_gl=1*16u52pc*_gcl_au*MTA4NDg0Mjk1OS4xNzAwNDcyMjUw).

Customers can click on an dd on image from within their account to view all images and read the product's description, which pulls from Shopify. <br>

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2F6Vr8MtFufzl3slbVF7Ec%2Fportal-add-on-details.gif?alt=media&amp;token=102dc3d7-deeb-4d24-b2f2-5860827e27de" alt="Gif highlighting the interaction with the portal add-ons in the Smartrr account portal."><figcaption></figcaption></figure>

### How can I add filters to add-ons?

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2F7MaVtDPDDCygOnfQTpKU%2Ffilter-add-on.gif?alt=media&amp;token=5df9fcd1-d2be-4c86-a2f6-b769e4489a61" alt="Display of filters in the &#x22;Portal Add-ons&#x22; cart when enabled. Filters are used to categorize the products that are displayed in the &#x22;Portal Add-ons&#x22; card."><figcaption></figcaption></figure>

If you are a shop with a large add-on offering, it might be helpful to add filters so your customers can easily find what they're looking for. \
\
To setup a filter, go to product's page from within the Shopify Admin and create a new product tag including the Smartrr filter prefix, `SmartrrFilter`: (ex. `SmartrrFilter:Cookie`). Smartrr will pick up on these tags for applicable add-on products and will automatically create filters to include within the Add-ons section.

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FdJG4qWXM2Os53L7yq7n1%2FScreenshot%202024-03-26%20at%2009.01.22.png?alt=media&amp;token=4a2eb9ca-17e8-4279-bce6-11a5e79e35de" alt="The &#x22;Tags&#x22; field shown on the product details page in the Shopify admin portal. To filter products in the Smartrr &#x22;Portal Add-ons&#x22; list, use the &#x22;SmartrrFilter:category&#x22; structure when adding the tag. Example: SmartrrFilter:Gluten-Free."><figcaption></figcaption></figure>

### Subscription Benefits app block

In your Shopify theme customizer, you can add the Smartrr Subscription Beneftis app block to your product pages. This widget will allow you to elaborate to customers the benefits of subscribing and can be fully customized.

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2F5z6bFxrLxBDt06NFa13l%2FApp%20blocks.png?alt=media&amp;token=60798f04-543a-4b79-9d63-b431fa1a6cec" alt="Adding the Subscription Benefits app block to a product page in the theme&#x27;s Customize view."><figcaption><p>Add the app block to the product page inside the Shopify theme customizer</p></figcaption></figure>

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FJCSbbbpopjLLCebwIAuU%2FSubscription%20benefit%20app%20block.png?alt=media&amp;token=056950d0-9e40-46d0-ae14-0704ff79ebba" alt="Fields in the &#x22;Subscription Benefits&#x22; block&#x27;s settings to add a headline and list the benefits that the subscription provides."><figcaption><p>Customize the app block from right in the Shopify theme customizer</p></figcaption></figure>


---

# 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://help.smartrr.com/docs/support/subscription-setup/subscription-programs.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.