Support purchase options

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

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.

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.

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:

1. For each selling_plan_group, output each of its options inside the product form.
2. 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.
3. 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.

To ensure that product and selling plan details reflect current selections, you should write JavaScript to handle for two events:

• Variant selection
• Selling plan option 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.

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.

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.

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.

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:

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.