In this tutorial, you'll learn the basics of how to support subscriptions in your theme. > Tip: > Refer to [Subscription UX guidelines](/docs/storefronts/themes/pricing-payments/subscriptions/subscription-ux-guidelines) to review user experience considerations that might impact your implementation. ## Requirements - Add a [product form](/docs/api/liquid/tags/form#form-product) to a template. A product form can be added to any template that can access the [`product`](/docs/api/liquid/objects/product) object. ## Resources To support subscriptions in your theme, you'll use the following resources: - The [`form`](/docs/api/liquid/objects/form) object. - Objects and object properties that represent selling plan information, including the following: - [`selling_plan_group`](/docs/api/liquid/objects/selling_plan_group): A group of selling plans that are available for the product's variants. - [`selling_plan`](/docs/api/liquid/objects/selling_plan): The details of the selling plan. - [`selling_plan_allocation`](/docs/api/liquid/objects/selling_plan_allocation): Information about how a particular selling plan affects a line item. - [`variant.requires_selling_plan`](/docs/api/liquid/objects/variant#variant-requires_selling_plan). - The [`/{locale}/cart/change.js` endpoint](/docs/api/ajax/reference/cart#post-locale-cart-change-js) 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: | Context | Example template types | Parent object | | --- | --- | --- | | Product and variant listings | [product](/docs/storefronts/themes/architecture/templates/product) | [variant](/docs/api/liquid/objects/variant) | | Variants that have been added to a cart or are part of an order | | [line_item](/docs/api/liquid/objects/line_item) | For more information about how to present each of these objects and their attributes, refer to [Subscription UX guidelines](/docs/storefronts/themes/pricing-payments/subscriptions/subscription-ux-guidelines). ## Implementing subscription displays To support subscriptions in your theme, you need to implement the following components: - **[A selling plan selector on the product page](#the-selling-plan-selector-on-the-product-page)**: This selector enables customers to select a selling plan. - **[JavaScript to update the selling plan](#javascript-to-update-selling-plan-information)**: 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](#the-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](#the-checkout-charge-display-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](#customer-order-selling-plan-display)**: Indicate to customers when a selling plan has been applied to a line item. ## The selling plan selector on the product page You can add a selling plan selector for products wherever you can access the [product form](/docs/api/liquid/tags/form#form-product). For example, you might add a selling plan selector to the [product template](/docs/storefronts/themes/architecture/templates/product) 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](/docs/api/liquid/objects/product#product-selling_plan_groups). Add the following to your product form: - For each [selling_plan_group](/docs/api/liquid/objects/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](#javascript-to-update-selling-plan-information). ### Example 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](#javascript-to-update-selling-plan-information) 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 > Note: > This example demonstrates how to integrate selling plans into your theme. We recommend customizing this integration to suit your specific needs. The following code can also be used as a [theme app block](/docs/storefronts/themes/architecture/blocks/app-blocks).

## JavaScript to update selling plan information 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](https://community.shopify.com/c/shopify-apps/subscription-1p-app-block/td-p/2415591#:~:text=Finding%20the%20variant%20input). ## The selling plan display in the cart 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](/docs/api/liquid/objects/line_item). The following is an example:

### The selling plan selector 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`](/docs/api/liquid/objects/variant#variant-selling_plan_allocations) 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`](/docs/api/ajax/reference/cart#post-locale-cart-change-js) endpoint of the Cart AJAX API. #### Example 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.

## The checkout charge display in the cart 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`](/docs/api/liquid/objects/selling_plan#selling_plan-checkout_charge) object. You can access a line item's checkout charge through its [`selling_plan_allocation`](/docs/api/liquid/objects/selling_plan_allocation). The following table outlines the types of checkout charges: | Checkout charge type | Description | | --- | --- | | `percentage` | A percent value representing the percentage amount of the full price that must be paid up front. | | `price` | The price to be paid up front, in cents. | > Note: > You can't configure checkout charges for subscriptions. Because of this, subscriptions always have a `value_type` of `percentage` and `value` of 100. ### Example 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. ```liquid {% if item.selling_plan_allocation %} {%- assign checkout_charge = item.selling_plan_allocation.selling_plan.checkout_charge -%} {% if checkout_charge.value_type == 'percentage' %} {{ item.original_price | times: checkout_charge.value | divided_by: 100 | money }} {% else %} {{ checkout_charge.value | money }} {% endif %} {% else %} {{ item.original_price | money }} {% endif %} ``` ## Customer order selling plan display 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](/docs/api/liquid/objects/line_item). The following is an example: