BYOB validation rules: control what shoppers can pick in a Build Your Own Bundle

Why use validation rules

A Build Your Own Bundle (BYOB) lets shoppers choose their own items. Sometimes you need a bit more control over those choices. Validation rules let you decide:

• How many items in total a shopper picks
• Whether repeats are allowed (for example, 3 different items instead of 3 of the same)
• How many picks come from each section (for example, at least 2 snacks, no more than 2 drinks). This one is now set in the app, see below.
• A cap on specific products (for example, only one premium item per box)

Shoppers see these limits live on the product page as they build their bundle, and the add-to-cart button tells them what is still missing.

Examples of what you can do

How to set it up

Section limits are set in the app. The other rules are saved as a short piece of code in a metafield on your bundle product, which you can add yourself in the Shopify admin.

Step by step

1. In your Shopify admin, go to Products and open your BYOB bundle product.
2. Click the pack variant you want to add rules to (for example, "3-pack").
3. Scroll down to Metafields and find Simple Bundles BYOB validations.

4. Paste the rule code for your setup (see the examples below) and edit the numbers and section names to match your bundle.
5. Click Save.
6. Repeat for each pack variant that needs rules.

Before you paste

• Keep the total in sync. If you set a total item count in the rules, make sure it matches the pack size (a 6-pack should say 6).
• Copy the code exactly. A typo like "maximum"    instead of "max"    means none of the rules will apply. Shopify will usually show an error in the console when you save if something is wrong.

Rule code for each example

Snack box: any 3, all different

{ "rules": [
  { "type": "itemCount", "count": 3 },
  { "type": "perItemMax", "max": 1 }
] }

Office bundle: one desk, one base, one chair

No code needed. Create sections named Desks, Bases and Chairs, turn on Set quantity for each one, set it to exactly 1, and use a 3-item pack.

Mixed box: 6 items, 2 to 4 snacks, up to 2 drinks, no more than 2 of any one item

In the app, set the Snacks section to a range of 2 to 4 and the Drinks section to a maximum of 2, with a 6-item pack. Then add this to the metafield for the "no more than 2 of any one item" part:

{ "rules": [
  { "type": "perItemMax", "max": 2 }
] }

Premium cap: only one Ribeye per box

{ "rules": [
  { "type": "itemMax", "productId": "123678901234567", "max": 1,
    "message": "Only one Ribeye per box" }
] }

Replace the number with your own product ID. To find it, open the product in your Shopify admin and copy the number at the end of the page URL (for example, admin/products/12367890123456   ). To cap a single variant instead, use "variantId"    with the variant's ID from its URL.

3-pack and 6-pack with different rules

Rules for totals, duplicates and product caps are saved per pack variant, so add a separate version to each one. Section limits need a single pack size, so if each size needs its own section limits, create a separate BYOB for each size.

Always include one specific item

No code needed. Put the required product in its own section (for example, "Included item" with only your Huggie Hoops in it), turn on Set quantity and set it to exactly 1. Put the charms in a second section. For a 7-item pack, shoppers pick the hoops plus 6 charms.

The shopper still clicks to add the required item, but they can't check out without it.

Custom messages (optional)

You can add a "message"    to per-item rules and product caps to show your own wording to shoppers. Don't add a message to the itemCount    rule, as this stops all rules from working. Messages only show in your store's main language, so if you sell in multiple languages, leave them out and the built-in translated messages will be used.

Checking it works

1. Open your bundle's product page on your store.
2. Refresh the page so it picks up your new rules.
3. Try picking items. You should see section counters, "Max quantity added" on capped items, and the add-to-cart button showing what's still needed.
4. Try breaking the rules on purpose (for example, adding too many from one section) to confirm the limits stop you.

If nothing changed: the rules probably weren't accepted. Double-check the code for typos.

If the add-to-cart button never turns on: the rules may be impossible to meet together, for example section minimums that add up to more than the total. Adjust the numbers and save again.

To troubleshoot issues, open your browser's developer console on the product page. If the rules were rejected, you'll see a warning starting with [Simple Bundles BYOB]    explaining why. No warning means the rules loaded. Note that a product cap with a wrong product ID won't show a warning; the cap just won't apply, so test it by adding that product.

What it can't do yet

• Section limits need a single pack size. They can't be set when the bundle has several pack sizes or value tiers.
• The total is always an exact number. You can't set a range like "pick 4 to 8 items".
• No per-item minimums. You can cap how many of an item shoppers pick, but not require a minimum of each.
• No automatically added items. Every item is picked by the shopper. The "Always include one specific item" setup above is the closest option.
• No conditional rules, like "only allow Y if X was chosen".
• Rules are checked on the product page only. They are not checked at checkout, and they don't apply to Shopify POS.
• Custom messages are shown in your main store language only.

Need a hand?

If you need help setting up your rules, reach out to our support team and we'll be happy to set them up with you.