CSV Product Register

CSV Product Register

Overview

This document explains how to add new products to Mercari Shops using the CSV import template. The process involves preparing product data in the simplified template format and importing it through the Mercari Shops interface.

Official Mercari Documentation

For the most up-to-date information about CSV import specifications and procedures, refer to the official Mercari Shops documentation:

• CSV一括編集について - Comprehensive guide on CSV bulk editing, including field specifications, validation rules, and import procedures
• メルカリShopsにCSVで商品情報を一括登録する - Step-by-step instructions for bulk product registration via CSV, with examples and troubleshooting tips

Template vs Export Format

Import Template (72 columns) - CRITICAL FORMAT

The product_import_template.csv requires EXACT 72-column structure:

• Location: /mercari-data/templates/product_import_template.csv
• Columns: EXACTLY 72 fields (missing columns cause import failure)
• Purpose: New product registration and updates
• Encoding: UTF-8 with BOM
• CRITICAL: Header and data rows must have identical column count

Export Format (162 columns)

The full export CSV contains additional system-generated fields:

• Columns: 162 fields (includes metadata and tracking)
• Purpose: Complete product management with system data
• Additional Fields: Product IDs, snapshots, update flags, registration status
• WARNING: Cannot be directly imported - must convert to 72-column format

Template Structure

Core Product Fields (Columns 1-22)

SKU/Variant Fields (Columns 23-62)

Each SKU slot (1-10) contains 4 fields:

Product Details (Columns 63-72)

Adding New Products

Step 1: Prepare Product Data

1. Download Template: Get product_import_template.csv from Mercari Shops
2. Open in Spreadsheet: Use Excel, Google Sheets, or CSV editor
3. Maintain UTF-8 BOM: Ensure encoding is preserved

Step 2: Fill Required Fields

Working 72-Column CSV Example

CRITICAL: This example shows the EXACT format that passes validation:

商品画像名_1,商品画像名_2,商品画像名_3,商品画像名_4,商品画像名_5,商品画像名_6,商品画像名_7,商品画像名_8,商品画像名_9,商品画像名_10,商品画像名_11,商品画像名_12,商品画像名_13,商品画像名_14,商品画像名_15,商品画像名_16,商品画像名_17,商品画像名_18,商品画像名_19,商品画像名_20,商品名,商品説明,SKU1_種類,SKU1_在庫数,SKU1_商品管理コード,SKU1_JANコード,SKU2_種類,SKU2_在庫数,SKU2_商品管理コード,SKU2_JANコード,SKU3_種類,SKU3_在庫数,SKU3_商品管理コード,SKU3_JANコード,SKU4_種類,SKU4_在庫数,SKU4_商品管理コード,SKU4_JANコード,SKU5_種類,SKU5_在庫数,SKU5_商品管理コード,SKU5_JANコード,SKU6_種類,SKU6_在庫数,SKU6_商品管理コード,SKU6_JANコード,SKU7_種類,SKU7_在庫数,SKU7_商品管理コード,SKU7_JANコード,SKU8_種類,SKU8_在庫数,SKU8_商品管理コード,SKU8_JANコード,SKU9_種類,SKU9_在庫数,SKU9_商品管理コード,SKU9_JANコード,SKU10_種類,SKU10_在庫数,SKU10_商品管理コード,SKU10_JANコード,ブランドID,販売価格,カテゴリID,商品の状態,配送方法,発送元の地域,発送までの日数,商品ステータス,配送料の負担,送料ID
"https://example.com/image1.jpg","","","","","","","","","","","","","","","","","","","","OXI ONE MK2 Black","高性能シンセサイザー\n複数行の説明文\n改行も可能","Black","1","OXI-001","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","158800","1411","1","3","jp13","2","2","1",""

Key Points:

• All 72 columns present (even if empty)
• SKU1_在庫数 has value “1” (required)
• 発送元の地域 uses “jp13” (NOT “東京都”)
• Numeric values for condition, method, duration, status, payer
• Empty cells use "" in CSV

Step 3: Critical Data Validation

Column Count Verification

// Validate 72-column structure
function validateCSVStructure(csvRow) {
  const columns = csvRow.split(',');
  if (columns.length !== 72) {
    throw new Error(`Column count mismatch: ${columns.length} (expected 72)`);
  }
  return true;
}

Required Field Values - CRITICAL MAPPINGS

• 商品の状態 (Condition) - Numeric ONLY:

  • 1 = 新品、未使用
  • 2 = 未使用に近い
  • 3 = 目立った傷や汚れなし
  • 4 = やや傷や汚れあり
  • 5 = 傷や汚れあり
  • 6 = 全体的に状態が悪い

