marketplace-building

マーケットプレイスの構築

概要

マルチベンダー型マーケットプレイスでは、独立した販売者がプラットフォームに商品を出品し、購入者から代金を回収して、手数料を差し引いた残額を販売者に支払います。主な構成要素は、KYC 認証を伴う販売者の登録、販売者ごとの商品出品管理、手数料の計算、自動支払いです。Shopify や WooCommerce を利用する事業者には、マーケットプレイス専用アプリで大部分の機能をまかなえます。カスタム開発が必要になるのは、主に非常に特殊な手数料体系や、ホワイトラベルのマーケットプレイスプラットフォームを構築する場合です。

このスキルを使用するタイミング

• サードパーティの販売者が自社の商品ではなく、自分の商品を出品・販売するプラットフォームを構築するとき
• プラットフォームが購入者から代金を回収し、手数料を差し引いた金額を販売者に分配する必要があるとき
• 販売者が出品を管理し、注文を確認し、収益を追跡するための独自のダッシュボードを必要とするとき
• 販売者の本人確認に関する KYC（顧客確認）要件に準拠するとき
• 手数料体系（割合、段階制、カテゴリ別）と支払いスケジュールを設計するとき

主な手順

ステップ 1：プラットフォームを決定し、適切なマーケットプレイスツールを選ぶ

プラットフォーム	推奨ツール	理由
Shopify	Webkul の Multi Vendor Marketplace または BOLD Multi-Vendor	Webkul のアプリは、ストアフロントを置き換えることなく、販売者アカウント、商品管理、手数料ルール、販売者用ダッシュボードを Shopify に追加します
WooCommerce	Dokan Multi-Vendor（最も人気があり、インストール数は 60K 以上）または WC Vendors	Dokan は WooCommerce マーケットプレイス向けに専用設計されており、販売者の登録、手数料管理、支払いリクエスト、販売者用ダッシュボードを備えています
BigCommerce	Webkul の Multi Vendor Marketplace（BigCommerce 版）	Webkul はマーケットプレイスアプリの BigCommerce 版を提供しています
カスタム／ヘッドレス	販売者アカウントを構築し、KYC と支払いに Stripe Connect を使用する	Stripe Connect は KYC、銀行口座情報の収集、1099-K 納税フォームに対応しています。カスタムマーケットプレイスにはこちらを使用してください

ステップ 2：販売者の登録と KYC を設定する

KYC（顧客確認）は、販売者に合法的に支払いを行う前に本人確認をするために必要です。これには Stripe Connect の利用を強く推奨します。独自に構築すると、費用がかさみ、法的にも複雑になるためです。

Shopify — Webkul の Multi Vendor Marketplace

1. Shopify App Store から Webkul の Multi Vendor Marketplace をインストールします
2. 販売者は販売者登録フォームから登録します（URL はカスタマイズ可能です。例：yourstore.com/seller/register）
3. Webkul 管理画面で販売者の申請を手動で承認します。承認前に販売者プロフィールを確認してください
4. 支払いのために Webkul を Stripe Connect に接続します：Webkul → Settings → Payment → Stripe Connect に移動し、Stripe の認証情報を入力します
5. 販売者を承認すると、Webkul は Stripe アカウントを接続するリンクを記載したオンボーディングメールを送信します（Stripe Express アカウントでは、Stripe が KYC と銀行口座情報を処理します）
6. Stripe Express アカウントの認証が完了すると、販売者は利用可能になります（Stripe は Webhook 経由で通知します）

WooCommerce — Dokan Multi-Vendor

1. WordPress.org（無料）または Dokan.com（Pro）から Dokan Multi-Vendor Plugin をインストールします
2. 販売者登録を有効にします：Dokan → Settings → General → Allow Registration に移動します
3. 必須項目（事業者名、納税者番号、銀行情報）を含むよう、販売者登録フォームをカスタマイズします
4. KYC には、Dokan Pro と Stripe Connect の連携を使用します。Dokan → Settings → Withdrawal → Stripe Connect に移動し、Stripe プラットフォームの認証情報を入力します
5. 販売者は、Dokan に組み込まれた Stripe Connect のオンボーディングフローから銀行口座を接続します
6. Dokan → Vendors で、販売者の申請を手動で承認または却下します

