littleshop/TEXT_IMPORT_GUIDE.md

LittleShop Text Import Guide - Variant Collections

Summary of Changes

The text import format already supports variant collections natively! The CSV import was incorrectly using multi-buys instead of proper variant collections.

Text Import Format (with Variant Collections)

Basic Structure

# Product Name; Variant Collection Name
<text>
Optional description here
</text>
category: CategoryName
price: BasePrice (optional when using variants)
weight: BaseWeight (optional when using variants)
unit: Unit
stock: StockQuantity

- Variant1Name; Price; StockLevel
- Variant2Name; Price; StockLevel
- Variant3Name; Price; StockLevel

Example: Weight-Based Product (Grams)

# Four whittteee; Weights - Standard
category: Flour
unit: Grams
stock: 100
- 28g; 700; 100
- 14g; 360; 100
- 7g; 190; 100
- 3.5g; 100; 100

Example: Unit-Based Product (Tablets)

# tablets - Vitamin-C; Single Units
<text>Dutch import</text>
category: Vitamins
unit: Unit
stock: 100
- 100; 150; 100
- 50; 80; 100
- 25; 50; 100
- 10; 30; 100

Key Differences: Variants vs Multi-Buys

Variants (Lines starting with -)

Format: - VariantName; Price; StockLevel Use Case: Different sizes, weights, or quantities of the SAME product Example: - 28g; 700; 100 (28g size for £7.00 with 100 in stock) Links to: Variant Collections ("Weights - Standard", "Single Units", etc.)

Multi-Buys (Lines starting with +) ❌ DON'T USE FOR THIS DATA

Format: + Name; Quantity; Price Use Case: Bulk purchase discounts (2 for £19, 3 for £25) Example: + Twin Pack; 2; 19.00 (Buy 2 items for £19) Not applicable: For single product variants

Variant Collections

You must create variant collections in the admin panel first:

1. Weights - Standard: For gram-based products (28g, 14g, 7g, etc.)
2. Single Units: For individual countable items (tablets, capsules)

These collections define the presentation format and UI behavior for variants.

Complete Import File

See: products_text_import.txt - Ready to use with 13 products properly formatted

Products Included:

• Flour Category (3 products): Four whittteee, double washed Flour, Chocolate infused
• Cereal Category (3 products): Cereal, Himalayan Cereal Blush, Cereal Rock
• Vitamins Category (5 products): Various vitamin tablets and organic options
• Herbal Category (2 products): Guarana products

How to Import

Option 1: Via Admin UI

1. Go to Admin → Products → Import (Text Format)
2. Upload products_text_import.txt OR paste content into textarea
3. Check "Replace All" if you want to delete all existing products first
4. Click Import Products

Option 2: Via API (if needed)

POST /Admin/Products/ImportText
Content-Type: multipart/form-data

textContent: [paste file content]
replaceAll: true

Important Notes

✅ DO THIS

• Use - prefix for product variants (different sizes/quantities)
• Link products to variant collections for consistent UX
• Use Unit for countable items (tablets, capsules)
• Use Grams for weight-based products
• Use "Replace All" checkbox to clear existing data before import

❌ DON'T DO THIS

• Don't use + multi-buys for size variants
• Don't use multi-buys at all (they're for bundle discounts)
• Don't forget to create variant collections first
• Don't import without checking "Replace All" if you want clean data

Variant Collection Setup

Before importing, create these variant collections in admin panel:

1. Weights - Standard

• Name: Weights - Standard
• Description: Standard weight-based product variants
• Used for: Flour, Cereal, Herbal gram-based products

2. Single Units

• Name: Single Units
• Description: Individual countable items
• Used for: Tablets, capsules, individual items

Field Reference

Field	Required	Description	Example
# ProductName; VariantCollection	Yes	Product name and variant collection	# Vitamin-C; Single Units
<text>Description</text>	No	Product description	<text>Dutch import</text>
category: CategoryName	Yes	Product category	category: Vitamins
unit: WeightUnit	Yes	Unit type (Unit/Grams/etc.)	unit: Grams
stock: Number	No	Base stock quantity	stock: 100
- Name; Price; Stock	No	Variant definition	- 28g; 700; 100

Weight Unit Options

• Unit - For individual items (tablets, pills, pieces)
• Grams - Standard metric weight
• Kilograms - Larger metric weight
• Pounds - Imperial weight
• Ounces - Imperial weight

Features Added

1. ✅ Replace All Option: Checkbox in text import UI (same as CSV)
2. ✅ Controller Support: replaceAll parameter added to ImportText action
3. ✅ Documentation: Updated UI hints to show variant collection format
4. ✅ Unit Support: Added Unit to the weight unit documentation

Files Modified

1. ProductsController.cs: Added replaceAll parameter to ImportText action
2. ImportText.cshtml: Added "Replace All" checkbox and updated documentation
3. products_text_import.txt: Created properly formatted import file

Testing

1. Create Variant Collections in Admin Panel:

   • "Weights - Standard"
   • "Single Units"

2. Import Data:

   • Go to Admin → Products → Import (Text Format)
   • Upload products_text_import.txt
   • Check "Replace All" if needed
   • Click Import

3. Verify Results:

   • Check Products page shows 13 products
   • Check each product has variants linked to correct collection
   • Verify variant pricing displays correctly

Migration from CSV

The old CSV format used multi-buys incorrectly:

Variations,PhotoUrls
"28g:1:700;14g:1:360"  ← WRONG (multi-buy format)

The text format uses variants correctly:

# Product; Weights - Standard
- 28g; 700; 100   ← CORRECT (variant format: name; price; stock)
- 14g; 360; 100

---

Generated: 2025-10-08 Format: Human-Readable Text Import with Variant Collections Ready to Use: Yes