Workflow Playbook
Product Variant Operations
Variant-level field rules, SKU behavior, option validation, and parent synchronization.
Audience: Inventory and master-data administrators.
Collections and Responsibilities
Product Variants
productVariant
Atomic inventory and pricing unit used by sales and purchases.
Products
product
Parent model that defines valid option names and receives hasVariants updates.
Workflow Timeline
Step 1
Step 1: Create or generate variant under a product
Every variant must reference a product and cannot be moved to another product later.
Step 2
Step 2: Validate options and identity fields
Option names must exist on product options; variantSku is generated if empty.
Step 3
Step 3: Save operational values
price, costPrice, and stock are maintained at variant level for downstream transactions.
Step 4
Step 4: Sync parent flags
Non-default variants mark product.hasVariants=true. Deleting last real variant resets it to false.
Field Guide (Required vs Optional)
| Field | Requirement | Behavior |
|---|---|---|
Product product | Required | Required relationship; reassignment is disabled on update. |
Variant SKU variantSku | Required | Auto-generated and de-duplicated when missing. |
Variant Option Name variantOptions[].name | Conditional | Must match a defined product option key. |
Variant Option Value variantOptions[].value | Conditional | Required for each option row. |
Display Name displayName | Auto / System | Generated from product + options but can be adjusted. |
Pricing & Inventory price, costPrice, stock, inStock | Optional | Commercial and inventory controls at variant level. |
Default Variant Flag isDefault | Auto / System | Hidden technical flag for simple-product placeholder variant. |
Decision Scenarios
If this happens
Variant option key is invalid
Save is blocked by validation to protect product-option integrity.
Timing: beforeValidate on productVariant.
If this happens
isDefault variant is updated
Product price/cost/stock/inStock sync back from that variant.
Timing: afterChange on productVariant.
If this happens
Real variant is saved
Parent product is flagged as hasVariants=true.
Timing: afterChange on productVariant.
Automatic Side Effects
- Variant SKU generation uses product SKU + option values and resolves collisions.
- Display name can be auto-generated from option combinations.
- Default variants do not count as real variants for hasVariants logic.
Operational Controls
- Keep option taxonomy stable before bulk variant generation.
- Use variant stock as the ERP source of truth for planning and reconciliation.
- Avoid direct edits on technical isDefault records except controlled simple-product operations.