catalog-import-export

カタログのインポート／エクスポート

概要

商品の一括インポートとエクスポートは、サプライヤーのスプレッドシートから新しいストアを立ち上げる場合や、大量の価格を更新する場合、Google Merchant Center に商品を送信する場合など、カタログ管理の中核となる作業です。主要なプラットフォームには、カスタムコードなしでこれらの作業に対応するネイティブのインポート／エクスポートツールが備わっています。まずはそれらを利用してください。ボリューム、形式、または検証要件がプラットフォームの機能を超える場合にのみ、カスタムパイプラインを構築してください。

このスキルを使う場面

• カタログがスプレッドシートや ERP システムに保存されている新しいマーチャントを立ち上げるとき
• サプライヤーや PIM から商品データを定期的に同期するとき
• コーディングせずに価格や在庫を一括更新したいマーチャントを支援するとき
• Google Merchant Center、Amazon、または価格比較サイト向けの商品フィードを作成するとき

基本手順

ステップ 1：プラットフォームを特定し、適切なインポートツールを選ぶ

プラットフォーム	推奨ツール	理由
Shopify	Matrixify（Bulk Product Import Export）	メタフィールド、バリエーション、複数の画像、コレクションを含む複雑なカタログに対応し、スケジュール同期やエラーレポートもサポートします
Shopify（シンプルな場合）	Shopify 組み込みの CSV インポート	無料で、標準フィールドのみを使用する数百点以下の基本的なカタログには十分です
WooCommerce	WP All Import Pro	WooCommerce 向けの最も強力なインポートツールです。CSV／XML、フィールドマッピング、スケジュールインポート、条件付きロジックに対応します
WooCommerce（組み込み）	WooCommerce Product CSV Importer	WooCommerce に付属しており、シンプルな用途で商品、バリエーション、画像を処理します
BigCommerce	組み込みの一括インポート／Feedonomics	BigCommerce のネイティブインポートでほとんどのニーズに対応できます。複数チャネルのフィード管理には Feedonomics を使用します
カスタム／ヘッドレス	カスタムパイプラインを構築	プラットフォームにネイティブツールがない場合、または検証／変換要件が複雑すぎる場合に限ります

---

ステップ 2：インポートファイルを準備する

プラットフォームを問わず、商品インポートファイルはほぼ同じ構造です。プラットフォームのサンプル CSV をテンプレートとして使用してください。

• Shopify：Products → Import → Download sample CSV からサンプル CSV をダウンロードします
• WooCommerce：Products → Import → Download sample CSV からダウンロードします
• BigCommerce：Products → Import & Export → Download template からダウンロードします

ほとんどすべてのプラットフォームで必要となる主なフィールド：

フィールド	注記
Handle / Slug	URL で使用できる一意の識別子（例：blue-cotton-tshirt）
Title	商品名
Price	小数。例：29.99
SKU	バリエーションごとに一意
Inventory Quantity	整数
Images	カンマ区切りの URL、または個別にアップロード
Variant options	サイズ、カラーなど

重要な書式設定ルール：

• CSV ファイルは UTF-8 エンコーディングで保存します（Excel の場合：Save As → CSV UTF-8）
• プラットフォームのサンプルテンプレートと完全に同じ列ヘッダーを使用します
• 日付は ISO 形式にします：2026-03-12
• 真偽値は true／false を使用します（プラットフォームで指定されていない限り、yes／no や 1／0 は使用しません）

---

ステップ 3：プラットフォーム固有の設定

---

Shopify

オプション A：組み込みの CSV インポート（シンプルなカタログ向け）

1. Admin → Products → Import に移動します
2. サンプル CSV をダウンロードして、テンプレートとして使用します
3. Shopify の列形式に厳密に従ってファイルを準備します
4. CSV をアップロードし、Import products をクリックします
5. Shopify に作成／更新される内容の概要が表示されます。確定する前に確認してください

制限事項：組み込みのインポーターは、メタフィールド、カスタムコレクション、複雑なバリエーションロジックに対応していません。

オプション B：Matrixify（複雑なカタログにおすすめ）

1. Shopify App Store から Matrixify をインストールします
2. Matrixify で Export をクリックして、現在のカタログを参照用のスプレッドシートとしてダウンロードします
3. エクスポートした形式を使ってインポートファイルを準備します。対応しているすべての列が例とともに含まれています
4. ファイルをアップロードし、Import をクリックします
5. Matrixify に行ごとのエラーレポートが表示されます。これをダウンロードしてエラーを修正してから、再実行します
6. 同期をスケジュールするには、Matrixify → Schedules → Add schedule に移動し、頻度（毎時、毎日など）を設定して、Google Sheets の URL または FTP パスを指定します

Google Merchant Center 用のエクスポート：

1. Matrixify で Export に移動します
2. エクスポートテンプレートとして Google Shopping を選択します
3. フィード XML をダウンロードして Google Merchant Center にアップロードするか、Matrixify の Google Sheets への直接同期を使用します

---

WooCommerce

オプション A：組み込みの商品インポーター

1. WooCommerce → Products → Import に移動します
2. CSV ファイルをアップロードします
3. 列のマッピング画面で、CSV の列を WooCommerce のフィールドに対応付けます
4. Run the importer をクリックします。WooCommerce に進捗バーと概要が表示されます

オプション B：WP All Import Pro（高度なニーズにおすすめ）

1. WP All Import Pro と WooCommerce Add-On をインストールします
2. All Import → New Import に移動します
3. CSV または XML ファイルをアップロードするか、スケジュールされたインポート用の URL を入力します
4. ドラッグ＆ドロップ式のフィールドマッパーを使って、ファイルの列を WooCommerce の商品フィールドに対応付けます
5. Scheduling を設定します：All Import → Manage Imports → Edit → X 時間ごとに自動実行
6. All Import → History でインポートログを確認します。エラーは行番号とともに表示されます

Google Merchant Center フィードのエクスポート：

• Product Feed Pro for WooCommerce（無料）をインストールします
• Product Feed Pro → Manage Feeds → Add Feed に移動します
• テンプレートとして Google Shopping を選択します
• フィード URL を設定し、Google Merchant Center に直接公開します

---

BigCommerce

組み込みの一括インポート：

1. Products → Import & Export → Import Products に移動します
2. CSV テンプレートをダウンロードします
3. ファイルを準備してアップロードします
4. BigCommerce がファイルを検証し、確定前にプレビューを表示します
5. 画像の場合：アクセス可能な URL に画像をホストし、Product Image URL 列に記載します

Google Shopping フィード：

• Channel Manager → Google Shopping に移動します
• BigCommerce には Google Shopping とのネイティブ連携があります。Google Merchant Center アカウントを接続すると、BigCommerce がカタログを自動的に同期します

高度なマルチチャネルフィードの場合： BigCommerce App Marketplace から Feedonomics または GoDataFeed をインストールすると、Amazon、eBay、比較エンジン向けのフィードを利用できます。

---

カスタム／ヘッドレス

ヘッドレスストアフロントの場合は、商品を検証、変換、アップサートするパイプラインを構築します：

// lib/catalogImport.ts
import { z } from 'zod';
import { parse } from 'csv-parse';
import { createReadStream } from 'fs';

// Define and validate the import schema
const productRowSchema = z.object({
  handle: z.string().min(1).regex(/^[a-z0-9-]+$/, 'Handle must be lowercase alphanumeric with hyphens'),
  title: z.string().min(1).max(255),
  price: z.coerce.number().positive(),
  sku: z.string().min(1),
  inventory_quantity: z.coerce.number().int().min(0).default(0),
  image_url: z.string().url().optional(),
});

// Stream-parse large CSV files without loading into memory
export async function* parseCatalogCsv(filePath: string) {
  const parser = createReadStream(filePath).pipe(
    parse({ columns: true, skip_empty_lines: true, trim: true })
  );
  let rowIndex = 2;
  for await (const rawRow of parser) {
    const result = productRowSchema.safeParse(rawRow);
    yield result.success
      ? { row: rowIndex, data: result.data, errors: null }
      : { row: rowIndex, data: null, errors: result.error.issues.map(i => ({ field: i.path.join('.'), message: i.message })) };
    rowIndex++;
  }
}

// Process as an async job with upsert logic (idempotent, safe to re-run)
export async function runCatalogImport(filePath: string) {
  let processed = 0;
  const errors: { row: number; errors: { field: string; message: string }[] }[] = [];

  for await (const { row, data, errors: rowErrors } of parseCatalogCsv(filePath)) {
    if (rowErrors) { errors.push({ row, errors: rowErrors }); continue; }
    // Upsert by handle — re-running the same file won't create duplicates
    await db.products.upsert({ where: { handle: data!.handle }, create: data!, update: data! });
    processed++;
  }

  return { processed, errorCount: errors.length, errors: errors.slice(0, 50) };
}

