Add subscriptions to your theme

• Add a product form to a template. A product form can be added to any template that can access the product object.

To support subscriptions in your theme, you'll use the following resources:

• The form object.
• Objects and object properties that represent selling plan information, including the following:
  • selling_plan_group: A group of selling plans that are available for the product's variants.
  • selling_plan: The details of the selling plan.
  • selling_plan_allocation: Information about how a particular selling plan affects a line item.
  • variant.requires_selling_plan.
• The /{locale}/cart/change.js endpoint of the Cart AJAX API.

Depending on where you're implementing your selling plan functionality, you'll access selling plan information through the following parent objects:

For more information about how to present each of these objects and their attributes, refer to Subscription UX guidelines.

To support subscriptions in your theme, you need to implement the following components:

• A selling plan selector on the product page: This selector enables customers to select a selling plan.
• JavaScript to update the selling plan: Use JavaScript to update the available selling plans when variants are selected, and update the hidden selling plan input as selling plan options are selected.
• A selling plan display in the cart: Indicate to customers when a selling plan has been applied to a line item. You can also implement a selling plan selector to give the option to add a new selling plan, or to remove or edit the current selling plan.
• A checkout charge in the cart: Display a checkout charge that represents the amount that customers need to pay during checkout.
• A selling plan display on the customer order pages: Indicate to customers when a selling plan has been applied to a line item.

You can add a selling plan selector for products wherever you can access the product form. For example, you might add a selling plan selector to the product template or a section in the template.

Selling plan groups and individual selling plans have a similar structure to products and variants. You can view selling plan groups like products, where there are multiple options that comprise an individual selling plan, similar to variant options that comprise an individual variant.

You can access the available selling plan options through the selling_plan_groups attribute of the product.

Add the following to your product form:

• For each selling_plan_group, output each of its options inside the product form.
• To track the ID of the selected selling plan, add an input with an attribute of name="selling_plan". The value should be the ID of the selected selling plan. If there's no selected selling plan, then the value should be empty.
• Save the product object so that it can be accessed in JavaScript.

The following example is showing an example on how you can show the selling plan group in your product form. Make sure to add the code inside your product form. The example is referring to the file selling-plans-integration.js, this file is covered on the JavaScript section. The following code is doing the following:

• Assign the product and the current variant to be used inside the integration
• Loop through every selling plan group, and display each associated selling plan
• When the product is only sold as a subscription, we do not allow the buyer to buy the product as a one time purchase
• Add a Subscription badge to be displayed next to the product price when a buyer selects a subscription

JavaScript is used to interact with the theme integration. This will make it possible for a buyer to select a product and add the correct subscription to their cart. You can create a separate file named selling-plans-integration.js inside the Assets folder of your theme. The following example illustrates how JavaScript can interact with the selling plan liquid integration:

• The functions listenToVariantChange() and listenToAddToCartForms() are implemented to track when a product variant is altered or when the product form is updated. The identification of the variant is crucial as it dictates which selling plan box should be displayed. For more information about how to find a variant, refer to our community post.

If a customer selects a selling plan on the product page, then they should see that selection in the cart.

Available selected selling plans are accessible through the selling_plan_allocation attribute of the line_item object. The following is an example:

Rather than just display the selected selling plan, you can give customers the option to add a new selling plan, or to remove or edit the current selling plan. To do this, you should implement a selling plan selector that lists out the available selling plans for the line item's variant, and reflects the currently selected selling plan.

You can loop through the selling_plan_allocations attribute of the variant object associated with the line item (line_item.variant) to build out your selector options. You can compare the selected selling plan ID with the ID of the selling plan at the current index of the loop to make sure that the selector reflects the currently selected selling plan.

To change the selling plan for a line item, you can use the /{locale}/cart/change.js endpoint of the Cart AJAX API.

The following example outputs a selling plan selector:

The following example illustrates the concept of watching for a change in the selling plan selector and applying those changes through the /cart/change.js endpoint. It isn't completely functional.

Because pre-order and TBYB can change how much a customer has to pay up front, you should show them how much they'll be charged at checkout. You can calculate this amount using selling_plan.checkout_charge object.

You can access a line item's checkout charge through its selling_plan_allocation.

The following table outlines the types of checkout charges:

The following example outputs the appropriate line item price depending on whether the line item has a selling plan allocation, and what kind of selling plan it is.

When a customer selects a selling plan, they should see the name of that selection on the customer order page.

The selected selling plan, if there is one, is accessible through the selling_plan_allocation attribute of the line_item object. The following is an example: