Skip to main content

Initial Product Selector

Allow customers to choose their first subscription items directly on the storefront, before checkout.

Overview​

The Initial Product Selector lets customers configure the contents of their first subscription box at the time of subscribing. Instead of subscribing to a shell product and then navigating to the customer portal to select items, customers can make their choice right on the product page.

How it works:

  1. Customer visits a shell product page on the storefront
  2. A product selector appears, showing items from configured collections
  3. Customer selects items according to the configured mode (see Selection Modes below)
  4. Customer clicks Confirm Selection — the shell product is added to the cart and the customer is taken directly to checkout (see Checkout Behavior below)
  5. Only the shell product is purchased at checkout
  6. After the subscription is created, the selected items are automatically added to the first billing cycle

This mirrors the product selection experience already available in the customer portal, but moves the initial choice to the point of subscription.

Selection Modes​

The Initial Product Selector supports three modes, determined by the metafields configured on the shell product variant:

Free Mode​

Items are added to the first billing cycle at no cost (as free one-time items), up to a configured limit. This limit also applies when customers edit product selections for future billing cycles in the customer portal.

Configured by: setting the custom.free_subscription_products_limit metafield on a shell product variant to the desired number (e.g., 5 or 10).

  • Customers can select up to the configured limit
  • The progress bar shows how many items are selected out of the maximum (e.g., "3/5 selected")
  • The confirm button is enabled as soon as at least one item is selected

Items are added to the first billing cycle at their regular price (not free), with a minimum total order amount required. This minimum also applies when customers edit product selections for future billing cycles in the customer portal.

Configured by: setting the custom.minimum_order_amount_for_cycle metafield on a shell product variant to the minimum order value in the store's currency (e.g., 25.00).

  • Customers can select any number of items
  • A minimum order total must be reached before the selection can be confirmed
  • A running total of the selection is shown (e.g., "Total: €12.50"), with a note naming the minimum until it's reached
  • The confirm button is disabled until the minimum order amount is met

Unlimited Mode​

Items are added to the first billing cycle at their regular price, with no quantity limit and no minimum order amount. The same applies for future billing cycle selections in the customer portal.

Configured by: leaving both metafields unset (or set to 0).

  • Customers can select any number of items
  • No progress bar or minimum order requirement is shown
  • The confirm button is enabled as soon as at least one item is selected
note

Configure only one of the two metafields per variant — not both. Each variant operates in exactly one mode.

Prerequisites​

Before setting up the Initial Product Selector, make sure you have:

  1. A shell product configured as your subscription box product
  2. The zubs-main-product tag assigned to the shell product
  3. One or more Shopify collections containing the products customers can choose from
  4. A selling plan (subscription plan) assigned to the shell product
  5. Mode metafield(s) set on the relevant shell product variants, depending on which mode you want to use (see Selection Modes above). In Unlimited Mode no metafield is required.
Free initial checkout

Consider granting a 100% subscription discount on the selling plan and then using a sequential flow to remove or reduce the discount after the first order. That way, the initial checkout order costs nothing and only the first "real" billing cycle charges the customer.

Build-a-box setup

The Initial Product Selector is one part of the build-a-box subscription model. For the complete setup guide — including minimum order thresholds, automatic cycle skipping, and ongoing customer portal management — see Build-a-Box Subscriptions.

Custom Pickup Locations

You can also let customers choose a pickup location at subscription time. See Custom Pickup Locations for the full setup guide.

Setup​

Step 1: Verify your shell product configuration​

  1. Open your shell product in the Shopify admin
  2. Confirm the product has the zubs-main-product tag
  3. For each variant, set the appropriate metafield for your desired mode:
    • Free Mode: set custom.free_subscription_products_limit to the desired item limit (e.g., 5 or 10)
    • Paid Mode: set custom.minimum_order_amount_for_cycle to the minimum order value in your store's currency (e.g., 25.00)
    • Unlimited Mode: leave both metafields unset (or set to 0)

Different variants can have different modes. For example, a "Small Box" variant might use Free Mode with a limit of 5 items, while a "Large Box" variant uses Paid Mode with a €30 minimum.