Google Merchant Center 用の XML エクスポート：

import { create } from 'xmlbuilder2';

export async function exportGoogleFeed(products: Product[]) {
  const root = create({ version: '1.0', encoding: 'UTF-8' })
    .ele('rss', { version: '2.0', 'xmlns:g': 'http://base.google.com/ns/1.0' })
    .ele('channel');

  for (const product of products) {
    const item = root.ele('item');
    item.ele('g:id').txt(product.sku);
    item.ele('g:title').txt(product.title);
    item.ele('g:price').txt(`${product.price} USD`);
    item.ele('g:availability').txt(product.inStock ? 'in_stock' : 'out_of_stock');
    item.ele('g:link').txt(`https://yourstore.com/products/${product.handle}`);
    item.ele('g:image_link').txt(product.images[0]);
  }

  return root.end({ prettyPrint: true });
}

---

ステップ 4：確定前に検証する

すべてのプラットフォームにプレビュー／ドライランの手順があります。大量のインポートを確定する前に、必ず使用してください。

• Shopify 組み込み：Import をクリックする前に、「作成する商品数 X 件／更新する商品数 X 件」という概要を確認します
• Matrixify：インポートプレビューには、エラーのある行と該当する列、問題の詳細が表示されます
• WP All Import：「Dry Run」モードを使って、作成／更新される内容をプレビューします
• BigCommerce：アップロードの検証手順で、処理前にエラーが表示されます

続行する前に、検証手順で一覧表示されたすべてのエラーを修正してください。一部の行は成功し、ほかの行は失敗する部分的なインポートは、ファイルを完全に修正して再実行するよりも後処理が困難です。

---

ステップ 5：監視と検証

インポート後：

1. 管理画面でランダムに 5～10 件の商品を抜き取り確認し、タイトル、価格、画像、バリエーションが正しく読み込まれていることを確認します
2. エラーログを確認します — Matrixify と WP All Import では、行番号付きのダウンロード可能なエラーレポートが生成されます
3. 在庫数を確認します — インポートに在庫が含まれていた場合、想定どおりであることを確認します
4. ストアフロントでテストします — インポートした商品を 2～3 件検索して開き、正しく表示されることを確認します

ベストプラクティス

• 必ずプラットフォームのサンプル CSV をテンプレートとして使用します — CSV をゼロから手作業で作成すると、ほとんどの場合、ヘッダーが一致しません
• 商品数の多いカタログは 500～1000 件ずつインポートします — エラーのデバッグが容易になり、プラットフォームの UI の応答性も保たれます
• 大量インポートの前に、現在のカタログをバックアップします — 既存のカタログを先にエクスポートしておけば、問題が発生した場合に復元できます
• 在庫を別の同期で管理している場合、商品インポートで在庫を更新しないでください — 同じ項目を 2 つのシステムが更新すると競合します
• タイトルではなく、ハンドル／スラッグを安定した一意のキーとして使用します — 商品タイトルは変更されますが、ハンドルは変更しないでください
• 定期インポートはピーク時間外にスケジュールします — 大規模な同期は、営業時間のピーク時に管理画面の動作を遅くすることがあります

よくある落とし穴

問題	解決策
CSV インポートがエンコードエラーで失敗する	ファイルが UTF-8 で保存されていることを確認します（Excel の場合：ファイル → 名前を付けて保存 → CSV UTF-8）。商品名に含まれる特殊文字が、最も一般的な原因です
インポート後に画像が表示されない	インポート時に、画像が一般公開されている HTTPS URL でホストされている必要があります。Shopify と WooCommerce はインポート中に画像をダウンロードします
バリエーションが正しく作成されない	CSV に商品ごとではなく、バリエーションごとに 1 行あることを確認します。Shopify の CSV 形式では、複数のバリエーションに同じハンドルを繰り返し使用します
再実行時に商品が重複して作成される	ハンドル／SKU によるアップサートに対応したツール（Matrixify、WP All Import）を使用します。挿入のみに対応したツールは避けてください
商品インポート後に在庫が 0 にリセットされる	在庫を別途管理している場合、商品インポート CSV に在庫を含めないでください。ほとんどのプラットフォームでは、在庫列をスキップできます
Google フィードが Merchant Center に拒否される	必須フィールドを確認します：id、title、description、link、image_link、availability、price、brand、gtin または mpn

関連スキル

• @variant-matrix
• @product-data-modeling
• @multi-warehouse
• @product-content-enrichment