Skip to main content

Build-a-Box Subscriptions

Set up a subscription model where customers select products per billing cycle, with optional minimum order thresholds and automatic skipping of cycles that don't meet requirements.

Overview​

Build-a-box subscriptions (also called build-your-box) let customers subscribe to a "shell" product and then choose the actual items they receive each cycle. This model is common for meal kits, snack boxes, beauty boxes, and similar curated subscription products.

How it works:

  1. Customer subscribes to the shell product (the "box") on your storefront
  2. The initial checkout costs nothing thanks to a 100% subscription discount
  3. A sequential flow adjusts the discount after the first order
  4. Each billing cycle, the customer selects their items in the customer portal
  5. If no items are selected, or the selected items don't reach the minimum order threshold, the cycle is automatically skipped

This guide walks through the complete setup, from product configuration to automatic billing cycle management.

Prerequisites​

Before setting up a build-a-box subscription, ensure you have:

  • A Shopify store with Zubs installed
  • Access to the Zubs merchant portal
  • Basic familiarity with Shopify product management (tags, metafields, collections)

Setup​

Step 1: Configure the shell product​

The shell product is the subscription "container" that customers purchase. It represents the box itself, not the individual items inside it.

  1. Create a product in Shopify (e.g., "Monthly Snack Box", "Weekly Meal Kit")
  2. Add the zubs-main-product tag to the product
  3. Assign a selling plan (subscription plan) to the product
  4. Set the product price to any value (it will be discounted to zero at checkout)
tip

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 costs nothing and only the first "real" billing cycle charges the customer.

Step 2: Configure product metafields​

Set up metafields on the shell product's variant(s) to control the build-a-box behavior. Navigate to the variant in Shopify admin and configure the following custom metafields:

Free item limit (optional)​

Metafield: custom.free_subscription_products_limit Type: Integer Example value: 5 or 10

This controls how many items the customer can select for free each cycle. Different variants can have different limits (e.g., "Small Box" = 5 items, "Large Box" = 10 items).

Customers can add more items than this on each cycle as paid items. To stop them at the limit, turn off Add Paid Extras.

For detailed setup of the storefront product selector, see the Initial Product Selector guide.

Minimum order threshold (optional)​

