Overview

Customers can upload CSV files containing lists of cards they want to sell. The system parses the CSV, matches items to products, and provides a preview before submission. This allows customers to bulk-submit large lists without manually adding each card individually.

CSV Format Requirements

• Required Columns:
  • Product ID or SKU: Use "Product ID", "SKU", or "skuId" column
  • Quantity: Use "Quantity" or "Qty" column (defaults to 1 if not provided)
• Optional Columns:
  • Condition: "Condition" column (accepts: Near Mint, Lightly Played, Moderately Played, Heavily Played, Damaged). Defaults to Near Mint.
  • Printing: "Printing" column (accepts: Normal, Foil, Holofoil, etc.). Defaults to Normal.
  • Language: "Language" column (accepts: English, Japanese, etc.). Defaults to English.
• Example CSV:

  Product ID,Quantity,Condition,Printing,Language
  12345,2,Near Mint,Foil,English
  67890,1,Lightly Played,Normal,English
  11111,4,Moderately Played,Foil,Japanese

Preview Process

1. CSV Upload: Customer selects CSV file from their computer
2. CSV Parsing: System parses CSV rows and extracts product identifiers, quantities, and attributes
3. Product Matching:
   • If skuId provided: Looks up SKU directly by skuId
   • Otherwise: Uses Product ID to find product, then matches SKU by condition, printing, and language
   • Normalizes condition aliases (e.g., "nm", "n.m.", "near mint" → "NM")
   • Normalizes printing aliases (e.g., "holofoil", "foil" → "Foil")
   • Normalizes language aliases (e.g., "en", "english" → "EN")
4. Preview Generation:
   • POST /api/buylist/preview-csv endpoint processes CSV rows
   • Returns previewItems array with productId, productData, skuData, condition, printing, language, quantity
   • Items without valid product identifiers are skipped with warning
5. Preview Display: Customer sees list of matched items with product names, images, quantities, and attributes
6. Price Calculation: System fetches prices for each preview item based on store's buylist configuration
7. Cart Addition: Customer can review preview, make adjustments, then add items to cart
8. Order Submission: Once added to cart, customer proceeds with normal order submission flow

SKU vs Product ID Matching

• SKU Matching (Preferred):
  • If CSV contains "skuId" column, system uses direct SKU lookup
  • SKU contains all attributes (productId, condition, printing, language)
  • Most accurate matching method
  • Condition, printing, and language are determined from SKU, not CSV
• Product ID Matching (Fallback):
  • If no skuId, uses "Product ID" or "SKU" column
  • Looks up product by numeric productId
  • Then matches SKU using condition, printing, language from CSV or defaults
  • If SKU not found, item may be skipped or use default attributes

Value Normalization

• Condition Normalization:
  • "near mint", "n.m.", "nm" → "NM"
  • "lightly played", "l.p.", "lp" → "LP"
  • "moderately played", "m.p.", "mp" → "MP"
  • "heavily played", "h.p.", "hp" → "HP"
  • "damaged", "dm" → "DM"
• Printing Normalization:
  • "foil", "holofoil" → "Foil"
  • "normal", "nonfoil", "non-foil" → "Normal"
  • "etched", "surge foil", "surge", "embossed", "textured" → respective normalized values
• Language Normalization:
  • Common abbreviations and full names normalized to ISO codes (EN, JP, FR, DE, etc.)
  • Defaults to "EN" (English) if not specified or unrecognized

Error Handling

• Invalid CSV Format: Returns 400 error if rows array is missing or empty
• Missing Product: Items without valid product identifiers are skipped with warning logged
• Missing SKU: If product found but SKU not found, item may be skipped or use default attributes
• Invalid Quantity: Non-numeric quantities default to 1
• Server Errors: Returns 500 error with error message if processing fails

Best Practices for Customers

• Use SKU IDs: Include skuId column for most accurate matching
• Include All Attributes: Specify condition, printing, and language for each row
• Verify Preview: Always review preview before submitting to ensure correct matching
• Check Product Names: Confirm product names in preview match your cards
• Handle Missing Items: If items don't appear in preview, they may not be in database - contact store
• CSV Format: Use standard CSV format (comma-separated) with header row