[Subscriptions] Documentation

Theme updates for subscriptions

Public facing document link

Background

Shopify has launched a number of APIs to support subscriptions as a business model in a closed beta launched on November 2nd. The Selling Plan API has been extended to Liquid and JSON responses to support subscription purchases in online store themes (Liquid doc link). 

The only way for merchants to make subscription products (selling plans) is through an App; there will be no native admin implementation. App Partners are responsible for providing merchant-facing UIs for subscription setup and management. Additionally, App Partners will be injecting buyer-facing UIs within the merchant’s theme, including updates to customer account pages and a subscription plan selector on product pages.

Example of an App’s selling plan selector displayed within a product form

Whenever an App injects UIs into a theme, there are risks the two codebases will have difficulty integrating. In working with App Partners to establish a baseline for Buyer UX on store, the primary trouble spot was having subscription information appear on line items on the Cart page and cart drawers/notifications, and have the information persist on cart updates. The fact that most carts use AJAX to build and update cart line items is a blocker for App devs as they do not have tools to properly modify a JavaScript file the same way they can Liquid files. (And it’s recognized that even modifying Liquid files comes with challenges).

After discussing the issue with App developers and Shopify team members experienced with theme development, it was determined that the best approach is to make showing a subscription’s selling_plan.name on cart line items the responsibility of the theme (Example below). This is comparable to how the vast majority of 3rd party Theme Store themes already display line item properties on cart lines. Similarly, themes will be asked to provide selling plan information on line items on order pages.

The pink box is mimicking an app installation that injects a widget for selling plan selection.

Links summary

Liquid and AJAX updates: 

• selling plan object and selling_plan_allocation object

• line_item.selling_plan_allocation object
• Noted in the docs: this object returns different properties when accessed through order.line_items
• product.selling_plan_groups 
• There have been a number of other product properties added to support selling plans.

• Ajax APIs have been updated to show how to add a selling plan to cart.

Demo store - Subs Demo: Coffee product subscription 

• Password: welovesubs2020
• This is a prototype built to test the APIs. The cart page and notification support displaying the selling plan name. 

Other:

• Landing page for subscriptions: marketing page
• List of Subscription Apps compatible with checkout; a.k.a. Launch partners
• Tutorial: Showing selling plan groups and selling plans on a product page
• Useful for seeing code examples of working implementations, but not a requirement of this theme update.

What

Themes will be required to do the following:

Update cart page’s and any AJAX carts to display a selling plan name on line items, if it exists.

• Update order pages to display a selling plan name on line items, if it exists.
• There are additional suggestions in the UX Guidelines section below.

Instructions

👀 Debut v17.6.1 available in the Theme Store already has these updates, should you wish to see how the project team implemented it.

The selling plan name can be accessed in Liquid within line items through the selling_plan_allocation object. From the allocation, the selling plan name can be found through selling_plan.name. 

Only implement the selling plan name within cart and order line items that are bought as subscriptions. This can be checked by simply checking if the line item has a selling_plan_allocation object. The name property is a required element of selling plans created by apps.

{% if line_item.selling_plan_allocation %}  <span>{{ item.selling_plan_allocation.selling_plan.name }}<span> {% endif %}

For cart implementations utilizing Javascript, the selling plan name can similarly be found within cart line items returned from the cart AJAX APIs again through the selling_plan_allocation.selling_plan.name property.

