QBM Product Variations

User Guide
With Shopify Integration Examples

1. Introduction

This guide explains how QBM handles products with variations (like different colors and sizes) and how to integrate with e-commerce platforms like Shopify.

1.1 What is a Product Variation?

A product variation is a specific version of a product that differs by one or more attributes. For example, a "Classic T-Shirt" might come in:

This creates 9 possible combinations (3 × 3 = 9 variations), each needing its own inventory tracking, UPC, and potentially different pricing.

2. How QBM Handles Variations

2.1 The Flat Model

QBM uses a flat model where each variation is stored as an independent item in the database. Variations are grouped together by sharing the same Product Name.

2.2 Example: T-Shirt Variations

Here's how a T-Shirt with color and size variations looks in QBM:

Product Name UpcSku (UPC) Color Size Stock Qty
Classic T-ShirtTSH-RED-SRedS25
Classic T-ShirtTSH-RED-MRedM30
Classic T-ShirtTSH-RED-LRedL20
Classic T-ShirtTSH-BLU-SBlueS15
Classic T-ShirtTSH-BLU-MBlueM40
Classic T-ShirtTSH-BLU-LBlueL35
Notice: All rows share the same Product Name "Classic T-Shirt" but each has a unique UPC (UpcSku) and tracks its own inventory.

2.3 Key Fields Explained

Field Purpose
Product NameGroups variations together. All variations of one product share the same name.
UpcSkuUPC for POS scanning. Must be unique for each variation in the database.
LookupCodeBarcode. Must be unique for each variation in the database.
ColorVariation attribute - free text field for color values.
ItemSizeVariation attribute - free text field for size values.
Brand / ModelVariation attributes - selected from predefined lists.

3. Advantages of QBM's Model

1. Simplicity

No complex parent/child relationships. Each item is self-contained with its own pricing, cost, and inventory. Easy to understand and manage.

2. Flexibility

Each variation can have completely different prices, costs, and profit margins. No restrictions on which attributes can differ between variations.

3. Independent Inventory Tracking

Each variation tracks its own quantity and cost. Stock movements are straightforward. FIFO/LIFO/Average costing works independently per item.

4. Fast POS Performance

Scan a UPC → immediate product match. No need to traverse parent/child hierarchies. Quick checkout experience.

5. Easy Reporting

Group by Product Name to see "total T-shirts sold" or drill down to "Red Medium T-shirts sold". No complex aggregation needed.

6. No Data Integrity Issues

Deleting one variation doesn't affect others. No orphan records or broken relationships to worry about.

4. Shopify Integration

4.1 Understanding the Difference

Shopify and QBM handle variations differently. Understanding this is key to successful integration.

Shopify (Hierarchical) QBM (Flat)
Product is the parent containerNo parent - all items are equal
Variants are children of a ProductEach variation is an independent item
Product.Title = "Classic T-Shirt"ProductName = "Classic T-Shirt"
Variant.SKU = "TSH-RED-M"UpcSku (UPC) = "TSH-RED-M"
Variant.Barcode = "012345678901"LookupCode (Barcode) = "012345678901"
Variant.Option1 = "Medium"ItemSize = "Medium"
Variant.Option2 = "Red"Color = "Red"

4.2 Mapping Rules

🔑 The Golden Rule:
Each Shopify Variant becomes one QBM Item.
Do NOT create a separate item for the Shopify Product itself.
  1. Product.Title → ProductName All variants of a Shopify product share the same ProductName in QBM.
  2. Variant.SKU → UpcSku (UPC) The Shopify SKU is stored in QBM as UpcSku (UPC). Must be unique.
  3. Variant.Barcode → LookupCode (Barcode) The Shopify barcode is stored in QBM as LookupCode (Barcode). Must be unique.
  4. Variant.Option1 → ItemSize (typically) First option is usually size. Map to QBM's ItemSize field.
  5. Variant.Option2 → Color (typically) Second option is usually color. Map to QBM's Color field.
  6. Variant.Price → UnitPrice Each variation gets its own selling price.

4.3 Complete Mapping Example

📦 Shopify Product:

Product ID7890123456789
TitleClassic T-Shirt
OptionsSize, Color

📋 Shopify Variants:

Variant ID SKU Barcode Option1 Option2
45678901234567TSH-RED-S012345678901SRed
45678901234568TSH-RED-M012345678902MRed
45678901234569TSH-BLU-S012345678903SBlue
⬇️

✅ Creates these QBM Items:

ProductName UpcSku (UPC) LookupCode (Barcode) ItemSize Color
Classic T-ShirtTSH-RED-S012345678901SRed
Classic T-ShirtTSH-RED-M012345678902MRed
Classic T-ShirtTSH-BLU-S012345678903SBlue

5. Uniqueness Rules

5.1 What Must Be Unique

Within your QBM database, the following must be unique for each item:

⚠️ Important Warning - Before Importing from Shopify:

Make sure all Shopify variants have unique SKUs and barcodes. If a SKU or barcode already exists in QBM for a different product, the import will fail with a duplicate error.

6. Best Practices

✓ Tip: Consistent Naming

Use exactly the same Product Name for all variations. "Classic T-Shirt" and "Classic T-shirt" (lowercase 's') would be treated as different products.

✓ Tip: SKU Convention

Use a consistent SKU pattern that includes the variation attributes. Example: PRODUCT-COLOR-SIZE (TSH-RED-M, TSH-BLU-L). This makes inventory management easier.

✓ Tip: Verify Before Sync

Before syncing inventory between Shopify and QBM, verify that SKUs match exactly. A mismatch could update the wrong product's stock.

7. Quick Reference Summary

Shopify Field QBM Field
Product.TitleProductName (shared by all variations)
Variant.SKUUpcSku (UPC; unique per item)
Variant.BarcodeLookupCode (Barcode; unique per item)
Variant.Option1ItemSize (typically)
Variant.Option2Color (typically)
Variant.PriceUnitPrice
Variant.InventoryQuantityQuantity (tracked per item)