Using Quantity Upsells with custom widgets

When you use Quantity Upsells with a custom or third-party subscription widget, the widget must determine the quantity associated with each selling plan.

Recharge stores quantity information in the selling plan options. Custom widgets must read this value to correctly reflect the selected quantity and ensure the correct quantity is added to cart.

This guide explains how custom and third-party subscription widgets should determine product quantity when using Quantity Upsells.

Implementation: Liquid / Theme App Extensions

For custom widgets using Liquid files:

Each selling plan includes an options array containing key/value pairs.

Example

{
  "id": 12345,
  "name": "2 month supply",
  "options": [
    {
      "key": "Recharge Plan ID",
      "value": "20054464"
    },
    {
      "key": "Order Frequency and Unit",
      "value": "2-month"
    },
    {
      "key": "Product Quantity",
      "value": "2"
    }
  ]
}

To determine quantity:

1. Iterate through plan.options.
2. Find the option where option.key === "Product Quantity".
3. Use option.value as the selected quantity

Example (JavaScript):

const quantityOption = plan.options.find(
  option => option.key === "Product Quantity"
);

const quantity = quantityOption
  ? parseInt(quantityOption.value, 10)
  : 1; // default fallback

If the Product Quantity option is not present, the widget should default to a quantity of 1.

Implementation: GraphQL / Headless

When using Shopify Storefront GraphQL:

• sellingPlanGroup.options contains option names (keys)
• sellingPlan.options contains option values
• The arrays correspond by index position

Example response structure:

{
  "sellingPlanGroup": {
    "options": [
      "Recharge Plan ID",
      "Order Frequency and Unit",
      "Product Quantity"
    ],
    "sellingPlans": {
      "nodes": [
        {
          "id": "gid://shopify/SellingPlan/123",
          "options": [
            "20054464",
            "2-month",
            "2"
          ]
        }
      ]
    }
  }
}

To determine quantity:

1. Find the index of "Product Quantity" in sellingPlanGroup.options.
2. Use that index to retrieve the corresponding value from sellingPlan.options.
3. Parse the value as an integer.

Example

const groupOptions = sellingPlanGroup.options;
const planOptions = sellingPlan.options;

const quantityIndex = groupOptions.indexOf("Product Quantity");

const quantity = quantityIndex > -1
  ? parseInt(planOptions[quantityIndex], 10)
  : 1; // default fallback

Expected behavior

Custom widgets using Quantity Upsells should:

• Read the selling plan quantity from plan options
• Update the UI to reflect the selected quantity
• Ensure the correct quantity is added to cart
• Maintain quantity consistency during upsell transitions

If the widget does not read the Product Quantity option, the incorrect quantity may be displayed or added to cart.