eBay Refund Management Spec

eBay返金管理 仕様書
新式B（2026-05-01 確定版）

refund_item_flow / 還付込み粗利 / 一部返金対応
2026-05-01
v2.0
01 — 概要・基本式

新式B：販売行と返金行を独立計上する設計

旧式は「matched行をリバースして相殺コピー」で表現していたが、新式Bでは 販売行と返金行を独立した会計事実として計上する。 返金行は「返金日に発生した増分」だけを表現し、CSV由来の手数料還付・Payoneer還付・在庫戻し価値・返送料を 組み合わせて粗利を算出する。

# 返金行の粗利計算式（calc_refund_gross_profit） refund.gross_profit_jpy = - refund_amount_jpy # 売上の取消し（abs(refund.jpy_amount)） + ebay_fee_credit_jpy # FVF + Intl − Promoted（手数料還付） + payoneer_credit_jpy # -refund.payoneer_fee_jpy（負値の符号反転） + returned_inventory_value_jpy # 商品が戻ってきた場合の評価額（原価相当） - actual_shipping_jpy # その取引の発送費（販売行=発送料、返金行=返送料）
重要： actual_shipping_jpy は販売行と返金行で意味が変わる。販売行＝バイヤーへの発送料、 返金行＝バイヤーからの返送料。1つの列で「その取引の発送費」を統一管理する設計（2026-05-01 確定）。
02 — パターン分類（Reference ID × 商品の動き）
Cancel ID
出荷前キャンセル
販売行statusmatched_cancel
商品手元のまま
在庫処理在庫中に戻す
refund_item_flowcancel_before_ship（自動）
UI固定ラベル・操作不可
eBay税還付ゼロ（取引不成立）
最終損益¥0（完全相殺）
Refund ID
返金のみ・商品戻らず
販売行statusmatched_sold
商品バイヤー保持
在庫処理なし
refund_item_flowbuyer_keeps（手動選択）
UIポップアップ2択
一部返金CSV金額そのまま使用で対応
最終損益−（原価+発送料）
Return ID
返品（商品戻る）
販売行statusmatched_sold
商品戻ってくる
在庫処理在庫中に戻す
refund_item_flowreturned（手動選択）
UIポップアップ2択
在庫戻し価値原価まるごと（方針確定）
最終損益≒ 発送料分の損失
一部返金（部分返金）について： eBayの正規返金フローを通すケースでは、CSVに一部金額の返金行が出力され、手数料も按分還付される。 現状ロジックは refund.jpy_amount をそのまま使うため、CSVが正しい金額を持ってくる前提で 自動的に正しい粗利が算出される（要・実ケース発生時の動作確認）。
03 — DB設計（ebay_sales 追加列）
商品の動き・在庫戻し関連 refund行のみ使用
refund_item_flowNEWvarchar(30)buyer_keeps / returned / cancel_before_ship
refund_amount_typeNEWvarchar(20)full / partial（将来拡張用）
item_returned_to_inventoryNEWboolean商品が在庫戻しされたか（returned時 true）
returned_item_conditionNEWvarchar(20)good / damaged / junk（将来UI追加予定）
returned_inventory_value_jpyNEWnumeric在庫戻し価値（returned時=原価、buyer_keeps時=0）
refund_typeNEWvarchar(40)Refund/Return/Cancel ID 種別の保存
is_seller_protection_deductionNEWbooleanセラープロテクション控除フラグ（将来用）
運用・履歴管理 全行で使用
gp_formula_versionNEWvarchar(30)old / new_b（粗利式バージョン管理）
is_accounting_lockedNEWboolean月次確定後の編集ロック（将来UI追加）
accounting_exported_atNEWtimestampMFクラウド送信日時
refund_processed_atNEWtimestamp返金処理日時（refund_item_flow更新時）
refund_noteNEWtext返金関連の手動メモ
actual_shipping_jpynumeric取引の運送費（販売行=発送料、返金行=返送料）
cost_jpynumeric仕入原価。unmatched行は手動入力可（直書き設計）
04 — 計算式（速報粗利・還付込み粗利）

速報粗利（gross_profit_jpy）

# 販売行（matched / matched_sold / matched_cancel） gp = sales_jpy − ebay_fee_jpy − payoneer_fee − cost − shipping − duty # 返金行（refund・新式B） gp = −refund_amount_jpy + (fvf_fixed + fvf_variable + intl_fee − promoted_fee) × jpy_rate + (−payoneer_fee_jpy) + returned_inventory_value_jpy − actual_shipping_jpy

還付込み粗利（calcRefundProfit、フロント計算）

# 速報粗利に消費税還付を加算 還付込み粗利 = 速報粗利 + ebayTaxRefund + purchaseTaxRefund # eBay手数料消費税還付 ebayTaxRefund = (status == 'refund' || status == 'matched_cancel') ? 0 # 取引不成立は還付なし : (allFeesUsd / 11) × jpy_rate # 通常は10%還付 # 仕入消費税還付（supplierType別） purchaseTaxRefund = (supplierType == '適格') ? cost / 11 : (supplierType == '非適格') ? (cost / 11) × 0.8 : 0 # unmatched行は supplierType='適格' を強制（雑貨単発仕入）
キャンセル相殺の保証： matched_cancel と対応する refund 行はeBay税還付がともにゼロ。 仕入税還付は cost_jpy が正負で対称（販売行=+10,450 / 返金行=−10,450）なので、 還付込み粗利も完全相殺される。
05 — UI仕様（売上一覧画面）

