Overview of installation
Simple Subscriptions works with all free Shopify themes (e.g., Debut, Brooklyn, Express, etc.) as well as Online Store 2.0 compliant themes out-of-the-box. If your store uses themes that fall into either of these categories you should NOT need to follow this guide.
Only stores that use older themes from the Shopify theme store or custom themes need to edit code to install Simple Subscriptions. After installing the app the in-app installation guide will indicate if you need to use this tutorial.
Contact our support channel (support@cakewalk.dev) with any questions! Or, submit a request for free help updating your theme.
Automatically install scripts into your theme
After installing Simple Subscriptions use the "Install theme code" button on the in-app installation guide to add our custom JavaScript to your store.
This step is fully automated once you click the button and will create two files within your theme (if you'd like to verify their existence):
- sections/simple-subscriptions.liquid
- snippets/simple-subscriptions-link.liquid
These files should not be edited and can be removed and recreated by using the "Remove theme code" button and re-running this step.
Update theme code to reference installed scripts for product page
The following steps will get the product subscription widget up and running on your product page.
Render the app's section from your product template
For example, in the Debut theme this is done by adding {% section 'simple-subscriptions' %} to the theme asset templates/product.liquid just after the {% section 'product-template' %} line.
Ensure scripts can find the selected product value
The on-form (usually hidden) master product variant select needs to be tagged so that the Simple Subscriptions script can find it on initial page load. This can be done by adding a "data-product-master-select" attribute to the field. In Debut, for example, we would add this in product-template.liquid as:
<select name="id" id="ProductSelect-{{ section.id }}" class="product-form__variants no-js" data-product-master-select>
The only change to the Debut code above is the addition of the "data-product-master-select" property. Ensure that this is added to all product selects. There may be more than one if the theme uses different forms for single-variant products and multi-variant products.
Update theme JavaScript to trigger variant change
Update the theme's JavaScript to notify the storefront app code when the selected variant has changed by passing the updated variant ID as follows:
In Debut, for example, this snippet can be inserted into the _onSelectChange function just after calling the _updateMasterSelect function.
Place the widget inside the product form
Add the HTML <div id="ss-options"></div> wherever you would like the purchase options widget to render. In Debut, for example, this is just before the "Add to Cart" button in sections/product-template.liquid.
Update your order status page
If you'd like customers to be able to manage their subscription from the customer account page (i.e., after logging-in to your store) then you'll also need to add a link to Simple Subscriptions to customers/order.liquid.
Note that the required snippet "simple-subscriptions-link" will be added automatically via the "Install" above and SHOULD NOT be edited.
Working with the AJAX Cart API
If using the AJAX cart API, the selling_plan parameter may need to be added to the request. The AJAX API documentation "Add a selling plan" section shows an example. You can get the selling plan ID by checking the product form for hidden field input[name=selling_plan] and reading its value.
Display the selling plan name in the Cart
If you'd like to show the selling plan name when customers visit their cart before checkout then you may need to add code like the following (some themes already have this code added):
See Shopify's storefront guidelines for subscriptions for more information.
Customizing CSS for Simple Subscriptions
Finally, add a new asset named "simple-subscriptions.css" to the theme and ensure that the asset is served at least on product pages. A starting point for the widget CSS is available here (based on the Debut theme).