Add subscription options outside the product page

The Subscription Widget block shows subscription options on product pages. The old subscription widget also appeared on collection pages, quick-add pop-ups and other places with an Add to cart button; the block doesn't. If you want subscription options in those places, add them with your own theme code, following this guide.

This guide is for theme developers. It uses standard Shopify selling plan features, so nothing here depends on Awtomic scripts. Contact [email protected] if you need help.

How a subscription gets into the cart

A product is added to the cart as a subscription when the add-to-cart request includes a selling_plan with the selling plan's ID. Without it, the product is added as a one-time purchase.

Awtomic's subscription plans are Shopify selling plan groups whose app_id is bundlesubscriptions. Filtering on app_id leaves out other apps' plans, but not Awtomic's checkout-only plans: Card Vaulting and allocation plans are bundlesubscriptions groups too. The Subscription Widget hides them using app data that theme code can't read, so your code has to choose the plans itself. The samples below only offer the subscription plans you name, using each plan's name from Subscription Plans in Awtomic (Shopify calls it the selling plan group's name). Never offer every bundlesubscriptions plan on the product, or a store with Card Vaulting or allocations will show those plans to customers.

Add a plan selector to a product form in Liquid

Use this in a collection card, quick-add form or any other section that renders a product form (form action="/cart/add").

{%- liquid
  # The Awtomic subscription plans to offer here, by name, separated by commas
  assign offered_plan_names = 'Coffee subscription,Tea club' | split: ','
  assign awtomic_groups = product.selling_plan_groups | where: 'app_id', 'bundlesubscriptions'
  assign current_variant = product.selected_or_first_available_variant
  assign has_offered_plan = false
  for group in awtomic_groups
    if offered_plan_names contains group.name
      assign has_offered_plan = true
    endif
  endfor
-%}

{%- if has_offered_plan -%}
  <select name="selling_plan">
    {%- unless product.requires_selling_plan -%}
      <option value="">One-time purchase</option>
    {%- endunless -%}
    {%- for group in awtomic_groups -%}
      {%- if offered_plan_names contains group.name -%}
        {%- for selling_plan in group.selling_plans -%}
          <option value="{{ selling_plan.id }}">{{ selling_plan.name }}</option>
        {%- endfor -%}
      {%- endif -%}
    {%- endfor -%}
  </select>
{%- endif -%}

• Replace Coffee subscription,Tea club with your own plan names, spelled exactly as in Awtomic. If you rename a plan, update the list. You can also make the list a theme setting so the merchant can edit it in the theme editor.

• Put the <select> (or radio inputs, or a hidden input) inside the product's form, so its value is submitted with the variant id.

• An empty value adds a one-time purchase. Leave out the one-time option when product.requires_selling_plan is true, because those products can only be bought as a subscription.

• To show the subscription price for the selected variant, use current_variant.selling_plan_allocations: each allocation has a selling_plan and a price (in cents, so use the money filter).

• A plan is available only for the variants it's assigned to. If customers can change the variant in this form, update the options when the variant changes, or check the plan against the variant's selling_plan_allocations before adding to the cart.

Add to the cart with JavaScript

If your theme adds to the cart with the Cart API (for example a quick-add button), pass selling_plan with the item:

await fetch(window.Shopify.routes.root + 'cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    items: [{ id: variantId, quantity: 1, selling_plan: sellingPlanId }],
  }),
});

Leave out selling_plan (or send null) for a one-time purchase.

Read plans in JavaScript

To build the options in JavaScript, fetch the product's JSON from /products/{handle}.js. It includes:

• selling_plan_groups: each group has an app_id, a name and selling_plans, each with an id, name and price_adjustments. Keep only bundlesubscriptions groups whose name is one of the plans you offer, as in the Liquid sample, so Card Vaulting and allocation plans stay out.
• requires_selling_plan: true when the product can't be bought as a one-time purchase.
• variants[].selling_plan_allocations: the plans available for each variant, with selling_plan_id, price and compare_at_price in cents.

Quick-add pop-ups

Some themes build their quick-add pop-up by loading the product page's main section after the page has loaded. If you've added the Subscription Widget block to that section, its options can show in the pop-up, but the widget's script only starts on the widget when the page loads, so selecting a plan there isn't guaranteed to reach the cart. Test it in your theme before relying on it. If it doesn't work, or your quick-add renders its own form, add a plan selector to that form as above.

Listen to the widget from your own code

On product pages, the Subscription Widget fires an event on document whenever the customer changes the purchase option, frequency or variant:

document.addEventListener('awtomic:sellingplan:change', (event) => {
  const { productId, variantId, sellingPlanId } = event.detail;
  // sellingPlanId is null when one-time purchase is selected
});

The event detail also includes the selected price (formattedPrice, formattedCompareAtPrice) and discount (discountValue, discountType). Use it in place of the old widget's window.bundleapp hooks, the bundleapp:ready event, onInit, initializeForms and setThemeConfigs, which don't exist with the block. See Switch from the old subscription widget.

Test it

1. On a collection page or quick-add, choose a subscription and add the product to the cart.
2. In the cart, confirm the item shows the subscription and frequency you chose.
3. Add the same product as a one-time purchase and confirm the cart shows no subscription.
4. Try a subscription-only product and confirm there's no one-time option.