カスタム／ヘッドレス — KYC に Stripe Connect を使用する

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// Create a Stripe Express account for a new seller and return the onboarding URL
async function onboardSeller(sellerId: string, sellerEmail: string): Promise<string> {
  // Create the Stripe Express account
  const account = await stripe.accounts.create({
    type: 'express',
    email: sellerEmail,
    capabilities: {
      transfers: { requested: true },
    },
  });

  // Store the Stripe account ID on the seller record
  await db.sellers.update(sellerId, { stripe_account_id: account.id });

  // Generate the onboarding link (valid for 24 hours)
  const accountLink = await stripe.accountLinks.create({
    account: account.id,
    refresh_url: `${process.env.APP_URL}/seller/onboarding/refresh`,
    return_url: `${process.env.APP_URL}/seller/onboarding/complete`,
    type: 'account_onboarding',
  });

  return accountLink.url; // send this URL to the seller
}

// Webhook handler: activate seller when Stripe confirms KYC is complete
async function handleStripeAccountUpdated(account: Stripe.Account): Promise<void> {
  const seller = await db.sellers.findByStripeAccountId(account.id);
  if (!seller) return;

  if (account.charges_enabled && account.payouts_enabled && seller.status !== 'active') {
    await db.sellers.update(seller.id, { status: 'active' });
    // Send welcome email to seller
  }
}

ステップ 3：販売者ごとの商品出品を設定する

Shopify（Webkul）

1. 承認済みの販売者は、yourstore.com/seller/dashboard のセラーダッシュボードにログインします
2. 販売者はダッシュボードから商品を追加します。商品を公開する前に、あなたによる承認が必要です（Webkul の設定で変更できます）
3. 販売者が独自に価格を設定できるか、すべての価格にあなたの承認が必要かを管理します
4. 商品画像、説明、在庫はすべて、販売者がダッシュボードから管理します

WooCommerce（Dokan）

1. 販売者は yourstore.com/dashboard からストアダッシュボードにアクセスします
2. 販売者は Dokan → Products → Add New から商品を追加します
3. Dokan の設定で「Product Review」を有効にすると、新しい商品を公開する前にあなたの承認が必要になります
4. 販売者は在庫数、商品バリエーション、価格を自分で管理します
5. Dokan Pro では、商品単位、カテゴリー単位、または全体でコミッション率を設定できます

ステップ 4：コミッションルールと支払いを設定する

Shopify（Webkul）

1. Webkul → Commission に移動して、コミッション率を設定します：
   • 全体のコミッション：例として、すべての販売に 15％
   • 販売者別：特定の販売者向けに上書きします（例：VIP 販売者には 10％）
   • カテゴリー別：商品カテゴリーごとに異なる率を設定します
2. 支払い時に、コミッションは各注文から自動的に差し引かれます
3. 販売者の収益は、Webkul → Payments → Seller Transactions で追跡できます
4. 販売者に支払うには、Webkul → Payments → Process Payout に移動します。販売者を選択し、「Process via Stripe Connect」をクリックすると、Stripe の残高から販売者の連携済みアカウントに資金が送金されます

WooCommerce（Dokan）

1. Dokan → Settings → Selling → Commission に移動して、全体のコミッション率を設定します
2. Dokan → Vendors → [Seller] → Commission で販売者ごとに上書きします
3. 販売者はダッシュボードから出金を申請します（Dokan → Withdraw Requests）
4. Dokan → Withdraw Requests → Pending で出金申請を承認します
5. Stripe による自動支払いには、Dokan Pro の Stripe Connect モジュールが承認済みの出金申請を自動的に処理します

カスタム／ヘッドレス — コミッションと支払いのロジック