Step 2: Prepare your product collections​

Create one or more Shopify collections containing the products customers can choose from. These collections should only include items that are eligible for selection.

Tips:

  • You can configure multiple collections (e.g., "Meals - Chicken", "Meals - Vegan", "Meals - Desserts"). The selector shows their products together in one grid; to split it into sections, use Grouping products under headings

Optional: Configure availability schedules​

If certain products are only available during specific time periods, set an availability schedule on the collection — see Configure availability schedules. Products in that collection then only appear in the selector during the periods you set, based on the customer's next billing date. Both dates are part of a period.

Step 3: Add the block to your product page​

  1. Open the Theme Editor in your Shopify admin (Online Store → Themes → Customize)
  2. Navigate to your product page template
  3. Click Add block and look for the Initial Product Selector block (under the Zubs app)
  4. Add it to the product page section where you want the selector to appear

The block will only be visible on products that have the zubs-main-product tag.

Step 4: Configure the block settings​

After adding the block, configure the following settings in the Theme Editor:

Product Collections​

Select the collections containing the products customers can choose from. This is the primary configuration — without collections, no products will be shown.

Appearance​

SettingDescription
Accent colorColor used for interactive elements (buttons, quantity controls)
Progress bar colorColor of the selection progress bar
Card sizeSize of each product card (Extra small, Small, Medium, Large, Extra large). Defaults to Medium. Controls how wide the product image and card get across the grid
Mobile columnsNumber of product cards per row on mobile screens (1 column or 2 columns). Defaults to 2 columns

Display Options​

SettingDescription
Show pricesDisplay product prices alongside items
Show product imagesDisplay product thumbnail images
Show unavailable itemsDisplay products and variants that are currently out of stock

Variant names aren't optional: every variant gets its own card, and its name (e.g., Large, Small) always appears under the product title. Products with a single unnamed variant show just the product title.

Pickup Location Selector​

Enable the Pickup Location Selector toggle to let customers choose a pickup location before checkout. Pickup locations must be configured in the merchant portal first. See Custom Pickup Locations for setup instructions.

When the pickup selector is active, the storefront shows a numbered two-step flow: Step 1 — Choose your pickup location above the product grid, and Step 2 — Choose your items as a header above the grid. The pickup-location button in Step 1 opens a modal where the customer types a postal code, city, or address (or clicks Use my location), then picks from a distance-sorted list — with an optional interactive map view.

Custom Text​

SettingDescription
Custom textRich-text block rendered below the next-order-date card and above the Confirm Selection button. Use it for reassurance copy, delivery notes, or links to your FAQ. Leave empty to hide

Product Labels & Grouping​

Show up to three labels on each product card — small coloured chips for extra product info like a diet tag, a cooking method, or a serving size.

SettingDescription
Label N metafield keyProduct metafield to read, as namespace.key (e.g., custom.cooking_method). With no template, its value is shown as-is
Label N templateOptional. Mix literal text with {...} placeholders to build a richer label
Label N colorBackground colour of the chip

Placeholders resolve against the product on each card:

PlaceholderResolves To
{metafield.<namespace>.<key>}That product's metafield value
{metafield.<namespace>.<key>.<field>}A field on the metaobject that metafield references
{metaobject.<type>.<handle>.<field>}A field on a shop-wide metaobject entry — the same value on every card

A placeholder pointing at an image field renders as an icon; anything else renders as text. For example, a serving-size label combining a shop-wide icon with a per-product number:

{metaobject.serving_size_icon.standard.person_icon} {metafield.custom.serving_size} servings
tip

If a product has no value for one of its {metafield...} placeholders, that label is hidden on that card — so a label reading "servings" never appears without its number.

Grouping products under headings​

Long catalogues read better split into sections. Group by metafield keys turns a product metafield into headings across the grid — by category, by producer, by diet, by whatever you already store on the product.

SettingDescription
Group by metafield keysOne or more product metafields to group by, as namespace.key, separated by commas. Leave empty to show one flat grid

