Variations

Product version: 1.0.0+1 Last updated: 2026-08-03 Audience: Tenant users with product:variant:read (mutations use product:variant:*)

A. What Are Variations?

A Variation defines a dimension along which a product can have multiple variants. Variations are the building blocks of configurable products — products that come in multiple flavors, sizes, colors, materials, or any other differentiation.

Common variation examples:

Variations are optionally scoped to a category. When a variation has a category_id set, it only appears for products in that category. Unscoped variations (with category_id = null) are available to all products.

Note: A variation without a category association is a global variation and can be used across any product in the tenant.

B. Viewing the Variations List

1. Go to Product Catalog > Variations from the main navigation.
2. The variations list shows all variations in your tenant, paginated at 10 per page.
3. Each row displays:

Use the Category filter to show only variations scoped to a specific category.

C. Creating a Variation

Required permission: product:variant:create

1. Go to Product Catalog > Variations.
2. Click Add Variation (the "+" button).
3. Fill in the form fields:

4. Click Save.

The variation appears in the list. You can now add options to it (see Creating Variation Options).

Tip: Plan your variation names carefully. They appear in product item configuration selectors and in the UI. Consistent naming (e.g., always singular) creates a better experience.

D. Creating Variation Options

Required permission: product:variant:create

A variation is only useful once it has options — the specific values that users select when configuring a product item.

1. Open the variation from the variations list by clicking its Name.
2. In the Options section, click Add Option.
3. Enter the option Value (e.g., "Red", "Small", "Cotton").
4. Optionally set a Display Order to control position in dropdowns.
5. Click Save.

Repeat for each option value you need.

Tip: Add all options for a variation before creating product items. This ensures all variation combinations are available when configuring items.

E. Editing Variations

Required permission: product:variant:update

1. From the variations list, tap a variation row to open its options list page.
2. Click the Edit button (pencil icon).
3. Modify the fields:

4. Click Save.

Warning: Changing a variation's name or category scope affects all product items that use this variation's options. Existing item configurations remain intact, but the variation name updates everywhere.

F. Associating Variations with Categories

Variations can be associated with a category at creation or edit time. This scoping determines which products can use the variation.

How scoping works

Use cases for scoping

• Clothing department: Scope "Size" and "Color" to the "Clothing" category. Products in "Electronics" won't see these variations.
• Electronics department: Scope "Storage Capacity" to "Electronics > Computers". Only computer products will show this variation.
• Global: "Material" can be global if used across furniture, clothing, and accessories.

Checking a category's variations

1. Open the category detail page (see Categories).
2. The Variations section lists all variations scoped to that category.
3. Variations inherited from parent categories are also shown (with an "inherited" indicator).

G. How Variations Create Product Item Configurations

Variations and their options combine to create product item configurations. This is how you represent a specific variant of a product.

The process

1. Define variations — Create the dimensions (e.g., "Color", "Size").
2. Define options — Add values for each dimension (e.g., "Red", "Blue", "S", "M", "L").
3. Create product items — For each unique combination, create one product item and select the matching options. You can update an item's variation configuration later if needed.

Configuration example

Given: - Variation: Color → Options: Red, Blue - Variation: Size → Options: S, M, L

The product would have 6 possible items (2 colors × 3 sizes):

Database mapping

Each product item links to its variation options through the product_configurations junction table (ProductItemConfiguration). For the TSH-RED-S item:

The system enforces that each combination of variation options is unique per product — you cannot create two items with identical configurations.

Previous: Categories Next: Variation Options

Related: Overview · Products · Items · Brands

See also: Tenant Owner Manual · Employee Manual