Product Attributes: Variants, Option Types, and Rules

The section Attributes or Separate Products explains which approach fits when.

The list shows how many products and values are associated with each attribute. Click to enlarge.

1. Create an attribute: Click the “Insert” tab, enter a name for each language, and save. A comment helps distinguish between attributes with similar names (e.g., “Clothing Size” and “Shoe Size”).
2. Create values: Use “Edit Attribute” and the “Attribute Values…” tab to create the values and determine their sort order. This order applies wherever you haven’t specified a custom order within the product.
3. Set defaults: In the “Edit Attribute” tab, under “Preselection when adding to products,” specify the settings with which the attribute is added to a product: required field, option type, option image display, and item number sorting. This saves time when working with many products.

Default settings that determine how the attribute is added to new products. Click to enlarge.

The values and their sort order. Click to enlarge.

Additional functions on this page:

• Listing Status: If set to “visible,” “Show only” values for this attribute will also appear in the product list.
• Merge: “Merge Option” and “Merge Option Value” clean up duplicate attributes and values, such as those created after an import.
• Clean Up: “Delete unused product attributes” removes attributes without a product; “Delete unused values” does the same for values.
• Edit Additional Values Advanced Feature Functions: Custom number columns per value for pricing formulas; see Pricing Formulas.

Toolbar and the expanded “Color” attribute with its values. Click to enlarge.

The toolbar

• Expand/Collapse (double arrow on the left side of the toolbar): opens or closes all attributes.
• Add a Single Attribute (green plus sign): Add an attribute with selected values.
• Attributes and Attribute Quick Selection (checkmark icon): Select multiple attributes and values at once.
• Add Block Advanced Feature Functions: Organize attributes on the product page into sections with headings.
• (Number) Rules Advanced Feature Functions: the product’s rule set.
• Select Primary Option: The attribute whose values appear as tiles in the product list; see Primary Option.
• Configure extension types (gear icon): Order and display of the “Purchase Price,” “MSRP,” and “Related Products” buttons below each value.
• Product Attribute Profiles (selection on the right): A saved set of attributes that you assign to the product. The pencil icon next to it opens the profiles for editing.

Settings per Attribute

Six option types on a product page: Radio (Button), Select, Radio, Text, Textarea, and Checkbox (Button). Click to enlarge.

Where the selection appears on the product page

If there are up to three selection attributes, the selection appears in the price box next to the image; if there are more, it appears below under “Please make a selection.” You can set this limit under Settings → Design → Product Detail View → Maximum number of options in the price box (product info page) (DISPLAY_MAX_OPTIONS). On smartphones, the selection is always displayed in the price box.

Define Input Fields More Precisely (Text Option Type)

For the “Text” option type, the “Details” field appears next to the attribute. The button next to it (Input Help for HTML Attributes) opens the “Select Text Input Field Parameters” dialog. There, you specify:

• Data type: text, number, date, color, or email. For “date,” a calendar appears; for “number,” a field with plus and minus signs appears.
• Minimum and maximum lengths for text, minimum and maximum values and increment for numbers. The store displays these limits below the field.
• Note regarding empty fields (placeholder text) and predefined content.

The dialog box writes the information into the “Details” field, e.g., maxlength=20;placeholder=z. B. Teamname. You can also enter it there directly.

Custom text: maximum 20 characters, with placeholder text. Click to enlarge.

Number fields with limits. The material surcharge is calculated based on the entries. Click to enlarge.

Size with stock per value and surcharge for XXL. The option price is shown net in the field. Click to enlarge.

The value’s stock is only deducted if Settings → Checkout → Inventory → Adjust inventory (STOCK_LIMITED) is enabled. With “Set sold-out products to inactive” (SOLD_OUT_SET_INACTIVE), the store deactivates a value as soon as its stock falls below 1.

How to create an attribute group

1. Assign the first attribute to the product, e.g., “Color.”
2. Click the green plus sign in the header of this attribute (tooltip: “Add option value to option group”) and select the second attribute, e.g., “Size.” The second attribute must not yet be assigned to the product individually; otherwise, it will not appear in the list.
3. Click “Add Value.” The store will prompt you for the values one after the other—first the color, then the size. “Add All Values” creates all combinations at once (up to just under 200 combinations).
4. For each combination, enter the item number, GTIN, inventory, and, if necessary, the image and price, then save by clicking “Update.”

Step 2: Select the second attribute. Click to enlarge.

Step 3: “Add All Values” creates all combinations. Click to enlarge.

Each combination has its own row with an item number, GTIN, and stock level. Click to enlarge.

Display in the store: Configurator mode

There are five display options for attribute groups: Select, Radio, Radio (Button), Radio (Popup), and Cart. If a group contains two or more attributes, the store displays each attribute as its own field (configurator mode). The fields are interdependent: Size becomes selectable only after a color has been chosen (“Please select a color first”), and combinations that do not exist or are disabled appear with ⁽¹⁾ and are locked.

Navy selected: The Navy/XXL combination is disabled and therefore locked. The image of the combination appears in the gallery. Click to enlarge.

You can set the threshold under Settings → Design → Product Listing → Option group size at which the split view (“configurator mode”) should be displayed (OPTIONS_SPLIT_NUM, default 2). Below this threshold, the store displays the group as a single field with entries such as “Black / M.” You can switch the summary below the fields on or off with “Option group summary in split view” (OPTIONS_SPLIT_SUMMARY).

Enter quantities by size, then click “Add to cart” once. Click to enlarge.

Result: two items in the shopping cart. Click to enlarge.

• Only one “Cart” attribute is allowed per product. Use the attribute to which item numbers and stock levels are linked.
• A “Cart” attribute cannot be a required field; the checkbox is not displayed.
• Each row displays the value, its item number, the delivery information, and the price including any surcharge, along with the value’s image, if it has one.

In the product list, the values of the primary option appear as tiles below the product. Click to enlarge.

• Product list: The values appear as tiles with an image and name. Clicking on a tile opens the product page with that value preselected. The maximum number of tiles that can appear is set under Settings → General → Maximum Values → Maximum number of primary option images and names in the listing (MAX_PRIMARY_OPTIONS_IN_LISTING).
• Google Feed: The feed for Merchant Center splits the product into individual entries based on the primary option, e.g., “Organic T-Shirt Classic - Color: Navy,” each with a price, image, and link to the preselected value. Only values with their own item number are split.

Attributes can be used as filters on category and search pages; this applies to selection attributes as well as “Show only” and “Hide” attributes. You can configure which attributes appear as filters under Products → Product Filters. The guide Search the Store describes how the store filters and searches.

If you work with families (master/slave), the master inherits the filterable attributes of its slaves so that the family can be found in the filter along with all its variants.

You set up product families in the product’s “General” tab: “Product Group (Master/Slave Products),” “Master Product,” and “Slave Display Type” (Listing, Select, Radio, Radio (Button), or Radio (Popup)). Both can be combined—for example, one family per color with the “Size” attribute in each slave.

You can open it in the “Features” tab using the “(Number) Rules” button. The “Manage Rules for …” dialog lists all rule blocks for the product. Each block consists of one or more conditions and one or more reactions.

Four rule blocks for the T-shirt with custom print. Click to enlarge.

One block: If color = Black, then hide the “Black” print color. Click to enlarge.

Conditions

• Customer selection/attribute entry: the attribute being checked. There are also “--Number of items--” (the quantity in the shopping cart) and “--No condition (always execute)--”.
• Comparison operators: < (less than), ≤ (less than or equal to), = (equal to), ≠ (not equal to), ≥ (greater than or equal to), > (greater than). This also allows you to check text entries and numbers, such as “Width > 300.”
• Comparison: a fixed value (“--Select Value--”), a formula (“--Enter Formula--”), or another attribute.
• Logic: For each block, either “All Rules” (and) or “At Least One Rule” (or) applies. If you need both, create two blocks.

The Seven Reactions

The “Immediate reaction without waiting for a click on the shopping cart” toggle (arrow icon next to the reaction) triggers the reaction as soon as the customer makes a selection. Without it, the store checks only when “Add to cart” is clicked—which is suitable for error messages. The server evaluates the rules, not the browser, so they cannot be bypassed.

Black Shirt: The print color “Black” is hidden. Click to enlarge.