The key format matches the label keys above:

KeyGroups by
custom.categoryThat product metafield's value
custom.category.nameA field on the metaobject that custom.category references
custom.category, custom.farmingBoth, combined into a single heading — Vegetables · Organic

So a store whose products carry custom.category gets:

Fruit
  [Apple]  [Pear]
Vegetables
  [Carrot] [Leek]
Other
  [Mystery Box]

How the groups behave:

  • Group order is alphabetical. Inside a group, products follow the order of your Shopify collection.
  • Products with no value collect under an Other heading at the bottom. If no product in the grid has a value — usually a mistyped key — the flat grid comes back instead, which is your signal to check the key.
  • List metafields become one combined heading, and the card still appears once. A product tagged [Vegan, Gluten-free] groups with one tagged [Gluten-free, Vegan]; the order you entered them doesn't matter.
  • Spelling and case matter. Bio and BIO produce two headings. Surrounding spaces are ignored, so a stray trailing space won't split a group in two.
caution

With several keys configured, a product that only has some of them is grouped by the values it does have. A product with custom.category but no custom.farming gets its own Vegetables heading next to Vegetables · Organic — which looks like one category split in two. Fill every configured key across the products in a category, or group by a single key.

Checkout Behavior​

This behavior is fixed and has no settings. Clicking Confirm Selection adds the shell product (with the selected selling plan) to the cart and takes the customer straight to the standard Shopify checkout.

While the selector is open, the product page's own Add to cart button stays hidden. That keeps customers from skipping the selection, or from thinking they still need to click it separately after confirming.

note

The redirect always uses Shopify's standard checkout URL, not the accelerated "Buy it now" flow. This is required to preserve the product selection — see Known Limitations for details.

Customer Experience​

Selecting products​

When a customer visits a shell product page, the selector adapts to the configured mode:

Free Mode:

  1. Progress bar shows how many items they have selected out of the allowed maximum (e.g., "3/5 selected")
  2. Once the limit is reached, the + buttons are disabled until items are removed
  3. The Confirm Selection button is enabled as soon as at least one item is selected

Paid Mode:

  1. A running total shows the current selection value (e.g., "Total: €12.50"), with a note asking for items worth at least the minimum until it's reached
  2. Customers can add as many items as they want
  3. The Confirm Selection button is disabled until the minimum order amount is met

Unlimited Mode:

  1. No progress bar or minimum order amount is shown — customers can select freely
  2. The Confirm Selection button is enabled as soon as at least one item is selected

In all modes:

  • One product grid shows the products of all configured collections together, optionally split into sections by Grouping products under headings
  • Quantity controls let them add or remove items. Each click adds or removes one unit of a product variant
  • Next order date is displayed so customers know when their first delivery will arrive

Choosing a pickup location​

When the pickup selector is enabled, Step 1 is a single button — labeled with the customer's current selection or a placeholder. Clicking it opens a modal that walks the customer through finding the nearest pickup point:

  1. Reference step. Customer enters a postal code, city, or address (address autocomplete suggests matches as they type) or clicks Use my location for browser geolocation. Locations without an address or with one that couldn't be geocoded show no distance and sort to the end.
  2. Results step. Pickup locations appear sorted by distance, each row showing the location name, address, and a distance badge (km or miles by locale).
  3. Optional map view. A Show map toggle renders an interactive map with one pin per location and a marker at the reference. Clicking a pin highlights the corresponding row.
  4. Confirm bar. Clicking a row or marker previews the choice in a sticky bar at the bottom. The choice is only committed when the customer clicks Confirm selection.

A small crosshair icon next to the Step 1 button is a one-shot shortcut: clicking it snaps to the nearest pickup location and commits immediately, without opening the modal — handy on mobile.

If you've configured types on your pickup locations (see Custom Pickup Locations), customers also see filter chips for those types, each labelled with its location count.

Once a location is confirmed, the Step 1 button updates to show the chosen location's name and the customer can move on to Step 2 (product selection).

Confirming the selection​

