Support purchase options
In this tutorial, you'll learn the basics of how to support purchase options in your theme.
Requirements
Anchor link to section titled "Requirements"- Add a product form to a template. A product form can be added to any template that can access the
product
object.
To support purchase options in your theme, you'll use the following resources:
- The
form
object. - Objects and object properties that represent selling plan information, including:
selling_plan_group
: A group of selling plans 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 purchase option functionality, you'll access selling plan information through the associated parent object:
Context | Example template types | Parent object |
---|---|---|
Product and variant listings | product | variant |
Variants that have been added to a cart or are part of an order | line_item |
For more information about how to present each of these objects and their attributes, refer to Subscription UX guidelines and Deferred purchase option UX guidelines.
Implementing purchase option displays
Anchor link to section titled "Implementing purchase option displays"To support purchase options 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.
The selling plan selector on the product page
Anchor link to section titled "The selling plan selector on the product page"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 object.
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 it can be accessed in JavaScript. You can do this by passing the object, with a JSON filter applied, as a data attribute.
This example includes selling plan options in the product form. It also does the following:
- Uses selling plan information in the price display, and automatically assigns a selling plan allocation to a variant when necessary.
- Saves the product object so it can be accessed in JavaScript. This is done by passing the object, with a JSON filter applied, in the
data-product
attribute on the selling plan option selector container.
JavaScript to update selling plan information
Anchor link to section titled "JavaScript to update selling plan information"To ensure that product and selling plan details reflect current selections, you should write JavaScript to handle for two events:
Variant selection
Anchor link to section titled "Variant selection"When a customer selects a variant, the selling plan options might need to be updated based on the newly selected variant. You need to detect this change, and update which selling plan options are displayed.
Retrieve the following information to update the display:
- To intercept a variant selection event, add a
change
event listener to the general product form. - Access the selected variant ID through the form input with an attribute of
name="id"
. - Access the product object. In this example, it's retrieved from the data attribute on the selling plan option selector container, defined in the selling plan selector implementation.
With the selected variant ID and the product object, you can access the selected variant object and any associated selling_plan_allocation
objects to update your selling plan option display.
The following example is meant to illustrate the required concepts for updating the selling plan option display based on a variant selection event. It isn't completely functional.
Selling plan option selection
Anchor link to section titled "Selling plan option selection"When a customer selects a selling plan option, it also changes the selected selling plan, which means that you need to update the selling plan input. In the selling plan selector example, this input has an attribute of name="selling_plan"
, and its value is the selling plan ID.
Retrieve the following information to update the display:
- Find the selling plan ID of the selected selling plan. To do so, compare the selected selling plan options with the available selling plans on the selected variant.
- Access the selected variant ID through the form input with an attribute of
name="id"
. - Access the product object. In this example, it's retrieved from the data attribute on the selling plan option selector container, defined in the selling plan selector implementation.
With access to the selected variant ID and the product data, you can find the selected variant object and its available selling plans. This allows you to compare the selected selling plan options against the available selling plans to find the selected selling plan ID.
The following example is meant to illustrate the required concepts for updating the selling plan input based on a selling plan option selection event. It isn't completely functional.
The selling plan display in the cart
Anchor link to section titled "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.
The selected selling plan, if there is one, is accessible through the selling_plan_allocation
attribute of the line_item
object.
The selling plan selector
Anchor link to section titled "The selling plan selector"Rather than just show 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 is meant to illustrate 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
Anchor link to section titled "The checkout charge display in the cart"Because deferred purchase options 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
.
You can access a line item's checkout charge through its 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. |
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.
Customer order selling plan display
Anchor link to section titled "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.