// Calculate commission and record seller earnings when an order is paid
async function recordSellerEarning(params: {
  orderId: string;
  sellerId: string;
  grossAmountCents: number;  // what buyer paid for this seller's items
  commissionRate: number;    // e.g., 0.15 for 15%
}): Promise<void> {
  const commissionCents = Math.round(params.grossAmountCents * params.commissionRate);
  const netAmountCents = params.grossAmountCents - commissionCents;

  // Funds held until return window closes (e.g., 30 days)
  const availableAt = new Date();
  availableAt.setDate(availableAt.getDate() + 30);

  await db.sellerEarnings.insert({
    seller_id: params.sellerId,
    order_id: params.orderId,
    gross_amount_cents: params.grossAmountCents,
    commission_cents: commissionCents,
    net_amount_cents: netAmountCents,
    status: 'held',             // becomes 'available' after return window
    available_at: availableAt,
  });
}

// Transfer available earnings to seller's Stripe account
async function payoutSeller(sellerId: string): Promise<void> {
  const seller = await db.sellers.findById(sellerId);
  const availableEarnings = await db.sellerEarnings.findAll({
    seller_id: sellerId,
    status: 'available',
    available_at: { lte: new Date() },
  });

  const totalCents = availableEarnings.reduce((s, e) => s + e.net_amount_cents, 0);
  if (totalCents < 100) return; // minimum payout $1.00

  // Transfer from your Stripe balance to seller's connected account
  const transfer = await stripe.transfers.create({
    amount: totalCents,
    currency: 'usd',
    destination: seller.stripe_account_id,
    metadata: { seller_id: sellerId },
  });

  // Mark earnings as paid out
  await db.sellerEarnings.updateMany(
    availableEarnings.map(e => e.id),
    { status: 'paid_out' }
  );
}

ステップ 5：販売者用ダッシュボードを設定する

Shopify（Webkul）

• 販売者は Webkul が提供する yourstore.com/seller/dashboard のダッシュボードにアクセスします。ここには注文、商品、収益の概要、支払い履歴が表示されます
• Webkul → Settings → Dashboard でダッシュボードの外観（色、ロゴ）をカスタマイズします

WooCommerce（Dokan）

• Dokan は yourstore.com/dashboard に、販売分析、商品管理、出金申請、注文管理機能を備えたフロントエンドダッシュボードを提供します
• Dokan のテンプレートオーバーライドを使用して、ダッシュボードを高度にカスタマイズできます

ベストプラクティス

• 販売者へのすべての支払いに Stripe Connect Express を使用します — Express は KYC、銀行口座の確認、IRS 1099-K の報告に対応します。これらを自前で構築すると、費用がかかり、法的なリスクも高まります
• 返品可能期間中は資金を保留します — 購入者の返品可能期間が終了するまで、販売者への収益の支払いを行わないでください。早期に支払うと、返金による損失をプラットフォームが負担することになります
• 注文確定と同じトランザクションでコミッションを記録します — 失敗する可能性のあるキューから非同期でコミッションを計算しないでください。収益の記録は注文と原子的に処理する必要があります
• 販売者に支払いの概要をメールで送信します — 注文ごとの詳細を含む週次の収益概要は、販売者の信頼を高め、サポートへの問い合わせを減らします
• Stripe のオンボーディングが完了するまで、販売者による公開をブロックします — 販売者が出品を公開できるようにする前に、Stripe アカウントの charges_enabled && payouts_enabled を確認します

よくある落とし穴

問題	解決策
出金に失敗しているのに、収益が支払い済みとして記録される	Stripe Connect では、収益を paid_out として記録する前に、transfer.created webhook を使って成功を確認します。送金を開始する同じ呼び出しで、支払い済みとして記録してはいけません
購入者の支払いが確定する前に、プラットフォームが出金する	チェックアウトセッションの作成時ではなく、payment_intent.succeeded webhook からのみ出金可能にします
KYC の確認前に、販売者が商品を掲載する	商品の公開を許可する前に、Stripe アカウントのステータス（charges_enabled && payouts_enabled）を確認します。Webkul と Dokan はこれを自動的に行います
販売者が手数料の差し引きに異議を申し立てる	すべての seller_earning レコードに手数料率と総額を保存し、販売者向けダッシュボードで手数料の計算履歴を確認できるようにします

関連スキル

• @multi-channel-selling
• @vendor-management
• @b2b-commerce
• @order-management-system