• 配送方法 (Shipping Method) - Numeric ONLY:

  • 1 = 未定(出品者が手配)
  • 2 = クール便
  • 3 = らくらくメルカリ便
  • 4 = クールメルカリ便(冷蔵)
  • 5 = クールメルカリ便(冷凍)
  • 6 = メルカリBiz配送

• 発送元の地域 - Prefecture Codes (NOT names!):

  • jp01 = 北海道
  • jp13 = 東京都
  • jp27 = 大阪府
  • jp47 = 沖縄県
  • Use jp01-jp47 format ONLY

• 発送までの日数 - Numeric ONLY:

  • 1 = 1〜2日で発送
  • 2 = 2〜3日で発送
  • 3 = 4〜7日で発送
  • 4 = 8〜14日で発送
  • 5 = 90日以内で発送

• 商品ステータス - Numeric ONLY:

  • 1 = 下書き (Draft)
  • 2 = 公開中 (Published/Active)

• 配送料の負担 - Numeric ONLY:

  • 1 = 送料込み(出品者負担)
  • 2 = 送料別(購入者負担)

Step 4: Import Process

1. Save as CSV: Export with UTF-8 BOM encoding
2. Login to Mercari Shops: Access merchant dashboard
3. Navigate to Import: 商品管理 → CSVインポート
4. Upload File: Select prepared CSV file
5. Validation: System checks for errors
6. Confirm Import: Review and confirm new products

Integration with Product Master

After importing new products:

1. Export Full CSV: Download complete product data with generated IDs
2. Update product-master-data.mjs:

• Add new product entries
• Include generated mercariProductId
• Map to appropriate slug and brand

3. Generate Markdown Descriptions:

   pnpm generate:mercari-markdown

4. Sync Prices:

   pnpm update:mercari-prices

Common Import Errors & Solutions

Critical Format Errors

”フォーマットエラー” (Format Error)

• Cause: Column count mismatch between header and data
• Solution: Ensure EXACTLY 72 columns in both header and data rows
• Check: Count commas - should be exactly 71 in each row
• Tool: Use CSV validator to verify structure

”SKU1_在庫数が未入力です” (Stock Quantity Missing)

• Cause: Stock quantity required even without SKU variants
• Solution: Add 1 or actual stock count in SKU1_在庫数 column (column 24)
• Note: Cannot leave empty even for single-variant products

”発送元の地域が不正です” (Invalid Shipping Origin)

• Cause: Using prefecture name instead of code
• Solution: Use jp01-jp47 codes, NOT “東京都” or “大阪府”
• Example: jp13 for Tokyo, jp27 for Osaka

”ブランドIDが存在しません” (Brand ID Not Found)

• Cause: Invalid or non-existent brand ID
• Solution: Use valid ID from brand master or leave completely empty
• Reference: Check /mercari-data/brand/brand-master.csv

”カテゴリIDが不正です” (Invalid Category ID)

• Cause: Using parent category or invalid ID
• Solution: Must use leaf category ID from category master
• Reference: /mercari-data/category/category-master.csv

Encoding Problems

• Issue: Characters appear as � or mojibake
• Solution: Save with UTF-8 with BOM encoding
• Tool: VS Code, Notepad++ (preserve BOM)

Column Alignment Issues

• Issue: Values in wrong columns after import
• Solution: Verify 72-column structure, check for extra commas
• Debug: Open in Excel/Sheets to visually verify alignment

Best Practices

1. Test with Draft Status: Use status=3 for initial imports
2. Small Batches: Import 10-20 products at a time
3. Backup Data: Keep copies of import files
4. Validate Locally: Check CSV structure before upload
5. Use Templates: Create reusable templates for product types

Workflow Summary

graph LR
    A[Prepare Template CSV] --> B[Fill Product Data]
    B --> C[Validate Fields]
    C --> D[Import to Mercari]
    D --> E[Export Full CSV]
    E --> F[Update Product Master]
    F --> G[Generate Markdown]
    G --> H[Sync Systems]

Related Documentation

• CSV Specification - Complete field reference
• Overview - Mercari CSV Viewer guide
• Product Master - Product data structure

Draft Management System

Overview

The draft management system provides a local workspace for preparing new product listings before CSV export. This allows users to incrementally build up product data, save work in progress, and export to CSV when ready for import to Mercari Shops.

Draft Data Structure

Drafts are stored in a simplified JSON format that captures essential product information without the full 72-column CSV complexity:

{
  "drafts": [
    {
      "id": "draft-1234567890",
      "createdAt": "2025-01-14T10:00:00Z",
      "updatedAt": "2025-01-14T10:30:00Z",
      "data": {
        "productName": "OXI ONE MK2 Black",
        "description": "詳細な商品説明...",
        "price": 158800,
        "images": [
          "https://example.com/image1.jpg",
          "https://example.com/image2.jpg"
        ],
        "skus": [
          {
            "variant": "Black",
            "stock": 5,
            "managementCode": "OXI-ONE-BLK",
            "janCode": ""
          }
        ],
        "categoryId": 1411,
        "condition": 1,
        "shippingMethod": 1,
        "shippingFrom": 13,
        "daysToShip": 2,
        "status": 3,
        "shippingPayer": 1
      }
    }
  ]
}

Storage Location: /mercari-data/drafts/draft.json (git-ignored)

Draft Form Fields

Basic Product Information

SKU/Inventory Management

Each draft can have up to 10 SKU entries:

UI Features:

• Add SKU button to create new variant
• Remove button for each SKU entry
• Automatic reordering on deletion
• Visual indicator for active SKUs

Product Images

UI Features:

• Dynamic add/remove image fields
• Image preview thumbnails
• Drag-and-drop reordering
• URL validation
• Support for image upload or URL input

Category Selection

Implementation:

• Uses existing category component from main viewer
• Hierarchical category display
• Search/filter functionality
• Shows category path (e.g., “楽器 > シンセサイザー > モジュラー”)

Shipping Configuration

Draft Viewer Features

Draft List View

• Display: Card or table layout showing all drafts
• Information Shown:
  • Product name
  • Price
  • Creation/update timestamps
  • Status indicator
  • Thumbnail image
• Actions:
  • Edit draft
  • Duplicate draft
  • Delete draft
  • Export to CSV

Draft Editor

• Auto-save: Changes saved automatically with debounce
• Validation: Real-time field validation
• Preview: Side-by-side preview of how listing will appear
• Templates: Save and apply product templates

Export and Management Features

Export to CSV

Converts draft data to proper CSV format:

function exportDraftsToCSV(drafts) {
  const csvRows = [];
  
  drafts.forEach(draft => {
    const row = new Array(72).fill('');
    
    // Map draft fields to CSV columns
    row[20] = draft.data.productName;           // 商品名
    row[21] = draft.data.description;           // 商品説明
    row[63] = draft.data.price;                 // 販売価格
    row[64] = draft.data.categoryId;            // カテゴリID
    row[65] = draft.data.condition;             // 商品の状態
    // ... map remaining fields
    
    // Handle images
    draft.data.images.forEach((img, i) => {
      if (i < 20) row[i] = img;                 // 商品画像名_1～20
    });
    
    // Handle SKUs
    draft.data.skus.forEach((sku, i) => {
      if (i < 10) {
        const base = 22 + (i * 4);
        row[base] = sku.variant;                // SKU[n]_種類
        row[base + 1] = sku.stock;              // SKU[n]_在庫数
        row[base + 2] = sku.managementCode;     // SKU[n]_商品管理コード
        row[base + 3] = sku.janCode;            // SKU[n]_JANコード
      }
    });
    
    csvRows.push(row);
  });
  
  return csvRows;
}

Draft Management Operations

Validation Rules

Required Fields

The system enforces validation matching CSV import requirements:

const validateDraft = (draft) => {
  const errors = [];
  
  // Required fields
  if (!draft.productName || draft.productName.length > 100) {
    errors.push('商品名は必須です（最大100文字）');
  }
  
  if (!draft.description || draft.description.length > 5000) {
    errors.push('商品説明は必須です（最大5000文字）');
  }
  
  if (!draft.price || draft.price < 300 || draft.price > 9999999) {
    errors.push('販売価格は300円～9,999,999円の範囲で設定してください');
  }
  
  if (!draft.categoryId) {
    errors.push('カテゴリを選択してください');
  }
  
  // Additional validations...
  
  return errors;
};

Field-Specific Rules

• Images: Valid URLs, accessible endpoints
• SKUs: Unique management codes within draft
• JAN Codes: Valid checksum if provided
• Category: Must be leaf category (not parent)

UI Components

Draft Counter Badge

Shows number of unsaved drafts:

<div className="draft-counter">
  <span className="badge">{draftCount}</span>
  <span>下書き</span>
</div>

Draft Action Toolbar

Quick actions for draft management:

<div className="draft-toolbar">
  <button onClick={addDraft}>新規作成</button>
  <button onClick={exportSelected}>選択をエクスポート</button>
  <button onClick={exportAll}>すべてエクスポート</button>
  <button onClick={clearAll}>すべて削除</button>
</div>

Storage and Persistence

• Local Storage: Auto-save draft state to browser
• File System: Export to /mercari-data/drafts/draft.json
• Backup: Automatic daily backup of draft.json
• Recovery: Restore from backup if main file corrupted

Integration Points

1. With Main Viewer: Share category and shipping components
2. With Product Master: Import product data as draft template
3. With CSV Export: Generate properly formatted import files
4. With Validation: Use same rules as CSV import specification