Build a product bundle selector

A bundle selector has three jobs: render the available groups, collect a valid choice for each group, and send the selected variants with the parent bundle.

Read the bundle structure

Fetch the product from the public storefront Product show operation. Its response exposes is_bundle and a top-level bundle_groups array on product. Non-bundle products return an empty bundle_groups array. Use product.bundle_groups[], not the legacy product.product_bundle_groups[] shape. Each group provides id, title, min_selections, max_selections, selection_type, and bundle_group_items. Each item identifies its selectable variant with bundled_variant_id.

{% if product.is_bundle and product.bundle_groups.size > 0 %}
  {% for group in product.bundle_groups %}
    <fieldset data-bundle-group="{{ group.id }}">
      <legend>{{ group.title }}</legend>

      {% for item in group.bundle_group_items %}
        <label>
          <input
            type="checkbox"
            value="{{ item.bundled_variant_id }}"
            data-bundle-item
          >
          Variant {{ item.bundled_variant_id }}
        </label>
      {% endfor %}
    </fieldset>
  {% endfor %}
{% endif %}

Use the group’s selection fields to validate the shopper’s choices before enabling your add button. Treat that client-side check as feedback, not as a replacement for cart validation.

Build the cart selection

Create one child entry for every selected variant. Keep the group id with each choice so checkout can associate it with the correct bundle group.

const bundledItems = Array.from(
  document.querySelectorAll("[data-bundle-item]:checked"),
).map((input) => ({
  variant_id: Number(input.value),
  quantity: 1,
  product_bundle_group_id: Number(
    input.closest("[data-bundle-group]").dataset.bundleGroup,
  ),
}));

For a direct checkout integration, the Add Items contract accepts bundled_items on each parent item. Every child requires variant_id and quantity. A child can also carry product_bundle_group_id, subscription, and subscription_plan_id. See the generated Checkout endpoints reference for the full contract.

Add the bundle with FairShare

The FairShare SDK uses its own cart lifecycle. Pass the child selections through addCartItems() with the parent bundle variant:

await window.FairShareSDK.addCartItems([
  {
    variant_id: 278318,
    quantity: 1,
    bundled_items: bundledItems,
  },
]);

The SDK forwards the nested child objects at runtime. Its published TypeScript type includes variant_id, quantity, display_to_customer, subscription, and subscription_plan_id, but may not yet declare product_bundle_group_id. JavaScript callers can send the group identifier. TypeScript callers may need a local type extension until the SDK declaration catches up. See Cart API for both addCartItems() call forms and subscription examples.

Test the workflow

Test a bundle with minimum and maximum choices, subscriptions, and more than one group. Confirm that your selector produces the intended child variants and group identifiers before you test the complete cart flow.

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Files SDK

Build a product bundle selector

Read the bundle structure

Build the cart selection

Add the bundle with FairShare

Test the workflow

​Read the bundle structure

​Build the cart selection

​Add the bundle with FairShare

​Test the workflow

Read the bundle structure

Build the cart selection

Add the bundle with FairShare

Test the workflow