var selling_plan_name = item.selling_plan_allocation ?  item.selling_plan_allocation.selling_plan.name : null;   if (selling_plan_name) {  // Display in cart update }

Feedback

We are looking for your feedback on the theme requirements above for discounts. You can submit your feedback here: Beta feedback sheet

Testing

Creating selling plans to purchase within storefront

Selling plans can only be created and applied to products by an app. You will need to install  one of the new subscription apps that use the new APIs - these are the beta launch Partners.

Additional requirements for selling plans:

• Your store must be using Shopify Payments
• No Shopify Scripts published 
• No checkout liquid customizations
• Full list of eligibility requirements here

Notes on Apps

The following are notes compiled by Shopify’s team to help you understand a bit more about the Apps before you try installing them on your store.

PayWhirl free app. The plan setup / installation instructions are more cumbersome than the other apps, but it is the only one available at launch that can be installed on a development store at the moment.

• When following their installation instructions, skip the step that asks you to edit the cart. You will want your own codebase to handle this. PayWhirl has been informed that they ought to be checking the theme’s codebase for use of the selling_plan property before asking merchants to do this step.
• PayWhirl’s selling plan selector widget has virtually no styling. This App Partner does not have as much experience integrating into a theme’s codebase as other Apps. Their previous implementation used iframes.

Bold Subscriptions app (60-day free trial). The plan setup UX is felt to be easier and their dev team has the most experience with theme-and-app integrations. 

• ⚠️ At the time, the app cannot be installed on a development store. Bold intends to make this app free indefinitely on development stores; however, that feature wasn’t available for launch and is being built later. 
• We confirmed with Bold that you can reach them directly (partners@boldcommerce.com), identify yourself as Theme Partner, and they will give you a free account.

ReCharge subscriptions app (60-day free trial). 

• ⚠️ReCharge has implemented a ‘waitlist’ to onboard people to their app (screenshot). 
• At this time, we’d recommend using the other apps for testing instead of waiting to schedule a time with ReCharge.

Adding selling plans to cart

To add selling plans to the cart, you can use the cart AJAX APIs to add a variant ID with a selling_plan ID to the cart.

Alternatively, you can add the following snippet to the product form that allows you to select a selling_plan.

{% if product.selling_plan_groups.size > 0 %}  <div>    <label for="plans">Purchase options:</label>    <select name="selling_plan" id="plans">      <option value="">One time purchase</option>      {% for variant in product.variants %}        <optgroup label="{{ variant.title }}">          {% for allocation in variant.selling_plan_allocations %}            <option value="{{ allocation.selling_plan.id }}">              {{ allocation.selling_plan.name }}            </option>          {% endfor %}        </optgroup>      {% endfor %}    </select>  </div> {% endif %

UX Guidelines

The subscriptions team has already documented public UX Guidelines for updating a theme to display selling plans. However, the audience of that document is custom theme developers who own both the App installation and Theme codebase. Not all aspects of that document are relevant to Theme Partners. Below we identify specific UX considerations for your theme’s update.

Displaying selling plan name in cart items and order line items

The selling plan name is text provided by the App. Some apps will allow the merchant to write the name, while other apps will decide the name based on the selling plan’s properties. Display the selling plan in a theme by referencing the API property selling_plan.name. 

Do not add an additional label like “Subscription : {{selling_plan.name}}” because this may be redundant with the text in the selling plan name or product title.

It is recommended to style the selling plan name with the same or similar styles (color and typography) used to show product options and/or line item properties on line items. Rationale: Checkout will be presenting the selling plan name with the same styling as product options and line item properties; so there is no strong need to emphasize a particular piece of information.

It is recommended to show line item information in the same order as Checkout to maintain consistency through the buyer flow:

1. Product options
2. Selling plan name
3. Line item properties

Screenshot of checkout 

• Product options: Dark chocolate mocha
• Selling plan name: Delivery every week, 35%
• Line item property: Engraving: Shopify

Screenshot of cart showing information in the same order

Dynamic checkout button

Selling plans are not compatible with the dynamic checkout button, so Shopify disables its render on any product that includes selling plans. The reason the payment button is not compatible is because not all payment options (Apple, GPay, etc.) have APIs compatible with selling plans. The Subscriptions team may revisit this solution in the future, but for now payment buttons are not rendered when the theme setting is enabled. Therefore, the remaining button will be wearing the secondary style although no primary action is available anymore on the page.

Ensure your theme accounts for this and that the primary call-to-action style is used for the form submission.

You can determine whether there are any selling plans on the product by checking the size of the product.selling_plan_groups array as all selling plans are part of a selling plan group.

{% if product.selling_plan_groups.size > 0 %}  // Use primary styling on Add to Cart button {% endif %}

Displaying line item properties at cart and order line items

The vast majority of 3rd party themes in the Theme Store are already displaying line item properties at cart. If your theme is not displaying these already, it is recommended to add these in your update.

It is also recommended to update order pages to display line item properties on any line items that have properties attached.

Note: Any line item properties that begin with an underscore (e.g. _foo) are considered “private properties” and are not shown at checkout. Your theme should not display these properties.

• This will require checking in Liquid and JS if the first character in a property is an underscore. This isn’t ideal and there are conversations internally to make a dedicated array of “public properties”, but there is no roadmap for this implementation at this time.

Known issues

See above notes on apps for known issues in testing on development shops.

There are no known bugs in the selling plans feature; however, below are notes on theme development and design concerns.

Expressing selling plan price ranges on product cards

There are currently no new Liquid properties on the product object that summaries selling plan allocation prices akin to product.price_min or product.price_max. At this time, there are platform engineering concerns about how to aggregate this information in a performant way, so it has been scoped out from launch. This is still something the team will explore, but it’s unknown when or if this would be available.

Updating product page UIs based on selling plan selection

An app’s selling plan selector is responsible for making sure the current selling_plan.id is submitted to cart. It is possible that a theme’s codebase could listen for changes on an input with [name=selling_plan] and update product page UIs with the selling plan information.  In the screenshot below:

• the pricing component’s prices update and a new badge is displayed.
• An additional message is displayed above the selling_plan.description that explains the selling plan allocation price_adjustments schedule.

⚠️ These types of updates are possible, but at the theme’s own risk. A theme’s codebase doesn’t know what information an App’s selling plan plan widget and scripts are doing. This risks information being duplicated, or race conditions between the App and Theme to update certain UI elements.

Timeline

The following dates and Partner names are sensitive information and not to be shared outside this group.

• November 2nd: 
• Public launch of the beta Subscriptions API. 
• A handful of pre-selected App Partners that we’ve been working with will have their new subscription apps submitted to the App store using the beta API. Launch Partners: ReCharge, Bold and PayWhirl
• Beginning of Q1 2021: 
• The Subscriptions API is planned to go to a stable release. 
• The larger App Partner ecosystem is allowed to start submitting new subscription apps to the App Store that are built on this stable API.

*All dates are tentative