Mercari CSV Specification

Mercari CSV Specification

Overview

The Mercari CSV format is used for bulk product management in Mercari Shops, Japan’s leading marketplace platform. This specification document details the complete structure of the CSV file format used for product data import/export operations.

Purpose and Usage

• Primary Use: Bulk product data management for Mercari Shops merchants
• Data Exchange: Import/export operations between Mercari platform and merchant systems
• Inventory Management: Stock level updates and SKU variant management
• Product Updates: Batch modifications of product listings

Technical Requirements

• Encoding: UTF-8 with BOM (Byte Order Mark)
• Delimiter: Comma (,)
• Text Qualifier: Double quotes (") for fields containing commas, newlines, or quotes
• Line Endings: CRLF (\r\n) or LF (\n)
• Total Columns: 162 columns (fixed structure)
• Header Row: Required (first row contains column names)

Core Product Fields

The following table details the primary product information fields:

Product Condition Codes

• 1 - 新品、未使用 (New, unused)
• 2 - 未使用に近い (Nearly unused)
• 3 - 目立った傷や汚れなし (No noticeable damage or stains)
• 4 - やや傷や汚れあり (Some damage or stains)
• 5 - 傷や汚れあり (Damaged or stained)
• 6 - 全体的に状態が悪い (Poor overall condition)

Category System

Category Management

• カテゴリID (Column 147): Numeric identifier for product category
• Category Master File: /category/category-master.csv contains category mappings
• Structure: Hierarchical category system with parent-child relationships

Category Master CSV Format

カテゴリID,カテゴリ名,カテゴリ名（フル）
1001,エレクトロニクス,エレクトロニクス
1002,シンセサイザー,エレクトロニクス > シンセサイザー
1003,モジュラーシンセ,エレクトロニクス > シンセサイザー > モジュラーシンセ

Additional Category Fields

Image Management

The CSV supports up to 20 product images, with each image slot containing 3 fields:

Image Field Structure (60 columns total)

For each image slot (1-20), the following columns exist:

Example Image Columns

Column 3: 商品画像名_1
Column 4: 商品画像更新フラグ_1
Column 5: 商品画像登録有無_1
...
Column 60: 商品画像名_20
Column 61: 商品画像更新フラグ_20
Column 62: 商品画像登録有無_20

Image Update Process

1. Set 商品画像名_[n] to the new image filename
2. Set 商品画像更新フラグ_[n] to 1 to trigger update
3. System will set 商品画像登録有無_[n] to 1 after successful upload

SKU/Variant System

The CSV supports up to 10 SKU variants, with each SKU containing 8 fields (80 columns total):

SKU Field Structure

For each SKU slot (1-10), columns are structured as:

Example SKU Data

SKU1_ID,SKU1_スナップショットID,SKU1_種類,SKU1_現在の在庫数,SKU1_増減フラグ,SKU1_在庫増減数,SKU1_商品管理コード,SKU1_JANコード
abc123,,Black,5,1,2,PROD-001,4901234567890

Shipping Configuration

Shipping Method Fields

Shipping Method Codes

• 1 - 未定(出品者が手配) (Undecided/Seller arranges)
• 2 - クール便 (Cool delivery)
• 3 - らくらくメルカリ便 (Rakuraku Mercari delivery)
• 4 - クールメルカリ便(冷蔵) (Cool Mercari - refrigerated)
• 5 - クールメルカリ便(冷凍) (Cool Mercari - frozen)

Prefecture Codes

Standard Japanese prefecture codes (1-47):

• 1 - 北海道 (Hokkaido)
• 13 - 東京都 (Tokyo)
• 27 - 大阪府 (Osaka)
• 47 - 沖縄県 (Okinawa)

Shipping Duration Codes

• 1 - 1〜2日で発送 (Ships in 1-2 days)
• 2 - 2〜3日で発送 (Ships in 2-3 days)
• 3 - 4〜7日で発送 (Ships in 4-7 days)
• 4 - 8日以上または未定 (8+ days or undecided)

Stock Management

Increment Flag System

The 増減フラグ (increment flag) fields control stock level changes:

Stock Update Process

1. Set SKU[n]_増減フラグ to 1 (increase) or 2 (decrease)
2. Set SKU[n]_在庫増減数 to the absolute change amount
3. System calculates: New Stock = Current Stock ± Change Amount
4. After processing, flags are reset to 0

Example Stock Update

# Before: Stock = 10
SKU1_現在の在庫数,SKU1_増減フラグ,SKU1_在庫増減数
10,1,5
# After processing: Stock = 15

# Decrease example:
10,2,3
# After processing: Stock = 7

Extended Descriptions

Markdown File Storage

For products requiring descriptions longer than the 5000-character limit:

• Directory: sub-packages/zmdpreview/docs/products/
• Filename Format: {product-slug}__{mercariProductId}.md
• Example: oxi-one-mk2-black__mYQ4dspiwCYsELs84GW5kC.md

Extended Description Structure

# Product Title

## Features
- Feature 1
- Feature 2

## Specifications
| Spec | Value |
|------|-------|
| Width | 16HP |
| Depth | 25mm |

## Additional Information
Detailed product description...

Integration with CSV

• The 商品説明 field contains the first 5000 characters
• Extended content is stored in the markdown file
• System merges both sources for complete product description

Data Validation Rules

Character Encoding Requirements

• Required: UTF-8 with BOM
• Prohibited Characters: Control characters (0x00-0x1F, 0x7F)
• Unicode Replacement Character: U+FFFD (�) causes import errors

Numeric Field Constraints

Text Field Limits

Special Character Handling

• Commas in fields: Must be enclosed in double quotes
• Quotes in fields: Must be escaped by doubling ("")
• Newlines: Allowed in quoted fields
• Japanese text: Fully supported

Integration Points

Connection to product-master-data.mjs

The mercari-viewer integrates with the main product database:

// product-master-data.mjs structure
{
  slug: "oxi-one-mk2-black",
  mercariProductId: "mYQ4dspiwCYsELs84GW5kC",
  price: 45000,
  // ... other fields
}

Price Synchronization

• Script: pnpm update:mercari-prices
• Process: Updates product-master-data.mjs from CSV prices
• Direction: Bidirectional sync capability

Data Flow

1. Export from Mercari: Download CSV from Mercari Shops admin
2. Local Editing: Use mercari-viewer for modifications
3. Save with Timestamp: /mercari-data/updated/YYYYMMDD-HHMMSS.csv
4. Import to Mercari: Upload modified CSV back to platform

Example CSV Row

Here’s a simplified example showing key fields:

商品ID,スナップショットID,商品画像名_1,商品画像更新フラグ_1,商品画像登録有無_1,...,商品名,商品説明,SKU1_ID,SKU1_スナップショットID,SKU1_種類,SKU1_現在の在庫数,SKU1_増減フラグ,SKU1_在庫増減数,...,ブランドID,販売価格,カテゴリID,商品の状態,配送方法,発送元の地域,発送までの日数,配送料の負担,送料ID,商品ステータス,...,Hash
"mYQ4dspiwCYsELs84GW5kC","snap_001","product_image_001.jpg","0","1",...,"OXI ONE MK2 Black","高性能シーケンサー...","sku_001","","Black","5","0","0",...,"OXI","45000","1003","1","3","13","1","1","ship_001","1",...,"abc123"

Troubleshooting

Common Issues

1. Character Encoding Errors

• Symptom: � characters appear in imported data
• Solution: Ensure UTF-8 with BOM encoding

2. Stock Update Failures

• Symptom: Stock levels don’t change after import
• Solution: Verify increment flags and amounts are set correctly

3. Image Update Issues

• Symptom: Images don’t update
• Solution: Set update flag to 1 for changed images

4. Category Validation Errors

• Symptom: “Invalid category” error
• Solution: Use valid category ID from category-master.csv

Validation Tools

The mercari-viewer includes validation utilities:

// csvValidator.js functions
validateCSVContent(csvContent) // Check for problematic characters
validateProductsData(products) // Validate product data
cleanProblematicChars(text)   // Remove invalid characters

Version History

• v1.0: Initial CSV format (162 columns)
• Current: Supports 10 SKUs, 20 images, extended descriptions via markdown files

Related Documentation

• API Field Specifications
• CSV Import Guide