How bundle rules work in the bundle configurator

Bundle rules limit choices in the bundle configurator of an online store based on other bundle options. The rules are stored in the bundle option JSON data, and each rule connects the controlling option to the option whose product features are being restricted. You can review the rules in the admin panel, but they cannot be edited as form fields.

Open the bundle product rules in the Control Panel

The rules for a package product can be found on the product's Package tab. Open Products at /products , select the package product, and open Package . In the Options section, select the package option you want to review. The rule data is displayed in JSON format with the option, along with the message Rules will be preserved. Editing requires an explicit rule update.

Changes to the package option type, option code, mandatory, order, optional, and localized names are saved automatically. These changes do not replace the existing rule JSON because the UI refresh request does not contain rules. The rules for the new option start as an empty list [] .

Identify the controlling option and the limiting option

The controlling option of a package rule is named in sourceOptionCode field with its internal option code. For example, option_63 could be a frame size option whose selected quantity controls the allowed products of another option. The rule is stored in the target option whose linked products' length, width, height, or weight you want to limit; in the example, the target option might be option_62 .

The option code is an internal identifier for package requests and integrations. If a code is not provided when creating a new option, the system generates a value in the format option_<id> . Always use the visible Option Code value when checking rules, as the title is localized customer text and not a stable rule reference.

Select the rule type and the amount to calculate

The package rule type specifies how the calculated threshold value is compared to the target product field. min_field_by_stack sets the minimum value, max_field_by_stack the maximum value, and exact_field_by_stack the exact value. The choices of the controlling option are counted using countMode value: selected_count counts the selected products, and selected_qty counts their selected quantities.

The target field is specified by targetField value. Supported technical fields are products_length , products_width , products_height , and products_weight . The package interface provides the online store with both rules value of the option and the length, width, height, and weight information of the linked products. Therefore, the values in the rules must match the same fields and units that the product data in question uses.

Calculate the stack limit

The stack-based computedValue threshold for package rules is calculated as base + max(count - 1, 0) * perIntermediate + (count > 0 ? last : 0) . base is the base value of the stack, perIntermediate increments the value for each selection after the first, and last increments the effect of the last item when there is at least one selected product.

If base is 40, perIntermediate is 20, last is 22, and the computed quantity is 3, the result is 40 + 2 * 20 + 22 = 102 . With a quantity of 4, the corresponding computedValue is 40 + 3 * 20 + 22 = 122 . When the computed quantity is 0, the intermediate and final additions are not used. Check each number against the actual dimensions or weight of the product; for example, a field value of 2400 must be interpreted in the actual unit of that field. An incorrect base value or unit can allow an incorrect combination or prevent a valid selection.

Combine multiple package rules

Multiple bundle rules for the same target option are applied together using the AND principle: the target product must meet all the rules. For example, a minimum and maximum rule can form an allowable measurement range. If any one condition is not met, the target product is not eligible for the current bundle combination.

The bundle configurator can disable an invalid product and clear a previously made selection if a change to the dominant option makes the selection illegal. Therefore, also test the order in which the customer first selects the target product and only then changes the quantity or selection of the dominant option. This ensures both deactivation and cancellation of the previous selection.

Only edit rules with an approved maintenance path

Package rules are displayed as read-only JSON in the Package tab of the Control Panel. There is no rule line addition, rule type selection, JSON view toggle button, or copy function. Do not replace JSON with other fields in the product, and do not infer the structure of a new rule based solely on the visible example. Editing a package rule requires an approved maintenance path.

Test the package rule in the online store

Bundle rules are tested in the bundle configurator with a product with known dimensions or weight and a controlling option whose code matches sourceOptionCode value. Start with a quantity of 0 or one option, increase the quantity to at least two, and compare the calculated threshold value to targetField values of the target products. Check the result according to the minimum, maximum, or exact condition, and the combined effect of all concurrent rules.

If all products remain selectable, check the option codes, the rule storage for the target option, countMode , targetField , and the JSON structure. If all products are disabled, check in particular the units, null values, and base , perIntermediate , and last numbers. If the previous selection remains in effect as against the rules, save the test selection order and the JSON values used for support investigation.

Identify the technical storage format of the rules

Bundle rules are stored in the database in catalog_product_bundle_option.rules field. The field is LONGTEXT , can be NULL , and the database checks the JSON for validity. The dashboard's read service converts the missing value to an empty list [] and returns both the parsed rules list and the original JSON string.

The e-commerce bundle response associates rules with an option and returns products in linked_products list. The generic name _field_by_stack aggregates the min, max, and exact types, but type value to be stored must be the complete rule type. The JSON structure, option codes, and target fields form a single contract; valid JSON alone does not prove that its rules can be evaluated.

Use package rules in a controlled manner

The purpose of bundle rules is to prevent impossible bundle combinations based on dimensions, weight, or selection quantity before the order is created. Dynamic computedValue allows the limit of the same target option to change with the selections of the controlling option, so a separate hard-coded combination is not needed for each quantity. By ANDing multiple conditions, you can limit both the minimum and maximum dimensions at the same time.

Implementing a package rule requires stable option codes, correctly populated product properties, and an e-commerce test with all thresholds. Document sourceOptionCode , countMode , targetField , calculation parameters, and expected result used. This way, the rule can be checked even if the package option title, linked products, or selection order change later.