Last updated: April 3, 2024

App Installation

From the Shopify app store, install the Smartrr app.

In your Shopify admin ([your-store-name].myshopify.com), navigate to 'Apps'. The Smartrr app should now show on your app list.

Click on the Smartrr app to open. Navigate to the Integrations tab in the left-hand navigation and generate a new API token using the button that reads Add Key.

We recommend setting both your Token Nickname and your Application Name as the name of the platform you are authorizing for. We also recommend that Application Name specifically be in all capital letters, without spaces.

Headless Implementation

Use the below endpoint to call for information about product Subscription Programs.

Call Subscription Program Information

Method 1: Shopify Storefront API

Using Shopify’s Storefront API, product’s selling plan groups can be pulled. To get only Smartrr selling plan groups, filter by appName and limit to Smartrr. Selling plans can be accessed from the selling plan groups.

To retrieve selling plans using Shopify's Storefront API, you can use a GraphQL query. Below is an example of how you might construct a query to fetch selling plans and their details based on a selling plan group:

query GetSellingPlansByProduct($first: Int, $productId: ID!) {
  product(id: $productId) {
    title
    sellingPlanGroups(first: $first) {
      edges {
        node {
          name
          appName
          options {
            name
            values
          }
          sellingPlans(first: $first) {
            edges {
              node {
                id
                name
                description             
                 options {
                  name
                  value
                }
              }
            }
          }
        }
      }
    }
  }
}

Shopify selling plan group documentation: https://shopify.dev/docs/api/storefront/2024-10/objects/SellingPlanGroup#top

Shopify product documentation:

https://shopify.dev/docs/api/storefront/2024-10/queries/product

Method 2: Smartrr API

GET https://api.smartrr.com/vendor/selling-plan-group

Subscription Programs are configured in the Subscription Programs tab in the left hand navigation of the Smartrr app.

Query Parameters

{
    // Response
}

From the call response, use the data provided in the sellingPlans[ ] array to power the storefront display. Submit the shopifyNumericId value for the field selling_plan in the form POST submission in order to attach a Subscription Group alongside an item added to a customer’s cart.

Attach Subscription Group to Item Added to Cart

POST  https://<shopify domain>/cart/add

Be sure to replace <shopify domain> with your store's shopify domain. Note, this is required to be a part of cart workflow and not checkout workflow as Shopify does not support subscriptions within the checkout workflow.

For more information on this POST method, visit Shopify's documentation on Cart API References.

The selling_plan property NEEDS to be provided for any subscription line item that is added to cart. Use the cartLinesAdd mutation from Shopify Storefront API to do this.

Shopify cartlinesAdd documentation: https://shopify.dev/docs/api/storefront/2024-10/mutations/cartLinesAdd#argument-lines

200: OK JSON object of the line items associated with the added items422: Unprocessable Entity Occurs when the exact quantity specified for one of the items can't be added to the cart

{

   // Response

}

Important: The product/variant will need to be enabled for the respective Subscription Program in the Smartrr admin portal. These can be detected with the productIds[ ] and/or variantIds[ ] array.

Displaying Account Portal

There are three methods for brands to display the Smartrr's Shopify liquid account portal on a headless shop.

We still recommend completing Smartrr's in-app Setup instructions up to step 3. Smartrr Installation – part 1. Install Snippets onto a dummy theme for developers to see how Smartrr renders the account portal, or if your developers would like to duplicate a piece of liquid functionality to headless.

1. [Recommended] Forward /account –related URLs to your {your-store}.myshopify.com domain.

   1. This is our recommended method as it allows Shopify to continue handling all account actions (Login/Logout/Register/Checkout).

2. Create an account page on your site using the code found in your Shopify theme customers/account.liquid and use <iframe> to display it. This works for headless shops using React.

3. Duplicate smartrr-account.liquid in HTML, replacing the liquid code with the corresponding HTML Code. This works for headless shops not using React.

For methods 2 and 3, please follow these additional instructions:

Pulling in data for liquidCustomer

The /customer/auth/session endpoint expects a liquidCustomer object. If the myshopify.com/account page is not used, the data may need to be pulled elsewhere. The customer data can be retrieved from Shopify Storefront API.

Below is the schema for the object.

{
 shopifyId: string,
 email?: string,
 phone?: string,
 firstName?: string,
 lastName?: string,
 trackShipmentText: string,
 defaultAddressId?: number,
 defaultAddress?: MailingAddress,
 state?: string,
 customerCurrency: string,
 orderCount: number,
 totalSpent: number,
 addresses: MailingAddress[]
}

Collection Pages

Smartrr can be added to any collection page where a product form is present.

Add the {% render 'smartrr-product', product: product, smartrr_unique_id: product.id, smartrr_collection: true %} snippet to the desired product form.

Ensure smartrr_unique_id value is the product ID.

Add the {% render 'smartrr-product-styles %} tag to the top of the collection page file.

Add the <script type="text/javascript" src="{{ 'smartrr-product-script.js' | asset_url }}"></script> script tag to the collection page. Make sure this is placed before the {% render 'smartrr-product' %} tag is rendered.

Landing Pages

Smartrr can be added to any landing page where a product form is present AND you are able to manually pull in the liquid product object.

Add the {% render 'smartrr-product' %} snippet to the desired product form alongside the smartrr_unique_id: product.id % attribute.

Example:

Custom Liquid Blocks

Example:

Last updated: April 3, 2024

Note: Before implementing Smartrr, it's important to to determine your eligibility for offering subscriptions on your storefront. You must also have enabled for a product to be subscription-eligible.

If your store is using , and have not , you’re eligible for our simple one-click automated install of Smartrr via our in-app Setup page.

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.

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.

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.

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:

• Customize the look and feel of your customer account portal

On-site setup

1. Install Smartrr snippets

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.

2. Add Smartrr subscription widget

Smartrr's subscription widget is an app block that can be added to your Default product page from your Shopify theme's online customizer.

If you installed Smartrr snippets to a theme that supports our widget, you will see a green banner during this step that reads: "You're using a Shopify theme that supports the block for our Smartrr Subscription widget."

Click Add Smartrr subscription widget to be taken to your live theme editor. Make sure you are viewing Products > Default product. Additionally, make sure you are previewing a product that you have added to a Smartrr subscription program. Under Product information, click Add block and find Subscription Options.

You can customize the look and feel of Smartrr Subscription Options on your by manipulating the block's settings in the left-hand sidebar.

Troubleshooting

Why don't see Smartrr on my theme once I preview my shop?

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.

Can I add subscription pricing outside the Smartrr subscription widget?

To add Smartrr's pricing element outside of the subscription widget, you can add the following code:

Styling can be changed by adding the following values to the data-smartrr-price-style attribute.

• original (Adds the original variant price/one-time purchase)

• original-compare (Adds the original variant price/one-time purchase price and the compare price)

• overwrite (Adds the current selected subscription plan's price)

• overwrite-compare (Adds the current selected subscription plan's price and compare price)

• strike (Discounted price struck through)

• strike-compare (Compare at price struck through)

How do I enable variant selection within the Smartrr subscription widget?

1. Find the product liquid file in your theme's code. This is usually named product.liquid or main-product.liquid, but can also be uniquely named if your shop uses a custom theme. If you can't find this file, you can also use theme.liquid.

2. At the bottom of the file, paste the following code:

1. In lines 4-5 above, input the unique selector for your variant selector elements. This can be done by inspecting the elements using your browser's developer tools and finding a class or data-attribute that is used only for variant selectors. Examples below:

Note: If your variant selectors are not <input> elements, then you can change the 'change' event listener to 'click'.

Last updated: April 3, 2024

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.

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.

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.

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:

• Customize the look and feel of your customer account portal

On-site setup

1. Install Smartrr snippets

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.

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.

When added, the product form should look something like this:

3. 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 customers/account.liquid. This file is typically located under either the Templates heading.

At the very beginning of the file, paste the following snippet:

The file should look like this:

Save the file.

4. Modifying the Order Status Page

Troubleshooting

Why don't 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.