📦 商品の動きポップアップ

Refund ID / Return ID（new_b）の返金行で表示。トリガーボタンをクリックすると共有ポップアップが開く。

[📦 商品の動き ▼]　← 小さいトリガーボタン
↓ クリック
┌──────────────┐
│ ○ 戻ってこなかった　│
│ ○ 戻ってきた　　　 │
└──────────────┘

「出荷前キャンセル」はCSV取込時に自動セット。UI選択肢には出ない。

🚫 Cancel ID 固定ラベル

matched_cancel に対応する返金行は固定グレーラベル表示・操作不可。

📦 出荷前キャンセル　← グレー固定ラベル

CSV取込時に refund_item_flow='cancel_before_ship' が自動でDB保存される。

🚚 速報送料（返送料）入力

販売行・返金行の両方で「速報送料」欄として表示。値の更新で粗利が即時再計算される。

販売行: 発送料を入力
返金行: 返送料を入力（returned時のみ意味あり）

DB列は1つ actual_shipping_jpy で統一管理。

💰 SKU未存在の仕入原価入力

unmatched行（ポケモンカードなど単発雑貨）は仕入原価セルをクリックでインライン入力可能。

[入力] ← クリック
↓
[ 100] 円　Enter で保存
↓
¥100　← クリックで再編集可

仕入消費税還付は適格扱いで自動計算。¥0 入力も「入力済み」として扱う。

06 — APIエンドポイント
エンドポイント 用途 主な処理
POST /ebay/refund/update 返金行の「商品の動き」更新 refund_item_flow保存・在庫戻し処理・粗利再計算
POST /ebay/update-shipping 速報送料（actual_shipping_jpy）更新 販売行/返金行(new_b)を判定して粗利再計算
POST /ebay/update-cost SKU未存在行の仕入原価手動入力 cost_jpyを直書き、calc_gross_profitで粗利再計算
POST /ebay/return_stock 旧式の在庫戻しボタン（後方互換） gp_formula_version='old'のみ対応、新式Bでは使われない
07 — 運用フロー
Step 01
eBayから月次CSVをダウンロード
Order行・Refund行・Other fee行・Payout行を含む取引明細CSV。
Step 02
CSV取込（自動判定）
Reference IDで Cancel/Refund/Return ID を判別。Cancel ID は refund_item_flow='cancel_before_ship' を自動セット。 全レコードに gp_formula_version='new_b' を刻印。 unmatched行はSKU未取得のため cost_jpy=NULL のまま保存。
Step 03
取込確認画面で重複チェック → 登録
既に取込済みの注文番号があれば already_imported カウントとして除外。
Step 04
売上一覧画面でユーザー操作
① 返金行の「商品の動き」ポップアップで戻ってこなかった/戻ってきたを選択
② 速報送料（発送料・返送料）を入力
③ unmatched行の仕入原価を手動入力
→ いずれも粗利・KPI・還付込み粗利が即時連動
Step 05（将来）
月次確定 → アカウンティングロック
is_accounting_locked=true でその月の編集を禁止。MFクラウド送信前の確定処理。
Step 06（将来）
MFクラウドへ仕訳送信
mf-automation プロジェクト経由で月次仕訳を送信。 accounting_exported_at に送信日時を記録。
08 — 既知の制約・将来課題
  • 旧式（old）レコードと新式（new_b）の混在：既存の old レコードは旧UIの在庫戻しボタンが動く。Step 5で順次 new_b に再計算予定。
  • Return ID 既存2件（26-125, 2025-0859）：gp_formula_version='old' のため新UI表示されず。Step 5の対象。
  • 真の一部返金（クレーム値引き）の動作確認：現状サンプルなし。実ケース発生時に検算。
  • 戻ってきた商品の状態別評価減：現状は「原価まるごと戻し」固定。ジャンク廃棄等は items 側で別途評価減処理する想定。
  • 月次確定後ロックUI：API は対応済み（is_accounting_locked判定）、UI実装は未着手。
  • SKU未存在の手動入力：古物台帳記載義務外（1万円未満）の単発雑貨を想定。1万円以上のものは items に登録すべき。
09 — 変更履歴
  • 2026-05-01 v2.0（新式B 確定版）： 全面刷新。旧式の「matched行リバース」設計を廃止し、販売行と返金行を独立計上する新式Bへ移行。 DB列12個追加、calc_refund_gross_profit 実装、ポップアップUI実装、Cancel ID自動化、 還付込み粗利のキャンセル相殺バグ修正、SKU未存在行の手動入力UI追加、返送料を actual_shipping_jpy に統合。
  • 2026-04 旧版 v1.x： 旧式タブとして「matched行を相殺コピー」する設計で運用。Cancel ID対応・在庫戻しボタン・ BUG-001（Refund IDの粗利計算ズレ）等の課題があった。