Metafield: custom.minimum_order_amount_for_cycle Type: Integer Example value: 10 (for a minimum of 10 in your store's currency)

This sets the minimum total order value for a billing cycle. If the total value of all items (including shipping) in a cycle is below this threshold, the cycle will be automatically skipped. The total is measured before any discounts are applied.

Important notes:

  • The value is in your store's base currency unit (e.g., 10 = 10 EUR, 10 USD, etc.)
  • The threshold applies to the entire cycle total: all line items plus shipping costs, before discounts -- a percentage discount on the cycle (for example an introductory discount) doesn't count against the minimum
  • Only integer values are supported (decimal values like 10.50 are truncated to 10)
  • If this metafield is not set, no minimum threshold is enforced and the cycle will not be skipped based on order value

Step 3: Set up product collections​

Create one or more Shopify collections containing the products that customers can choose from each cycle. These collections define the "menu" available in the customer portal.

  1. Go to Products → Collections in Shopify admin
  2. Create a new collection (e.g., "Build-a-Box Items", "Weekly Menu")
  3. Add eligible products to the collection

Tips:

  • Use multiple collections to organize by category (e.g., "Meals - Chicken", "Meals - Vegan", "Desserts")
  • The storefront selector shows a limited number of products per collection — see Known Limitations

Which products customers are offered​

Products are offered only when they are active, published to your Online Store sales channel, and available in your customer's market. Variants you hide from the Online Store aren't offered. The same applies everywhere Zubs offers products: the customer portal, the default item fill, product recommendations, and the upsell customers see before they subscribe.

A variant that's out of stock stays in the customer portal's picker, shown as unavailable, so customers can't pick it. The default item fill, recommendations and the upsell skip it.

The Available Products preview lists the products and variants in your collections that aren't active or published to your Online Store under Not offered to customers, with the reason for each. It doesn't check markets.

Optional: Configure availability schedules​

If certain products should only be available during specific time periods (e.g., weekly rotating menus), set an availability schedule on the collection. Products in that collection then only appear during the periods you set, based on the customer's next billing date. Both dates are part of a period, and the billing date is judged on your store's own calendar day.

To edit a collection's availability schedule:

  1. In Shopify admin, go to Products → Collections and open the collection.
  2. Click More actions → Availability schedule.
  3. Choose when customers can pick products from the collection:
    • Only during the periods below — add a start and end date for each period.
    • Always (no restriction) — the collection is offered in every period.
    • Never — customers can't pick products from the collection.
  4. Click Save.

Periods that have ended stay in the schedule. The editor lists them under Show past periods, where you can still remove them.

To see the schedule on every collection page:

  1. Open any collection in Shopify admin.
  2. In the Blocks section at the bottom of the page, click + Block and select Availability schedule.
  3. Click the Pin icon next to the block, so it stays on collection pages for all staff.

The block shows the collection's current and upcoming periods. Click Edit schedule to open the editor.

If Zubs can't fully read a collection's schedule, the editor and the Available Products preview show a warning. Saving the schedule from the editor replaces it with what you set there.

Step 4: Enable collections in the merchant portal​

  1. Log in to the Zubs merchant portal
  2. Go to Settings → Subscription Features
  3. Enable Subscription Products Collection
  4. Select the collection(s) you created in Step 3

This ensures that when customers edit their billing cycle in the customer portal, they see products from the correct collections.

For more details on this setting, see Settings: Subscription Features.

While in Settings → Subscription Features, also consider enabling:

  • Edit Future Cycles -- allows customers to customize the contents of upcoming billing cycles in advance
  • Edit One-Time Products -- allows customers to add products to a single upcoming order

These features give customers the flexibility to manage their box contents for each cycle.

Customer Experience​

Initial checkout​

  1. Customer visits the shell product page on your storefront
  2. If the Initial Product Selector is configured, customers can choose their first box items right on the product page
  3. Customer proceeds to checkout -- the shell product costs nothing (100% subscription discount)
  4. After checkout, the subscription is created and the selected items are added to the first billing cycle

Managing each cycle​

For subsequent billing cycles:

  1. Customer logs in to the customer portal (customer account page)
  2. Opens their subscription and views upcoming billing cycles
  3. Selects products from the available collections for each cycle
  4. If a minimum order threshold is configured and the cycle total is below it, a warning banner is displayed:

"Your order total is below the minimum order amount of [threshold]. This cycle will be skipped unless you add more products."

  1. Customer adds or removes products until they're satisfied with their selection

Automatic cycle skipping​

Billing cycles are automatically skipped in two scenarios:

  1. All products are main products only -- if the cycle only contains the shell product (tagged zubs-main-product) and no additional items, it is skipped because there's nothing meaningful to ship
  2. Below minimum order threshold -- if a custom.minimum_order_amount_for_cycle metafield is configured and the total value of all items plus shipping is below the threshold, the cycle is skipped

When a cycle is not skipped (threshold is met or no threshold is configured), it is charged and fulfilled as a normal subscription order.

Fail-safe behavior

If the threshold metafield is missing or cannot be read, the cycle is charged (not skipped). This conservative default prevents accidental skips due to configuration errors.

Example Setup​

Here's a complete example for a weekly meal kit subscription:

ConfigurationValue
Shell product name"Weekly Meal Kit"
Shell product tagzubs-main-product
Selling planWeekly delivery, 100% subscription discount
Free item limit (custom.free_subscription_products_limit)5 (5 free meals per week)
Minimum order threshold (custom.minimum_order_amount_for_cycle)20 (minimum 20 EUR per cycle)
Collections"Meals - Classic", "Meals - Vegetarian", "Meals - Premium"

Customer flow:

  1. Customer subscribes to "Weekly Meal Kit" -- checkout is free
  2. Sequential flow sets discount to a lower value after the first order
  3. Each week, customer picks 5 meals from the available collections
  4. If the customer picks meals totaling less than 20 EUR (or picks no meals at all), that week's cycle is automatically skipped
  5. If the total meets or exceeds 20 EUR, the order is charged and fulfilled

Troubleshooting​

Cycle not being skipped when expected​

Possible causes:

  1. The custom.minimum_order_amount_for_cycle metafield is not set on the shell product's variant
  2. The cycle total (including shipping) is at or above the threshold
  3. The shell product does not have the zubs-main-product tag

Solution:

  • Verify the metafield value in Shopify admin
  • Remember that shipping costs are included in the total -- a cycle with low-value items but high shipping may still meet the threshold
  • Check that the product tag is correctly applied

Cycle being skipped unexpectedly​

Possible causes:

  1. The minimum threshold value is set too high
  2. Shipping costs are not being included in the calculation (contact support if you suspect this)

Solution:

  • Review the threshold value and adjust if needed
  • Check the cycle's total charge amount in the customer portal to understand what value is being compared against the threshold

Warning banner not appearing in customer portal​

Possible causes:

  1. The custom.minimum_order_amount_for_cycle metafield is not configured
  2. The cycle total already meets or exceeds the threshold
  3. The cycle is already skipped

Solution:

  • Verify the metafield is set on the correct variant
  • The banner only appears when the total is below the threshold and the cycle is not already skipped

Products not showing in customer portal​

Possible causes:

  1. Subscription Products Collection is not enabled in Settings
  2. The collections are not selected in the feature configuration
  3. The products aren't offered to customers: they aren't active, aren't published to your Online Store sales channel, or aren't available in the customer's market

Solution:

  • Go to Settings → Subscription Features and verify the collection configuration
  • Open the Available Products preview: its Not offered to customers list names each product or variant customers aren't offered, and why