Size XXL: The warning message appears at the top of the page. Click to enlarge.

• Status: Each block can be disabled individually. If a block cannot function in this state, the store saves it as disabled and reports this.
• Copy and Paste Rules: Transfers rules to another product via the clipboard, either as an addition or a replacement.
• Via API: Rules can also be read and written via the xoPort API (options_rules field).

Formula in the option price: Area in m² multiplied by price per m². Click to enlarge.

How the example works

The advertising banner has the text fields “Width in cm” (attribute ID 10) and “Height in cm” (ID 11), both with the data type “number.” For the value “PVC tarpaulin 510 g/m²,” the option price is:

ov10*ov11/10000*12.52

Width times height divided by 10,000 equals the area in m², multiplied by €12.52 net (€14.90 gross) per m². For 200 × 100 cm, that is 2 m², so the surcharge is €25.04 net or €29.80 gross. The attribute ID is listed under “Product features.”

200 × 100 cm in PVC: €9.90 base price plus €29.80 area price. Click to enlarge.

• + - * / ( ) and numbers with a period as the decimal separator (12.52, not 12,52) are allowed. Division by 0 results in 0.
• Formulas calculate using net prices, just like the option price itself.
• The “Weight” field also accepts a formula, such as weight per m².
• Additional values are managed under Products → Product features → “Edit Additional Values”: a table with separate columns for each value, such as price per m² and weight per m² for each material.

Practical Examples

• CSV: Under Tools → xoPort CSV Import/Export Manager, there is a port called “Product Options (Attributes)” for attributes, values, prices, item numbers, and inventory levels.
• REST API: The product import accepts attributes in the field options and creates missing attributes and values. The export provides individual attributes in options and attribute groups with all combinations in option_groups. Rules are specified in the field options_rules. Details are available in the API documentation for Products.
• Inventory Management: “Show only” attributes are well-suited for data from your inventory management system because they do not affect the ordering process.

• When saving a product: The store rejects a required attribute without an active value or a preselection set to an inactive value, displaying a message.
• When restoring a shopping cart: If a customer logs in and an older shopping cart is retrieved, the store checks the saved selections. If a value no longer exists, it points this out instead of calculating the item incorrectly.
• At checkout: Under Settings → Privacy → GEO IP Policies → Check for missing attribute selection at checkout (CHECKOUT_ATTRIBUTE_GUARD_MODE), you can specify what happens when an item lacks a required attribute: off (no check), log (log only; default), or block (block checkout). Such items are not created via the product page, but rather through the upload of an item list, for example. If a saved selection is no longer available for order, the checkout process will always block the transaction.

• Product stock is too low: The stock level is determined by the lower of the product’s stock and the value’s stock. If the product’s stock is 0, the variant is considered out of stock, even if the value’s stock is 50.
• Second attribute missing when grouping: An attribute that is already assigned to the product individually cannot be added to the group. Remove it first.
• Option price is net: If you want a €2 gross surcharge, enter 1.6807 for 19% VAT or use the calculator next to the field.
• Comma in formulas: In formulas, only the period is used as the decimal separator.
• No selection enforced: Without “Please select,” the first value is already selected by default. For sizes, this can lead to incorrect orders. Enable both “Please select” and “Required field” together.
• Duplicate attributes after imports: “Größe” and “Groesse” are treated as two separate attributes by the store. Merge them under “Product features.”
• Item Numbers in the Google Feed: The values for the primary option require complete item numbers; see Primary Option.
• Converting to an attribute group: When grouping, the group’s existing values will be lost. Back up item numbers, GTINs, and inventory levels beforehand, for example via a CSV export.

1. Create attributes and values under Products → Product features, then sort the values.
2. Decide: individual attributes, attribute group, or family?
3. Assign attributes in the “Features” tab and set the option type, “Please select,” and the required field.
4. For each value, enter the surcharge, item number, GTIN, inventory, and image.
5. Set the product’s inventory at least as high as the highest value inventory.
6. Specify the primary option if you want the variants to appear in the product list and in the Google feed.
7. If necessary, create rules and formulas Advanced Feature Functions.
8. Save, then click through each selection once on the product page: Price, Item Number, Image, and Stock.