Custom theme installation guide

When to follow this guide

Subscription Herder works out-of-the-box with Online Store 2.0 themes like Dawn. If your store uses an Online Store 2.0 theme then you should NOT need to follow this guide. Only stores that use older themes from the Shopify theme store, old themes like Debut, or custom themes may need to edit code to install and set up Subscription Herder.

Get free help setting up your Shopify store with subscriptions

Please submit a request to our team for free assistance setting up Subscription Herder with your Shopify store. We'll handle updating your theme as necessary and consult with you as to the best subscription plan configuration for your store. Our turnaround time is approximately 1 to 2 business days once we have access to edit your theme.

Install required snippet into your theme

Create a new file named "subscription-herder.liquid" in the Sections folder of your theme's code. Include the following liquid code:

{% if content_for_header contains "cakewalk.dev" %}
  <script type="text/javascript">
    globalThis._SS_DATA = {{ product | json }}
    globalThis._SS_MF = {{ shop.money_format | json }}
    globalThis._SS_CUST_CUR = {{ cart.currency.iso_code | json }}
    globalThis._SS_SHOP_CUR = {{ shop.currency | json }}
    globalThis._SS_HEADER = {{ section.settings.purchase_options_header | json }}
    globalThis._SS_PRICE_FROM = {{ section.settings.price_from | json }}
    globalThis._SS_PRICE_EACH = {{ section.settings.price_each | json }}
    globalThis._SS_PER_SHIPMENT = {{ section.settings.per_shipment | json }}
    globalThis._SS_PER_SHIPMENT_ADJUSTMENTS = {{ section.settings.per_shipment_adjustments | json }}
    globalThis._SS_SUB_POLICY = {{ section.settings.sub_policy | json }}

    {% for locale in shop.published_locales %}
      {% if locale.primary %}
        globalThis._SS_SL = {{ locale.iso_code | json }}
      {% endif %}
    {% endfor %}
  </script>

  <script 
    type="text/javascript"
    src="https://sscdn-prod.cakewalk.dev/app.min.js"></script>
{% endif %}

{% schema %}
  {
    "name": {
		"en": "Subscription Herder"
	},
    "settings": [
      {
        "type": "text",
        "id": "purchase_options_header",
        "label": {
          "en": "Header"
        },
        "default": {
          "en": "Purchase options"
        }
      },
      {
        "type": "text",
        "id": "price_from",
        "label": {
          "en": "Price description"
        },
        "default": {
          "en": "from {amount}"
        }
      },
      {
        "type": "text",
        "id": "price_each",
        "label": {
          "en": "Price subtext"
        },
        "default": {
          "en": "each"
        }
      },
      {
        "type": "text",
        "id": "per_shipment",
        "label": {
          "en": "Shipment price display (single price)"
        },
        "default": {
          "en": "{amount} per order"
        }
      },
      {
        "type": "text",
        "id": "per_shipment_adjustments",
        "label": {
          "en": "Shipment price display (with price adjustments)"
        },
        "default": {
          "en": "{amount1} for the first {orderCount} order(s) then {amount2}"
        }
      },
      {
        "type": "text",
        "id": "sub_policy",
        "label": {
          "en": "Subscription policy link"
        },
        "default": {
          "en": "View subscription policy"
        }
      }
    ]
  }
{% endschema %}

{% stylesheet %}
  .ss-root {
    margin-bottom: 20px;
    padding: 0;
  }

  .ss-root input[type=radio] {
    margin-right: 5px;
  }

  .ss-root .ss-group-select {
    display: flex;
  }

  .ss-root .ss-group-select label {
    display: flex;
    align-items: center;
    align-self: center;
  }

  .ss-root .ss-group-select div {
    font-size: 0.9em;
    margin-left: auto;
    text-align: right;
    display: flex;
    flex-direction: column;
    margin-top: -4px;
  }

  .ss-root .ss-group-select sub {
    text-align: right;
  }

  .ss-root .ss-group-options {
    padding-left: 15px;
    margin-top: 5px;
  }

  .ss-root .ss-group-options > label {
    display: block;
    font-variant: small-caps;
  }

  .ss-description {
    margin: 5px;
    margin-bottom: 20px;
  }

  .ss-description .ss-price {
    font-weight: bold;
  }

  .ss-description p:not(.ss-price) {
    margin-bottom: 0.2em;
  }

  @media only screen and (min-width: 990px) {
    .ss-root {
      padding: 0 5px;
    }
  }
  .ss-root .ss-group {
    border-top: solid 1px var(--color-border-form-darker, #cccccc);
    border-left: solid 1px var(--color-border-form-darker, #cccccc);
    border-right: solid 1px var(--color-border-form-darker, #cccccc);
    padding: 10px 10px 5px 10px;
    background-color: var(--color-text-field);
  }

  .ss-root .ss-group-select label {
    display: flex;
    align-items: center;
    align-self: center;
    max-height: 25px;
  }

  .ss-group:last-of-type {
    border-bottom: solid 1px var(--color-border-form-darker, #cccccc);
  }

  .ss-root .ss-group-select div {
    color: inherit;
  }

  .ss-root .ss-group-options > div {
    max-height: 25px;
  }

  .ss-root .ss-group-options > div > label > input {
    min-height: 0px;
  }

  .ss-group-options > div > * {
    margin: 5px;
  }
{% endstylesheet %}

{% javascript %}
{% endjavascript %}

Update theme code to reference new section 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 'subscription-herder' %} 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 Subscription Herder 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>
</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:

if (typeof(globalThis._SS_APP) !== 'undefined') { 
  globalThis._SS_APP.selectVariant(variant.id);
}

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 (optional)

This is no longer supported by default as Shopify has disabled write access to their Assets API. It is still possible to set this up with a secure code. If you are interested, please contact our support team.

If you skip this step, your customers will always be able to access their subscription from the Order Receipt page (displayed by Shopify after checkout) as well as an optional (enabled by default) email sent from our app.

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):

{% unless item.selling_plan_allocation == empty %}
  {{ item.selling_plan_allocation.selling_plan.name }}
{% endunless %}

See Shopify's storefront guidelines for subscriptions for more information.

Customizing CSS for Subscription Herder

A default CSS set up that works with Debut is installed in the file sections/subscription-herder.liquid that you created above. Edit the CSS at the bottom of that file to adjust the subscriptions widget to your liking.

Advanced: 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 selected selling plan ID by checking the product form for hidden field with selector input[name=selling_plan] and reading its value.