Once the customer has made their selection:

  1. Click the Confirm Selection button
  2. The selection is saved and the shell product is automatically added to the cart
  3. The customer is taken directly to the standard Shopify checkout

The customer only checks out and pays for the shell product. The selected items will be added to the subscription automatically after the order is placed.

What the customer sees at checkout​

Because only the shell product is on the order, the checkout summary shows it at its own price — often €0.00. The shell line carries a short note explaining what that covers:

LineShows
Due todayWhat the shell product itself costs
Charged onThe date of the first subscription order
Your itemsThe products the customer picked

A long selection continues across numbered lines — Your items (1/2), Your items (2/2).

Why the note shows no future amount

The note names the picked products rather than quoting the upcoming charge. Introductory discounts and other subscription discounts are applied to the billing cycle after checkout, so an amount shown at this point would be wrong for exactly the customers who were promised a discount.

The note is removed from the subscription once the order is placed, so it doesn't reappear on renewal orders.

Variant switching​

If the shell product has multiple variants with different configurations, the selector dynamically updates when the customer switches variants. For example, switching from a "Small Box" (Free Mode, 5 items) to a "Large Box" (Paid Mode, €30 minimum) will update the progress bar and confirm button behavior accordingly.

Billing and pricing​

ModeHow items are added
FreeAdded as free one-time items at zero cost
PaidAdded at their regular storefront price
UnlimitedAdded at their regular storefront price
  • The shell product is always charged at its regular price (or with any subscription discount configured in the selling plan)
  • This is the same mechanism used when customers add items through the customer portal

Next billing date calculation​

The selector calculates and displays the customer's next billing date based on the selling plan's delivery policy. Cutoff days are also respected — if the customer subscribes too close to the next anchor date, they will be scheduled for the following cycle.

Known Limitations​

  • Accelerated checkout is not supported. Customers must use the standard checkout flow. Accelerated checkout via "Buy it now" button will not carry cart attributes through to the order, which would result in the product selection being lost
  • 50-product limit per collection. Shopify's Liquid returns at most 50 products from a collection without pagination, so each configured collection displays up to 50 products in the selector. If a collection has more, consider splitting it into multiple smaller collections
  • Grouping only sees the products the selector loaded. Headings are built from the products actually shown, so anything beyond the per-collection limit is missing from its group. A product that sits in two configured collections is grouped by whichever collection comes first

Troubleshooting​

Selector not appearing on the product page​

Possible causes:

  1. The product does not have the zubs-main-product tag
  2. The block has not been added to the product page template in the Theme Editor

Solution:

  • Verify the product tag in the Shopify admin
  • Open the Theme Editor and confirm the block is present and collections are selected

No products shown in the selector​

Possible causes:

  1. The configured collections are empty or contain only unavailable products
  2. "Show unavailable items" is turned off and all products are out of stock
  3. All products in the collection fall outside the availability schedule for the next billing date

Solution:

  • Check that the collections contain active, in-stock products
  • If using availability schedules, verify the date ranges include the next billing cycle

Selection not carried through to the subscription​

Possible causes:

  1. Customer used the accelerated checkout ("Buy it now")
  2. The cart attribute was cleared before checkout (e.g., by another app or script modifying the cart)

Solution:

  • Ensure customers use the standard checkout flow
  • Check if other apps or scripts are modifying cart attributes

FAQ​

Can I use this alongside the customer portal product selection? Yes. The Initial Product Selector only sets the items for the first billing cycle. For any future cycle, customers use the customer portal to manage their product selection as usual.

What happens if a customer doesn't select any items? The subscription is created normally without any pre-selected items. The customer can add items later through the customer portal.

Can customers change their selection after confirming and checking out? Yes, as long as the recurring subscription order hasn't been processed yet. They can simply head to the customer portal to make these changes.

Which mode should I choose?

  • Use Free Mode if you want to include a set number of items at no extra cost to the customer (e.g., a "5-item free box" as part of a subscription)
  • Use Paid Mode if customers are paying for their selected items and you want to enforce a minimum order value
  • Use Unlimited Mode if customers are paying for their selected items with no restrictions on quantity or total