SaaSサブスクリプションのための紹介クレジットシステム設計

紹介クレジットシステムとは（何ではないか）

紹介クレジットプログラムは支払い機能ではなく、請求（billing）の機能です。報酬は将来の請求を減らす（または期間を延ばす）アカウントクレジットであり、銀行に振り込まれる現金でもギフトカードでも、後で“支払われる”という約束でもありません。

良いシステムは常に一つの問いに答えます：「なぜこのアカウントの次の請求額が下がったのか？」 これを一〜二文で説明できなければ、サポートチケットや紛争が続きます。

紹介クレジットシステムは三つの要素からなります：誰かが新規顧客を招待すること、招待が有効と見なされる明確なルール（コンバージョン）、そしてクレジットが獲得され将来のサブスクリプション請求に適用されることです。

それが何でないか：現金支払い、記録のないあいまいな割引、請求に結びつかないポイントシステムなどです。

複数のチームがこれらの詳細に依存します。紹介者は何をいつ得たかを見たい。紹介されたユーザーは何を得るのか、プランに影響があるかを知りたい。サポートは「クレジットが消えた」を迅速に解決する必要がある。財務は請求書と一致し監査可能な合計を求めます。

例：SamがPriyaを紹介。Priyaが有料プランを開始すると、Samは$20のクレジットを獲得し、次回の請求から最大$20を差し引けます。もしSamの次回請求が$12であれば、残りの$8は後で使えるクレジットとして残り、出所が明確に記録されます。

成功は単に「紹介が増えること」ではなく、予測可能な請求と争いが少ないことです。クレジット残高が説明しやすく、請求書が台帳と一致し、サポートが推測や手作業なしに質問に答えられるとき、それがうまく機能している証拠です。

構築前に決めるべきルール

紹介プログラムは簡単に聞こえますが、最初のチケット「なぜクレジットがもらえなかったのか？」が来ると面倒になります。多くの作業はコードではなく方針です。

まずトリガーを決めましょう。「招待を送信した」は早すぎます。「サインアップ」は使い捨てアカウントで悪用されやすいです。一般的な折衷点は「qualified conversion（資格を満たしたコンバージョン）」：メール確認＋最初の有料請求、またはトライアル後の最初の成功した支払いなどです。一つのトリガーを選び一貫させることで台帳がきれいに保たれます。

次に価値と制限を設定します。クレジットは実感できるべきですが、無制限の割引装置になってはいけません。固定額（例：$20）を与えるか請求の割合を与えるかを決め、説明が一文で済むように上限を設けてください。

後で混乱を避けるための決定事項：

• どのイベントが資格になるか（最初の支払い、初回更新など）
• 付与されるクレジット額（固定か割合か、プランによって変わるか）
• 上限（紹介ごと、月ごと、生涯など）
• 対象となるプランや取引タイプ
• クレジットの有効期限の有無

適格性ルールは人々が思うより重要です。もし有料プランのみが対象なら明記しましょう。地域による除外（税務、コンプライアンス、プロモ）はあれば明示してください。年額プランは対象で月額は対象外、などがある場合も同様です。For a platform like Koder.ai のように複数の階層があるプラットフォームでは、無料からプロへのアップグレードが対象か、エンタープライズ契約を手動で扱うかを事前に決めてください。

リリース前にユーザー向けの文言を書いておいてください。各ルールを二短文で説明できないなら、ユーザーは誤解します。穏やかで断定的な表現を使いましょう："不審な活動が疑われる場合、クレジットを保留する場合があります" は長い脅しのリストよりも明確で穏当です。

招待から資格成立までのトラッキング方法

一つの主要識別子を選び、他は補助証拠として扱いましょう。最もクリーンな選択肢は紹介リンクのトークン（共有が簡単）、短いコード（入力が簡単）、特定のメールアドレスへの招待（直接招待に最適）です。真実の単一ソースを選べば帰属が予測可能に保てます。

その識別子をできるだけ早く捕捉し、ユーザージャーニー全体で持ち運んでください。リンクトークンは通常ランディングページで捕捉され、ファーストパーティのストレージに保管され、サインアップ時に再送信されます。モバイルでは可能な限りアプリインストールフローを通して渡しますが、時々失われることを想定してください。

ビジネスルールに合う少数のイベントを追跡します。目標が「支払い顧客になったかどうか」であれば（単なるクリックではなく）、最小限のセットで十分です：

• referral_click（トークンが見えた）
• account_signup（新規ユーザー作成）
• account_verified（メール/電話確認）
• first_paid_invoice（最初の成功した支払い）
• qualification_locked（コンバージョンが確定し変更されない）

デバイス切り替えやブロックされたクッキーは普通に起こります。それらを過剰追跡せずに扱うには、サインアップ時にクレーム（主張）ステップを追加してください：トークンがあれば新規アカウントに添付し、なければオンボーディングで一度だけ短い紹介コードを入力できるようにします。両方が存在する場合は、最も早く捕捉された値を主要値として保持し、もう一方を補助証拠として保存します。

最後に、サポートが1分で読める簡単なタイムラインを各紹介に保持してください：紹介者、紹介されたアカウント（判明次第）、現在のステータス、最後の意味のあるイベントとタイムスタンプ。誰かが「なぜクレジットがもらえなかったのか？」と聞いてきたときに、「サインアップはあったが最初の有料請求がなかった」という事実で答えられるようにします。

読みやすくデバッグしやすいデータモデル

紹介プログラムはデータモデルがあいまいだと壊れやすいです。サポートは「誰が誰を紹介したか？」と聞き、請求は「クレジットは既に発行されたか？」と尋ねます。ログを掘らずに答えられないならモデルを厳しくしてください。

紹介関係はファーストクラスのレコードとして保存し、クリックから推測するような派生値に頼らないでください。

保存すべきコアレコード

シンプルでデバッグしやすい構成は次の通りです：

• referrals: id, referrer_user_id, referred_user_id, created_at, source（invite link, coupon, manual）, status, status_updated_at
• referral_attribution（オプション）: referral_id, invite_code_id or campaign_id, first_seen_ip_hash, first_seen_user_agent_hash
• workspaces（チームがある場合）: workspace_id, owner_user_id, created_at
• workspace_members: workspace_id, user_id, role, joined_at

referralsテーブルは小さく保ってください。後で後悔するような生データ（フルIP、フルユーザーエージェント、氏名など）は避けるか、短期ハッシュとして保存し明確な保持ポリシーを設けてください。

ステータスは明示的かつ相互排他的にしてください：pending（サインアップはあるがまだ資格なし）、qualified（ルールを満たした）、credited（クレジット発行済み）、rejected（チェックに失敗）、reversed（返金/チャージバックでクレジット回収）など。

二重カウントを防ぐルール

優先順位は一度決めてデータベースで強制してください。最低限：

• 一つの紹介につき被紹介アカウントは一人だけ（referred_user_idにユニーク制約）
• 被紹介アカウントにつきcreditedになれる紹介は一つだけ
• 複数の接触（タッチ）があれば、first-touchかlast-touchのどちらかを選び選ばれたreferral_idを保存する

チームをサポートする場合、紹介が個人サインアップに付くのかワークスペース作成に付くのかを決めてください。両方を同時にやろうとしないでください。実用的な方法としては紹介をユーザーアカウントに紐付け、適格チェックはそのユーザー（またはそのワークスペース）が有料購読者になったかを確認する、というやり方があります。

クレジット台帳の基礎：正確で監査可能、説明できること

請求バグとサポートチケットを減らしたければ、単一の「クレジット残高」フィールドではなく台帳を使ってください。残高は上書き、四捨五入、二重更新されやすいですが、台帳は常に足し合わせ可能な履歴です。

エントリタイプは限定し曖昧さをなくしてください：earn（付与）、spend（請求へ適用）、expire（期限切れ）、reversal（回収）、manual adjustment（注記と承認者付き）など。

各エントリはエンジニアとサポートの両方が読めるようにしてください。保存する一貫したフィールド例：amount、credit type（クレジットが現金でないなら「USD」だけにしない）、reason text、source event（例：referral_signup_qualified）、source IDs（ユーザー、被紹介ユーザー、サブスクリプションや請求書）、タイムスタンプ、created_by（system または admin）。

冪等性（idempotency）は想像以上に重要です。同じWebhookやバックグラウンドジョブが二度走ることがあります。ソースイベントごとにユニークなidempotency keyを要求し、再試行しても二重でクレジットを付与しないようにしてください。

ユーザーに説明できるようにしてください。「なぜ20クレジットが付いたの？」と聞かれたら、どの紹介がトリガーしたか、いつ投稿されたか、有効期限があるか、後で回収があったかを示せるべきです。友人がアップグレードしたときはそのアップグレードイベントに紐づくearnエントリを追加します。支払いが返金されたら、その返金イベントに紐づくreversalエントリを投稿します。

自己紹介とよくある不正を厳しくせずに防ぐ方法

ほとんどの人は正直で、ごく一部が明らかなトリックを試します。目標は簡単な不正を止め、ルールを明確にし、同じWi-Fiや家族のカードを使う本当の顧客をブロックしないことです。

自己紹介を単純で説明可能なルールでブロックする

正当化できるハードブロックから始めましょう。紹介者と被紹介者が明らかに同一人物である場合（同じユーザーID、同じ確認済みメール、同じ支払い方法のフィンガープリントなど）にクレジットを付与しないでください。メールドメインルールは助けになりますが、狭くしてください。会社ドメインをすべてブロックすると正当なチームを傷つける可能性があります。

次にループや大量サインアップの軽量検出を追加します。初日から完璧な不正スコアを作る必要はありません。強いシグナルがいくつかあれば多くの不正を捕捉できます：短時間に同じデバイスから多数のサインアップ、同一IPレンジからの短時間の繰り返し使用、複数の「新規」アカウントで同じカード使用、メールを確認しないアカウントが大量にある、クレジット付与後の急速なキャンセルと再購読パターンなど。

クレジットが使えるようになる前に資格アクションを要求してください（例：メール確認＋有料請求など）。これによりボットや無料ティアの離脱がノイズを生むのを防げます。

正常なユーザーを罰しないで不正を遅らせる

紹介リンクと引換のレート制限やクールダウンを静かに追加してください。リンクが1時間で20回同じネットワークから使われたら報酬を一時停止してフラグを立てます。

介入するときは穏やかな体験を保ってください。クレジットを支払いが確定するまで保留にし、遅延の理由を平易に表示し（非難を避ける）、サポートに連絡する簡単な方法を提供し、エッジケースは自動バンではなく手動レビューに回してください。

例：スタートアップのチームが一つのオフィスIPを共有している場合、同じ紹介を通じて同日に3人の同僚がサインアップしても、適格な支払いと基本的なクールダウンがあればそれぞれクレジットを得られます。一方、ボットのような急増はレビュー保留になります。

現実の複雑ケース：返金、回収、アカウント変更

紹介プログラムは単純に見えますが、返金、チャージバック、請求の無効化、アカウントの所有権変更があると問題になります。これらを前もって設計すると怒ったユーザーや長いサポートスレッドを避けられます。

いつクレジットを回収するか（そしてどう回収するか）

クレジットは単なるサインアップに基づくものではなく、有料の結果に基づいて獲得されるものとして扱ってください。そして請求イベントに紐づく回収ポリシーを定義します。

サポートが説明できるルール例：

• 元の有料請求が全額返金またはチャージバックされた場合、付与された紹介クレジットを回収する。
• 支払いが確定する前に請求がキャンセルされた場合、クレジットは付与しない。
• もしクレジットが早めに付与されていた場合（例："invoice paid"で付与）、回収は自動的に行われ明確な履歴を残す。

部分返金はチームが詰まる部分です。一つのアプローチに絞って一貫させてください：比例回収（30%の返金に対してクレジットの30%を回収）か全額回収（どんな部分返金でも全額回収）。比例は公平ですが説明とテストが難しい。全額回収は単純ですが厳しく感じられることがあります。

トライアルから有料への移行も明確にしてください。一般的な方法はトライアル中はクレジットを保留にし、最初の成功した有料請求が確定した後にロックする（必要なら短い猶予期間後）、というものです。

アカウント統合と所有権変更

人はメールを変えたりアカウントを統合したり、個人使用からチームワークスペースへ移行します。何が本人についていき、何が支払いアカウントについていくかを決めてください。購読者がワークスペースである場合、クレジットはそのワークスペースに帰属することが多く、離脱するメンバー個人に残るわけではありません。

アカウント統合やチーム所有者の移転をサポートする場合は、履歴を書き換えるのではなく調整イベントを記録してください。すべての回収や手動修正には「invoice 10482 のチャージバック」や「Workspace owner transfer approved by support」のようなサポート向けの短い注記を含めてください。Koder.ai のようなプラットフォームでクレジットがサブスクリプションに適用される場合、それらの注記が「なぜクレジットが変わったのか？」に一度の照会で答えるための鍵になります。

サブスクリプションへのクレジット適用をきれいにする

追跡が難しいのは取引ではなく、クレジットを更新、アップグレード、ダウングレード、税金の扱いの中で一貫して振る舞わせることです。

まず、クレジットがどこで使えるかを決めてください。一部は次の新しい請求にのみ適用するチームもいれば、未払いの任意の請求書に適用できるようにするチームもあります。一つのルールを選びUIで示してユーザーを驚かせないでください。

次に、処理順を固定してください。予測可能なアプローチの一つは：サブスクリプション料金（按分を含む）を計算し、割引を適用し、税を計算し、最後にクレジットを適用する、というものです。クレジットを最後に適用すると税ロジックが一貫し、クレジットが課税対象額をどう減らすかで争いが起きにくくなります。法務/税務で別の順序が必要なら文書化しテストを書いてください。

按分（proration）は請求バグが最も出る箇所です。誰かが周期の途中でアップグレードしたら、按分のラインアイテム（請求またはクレジット）を作り、それを他のラインアイテムと同様に扱ってください。そして紹介クレジットは個別のラインアイテムではなく請求書合計に適用してください。

請求ルールを厳しく保ってください：

• クレジットは顧客の支払額を減らすが、請求額を$0未満にはしない
• 未使用のクレジットは将来に繰り越す
• クレジットは一定の順序（古いものから）で適用し、結果を再現可能にする
• 請求が無効化または返金された場合、その請求で実際に消費されたクレジットのみを回収する

例：ユーザーが月の途中でアップグレードして$12の按分請求が出た。割引と税で請求合計が$32になった。紹介クレジットが$50ある場合、$32を適用して請求を$0にし、残りの$18は次回の更新で使えるように保持されます。

実装ステップ（MVPからv1へ）

紹介プログラムを作るときはマーケティング機能ではなく小さな請求機能として扱ってください。目標は退屈な一貫性です：すべてのクレジットに理由、タイムスタンプ、次の請求への明確な道筋があること。

MVP（数日で出せる範囲）

1つのコンバージョンイベントと1つのクレジットルールを選んでください。例：招待されたユーザーが有料購読者になり最初の支払いが成功したときにのみ紹介が有効となる、など。

MVPはエンドツーエンドのパスに焦点を当てます：サインアップ時に紹介トークンまたはコードを捕捉し、支払い成功時に適格判定を行い（ユーザーがカードを入力した瞬間ではなく）、ユニークなidempotencyキーで台帳エントリを書き、次回の請求に予測可能な順序でクレジットを適用します。

真実のソースを早く決めてください。請求プロバイダをソースにしてアプリがそれをミラーするのか、内部台帳をソースにして請求側には「請求書にXクレジットを適用してくれ」と送るのか。両者を混在させると「クレジットが消えた」チケットが増えます。

v1（サポート可能にする）

追加ルールを増やす前に管理ツールを追加してください。サポートはユーザー、紹介コード、請求書で検索し、次のタイムラインを見られる必要があります：invite、signup、qualification、credits granted、credits spent、reversals。手動調整も含め、短いメモを必須にしてください。

その後ユーザー向けUXを追加します：紹介ページ、各招待のステータス行（pending、qualified、credited）、請求と一致するクレジット履歴など。

最後にモニタリングを追加します：紹介の急増、高い回収率（返金やチャージバック）、同一デバイスや支払い方法の多発などの異常パターンをアラートする。これにより不正対策を強固にしつつ正常なユーザーを罰しない運用ができます。

例：誰かがKoder.aiの紹介をチームと共有した場合、最初の成功した有料購読後にのみクレジットが表示され、それらのクレジットは手動クーポンではなく自動的に次の更新で差し引かれるべきです。

請求バグとサポート負荷を生む一般的な誤り

ほとんどの紹介プログラムの失敗はマーケティングではなく請求で起きます。クレジットが予測不能に感じられるとチケットが増えます：ユーザーはなぜ得たのか、いつ適用されるのか、なぜ請求書が違うのか分からない。

よくある罠はルールが明確でないまま構築することです。"qualified referral"があいまい（トライアル開始、最初の支払い、30日保持など）だと、ケースバイケースで交渉して返金で帳尻を合わせる羽目になります。

もう一つの問題は可変の"credit balance"フィールドを使うことです。一見シンプルですが、再試行、返金、プラン変更、手動調整が出ると数値がずれて由来が分からなくなります。

冪等性も見落とされがちです。支払プロバイダはWebhookを再送し、ワーカーはジョブを再試行し、ユーザーは二度クリックします。"award credit"が冪等でないと重複クレジットが発生し、収益データにずれが出ます。

クレジットの適用順序のミスでも問題が起きます。クレジットを税の前に適用したり按分ルールを無視すると、請求プロバイダの期待と合わず領収書や決済失敗、照合の問題につながります。

不正チェックを厳しくしすぎることもあります。IPやデバイス、ドメインでブロックしてレビュー手段がないと、ルームメイトや同僚など正当な紹介を止めてしまいます。

注意すべき5つのレッドフラッグ：

• 資格ルールがコード内にしかなく管理/サポート画面に見えない
• クレジットに重複を防ぐユニークなイベントキーがない（invite_id, conversion_idなど）
• "Balance"が上書きで保存され、台帳エントリを追加していない
• 請求書がクレジットをプロバイダと異なる順序で適用している（税、按分、割引）
• 不正防止に異議申し立てや手動オーバーライドの道がない

例：Koder.aiのProユーザーが月途中でアップグレードし紹介クレジットを得てからダウングレードした場合、単一の残高フィールドを使いクレジットを按分前に適用すると次回請求が不自然になり長いサポートスレッドにつながります。台帳と固定された適用順序があればこれを防げます。

クイックチェックリスト、単純な例、次のステップ

出荷前にいくつかのチェックを実行すれば多くの請求とサポートの問題を早期に発見できます。

• 1アカウントにつき1人の紹介者：一度帰属したら勝手に変えない
• 明確な資格：クレジットを得る正確なイベントを定義（例：最初の有料請求が成功し返金されていない）
• 台帳を使う：すべてのクレジットとデビットをエントリとして保存する
• 回収を用意する：返金、チャージバック、キャンセルで回収エントリを作成する
• 管理者調整はログに残す：手動付与/削除も台帳エントリで理由を残す

例：MayaがNoahを招待。NoahはMayaの招待からサインアップしトライアルを経てProにアップグレードし$30を支払った。システムはその請求を適格とマークし、Mayaに（例：$10）を付与する台帳エントリを作成する。

次の更新でMayaの請求小計が$30であれば、請求処理は最大$10を利用可能クレジットから適用し、請求書は$30小計、-$10クレジット、$20の支払額を示します。Mayaの台帳にはearn（+$10）とspend（-$10 invoice #1234へ適用）の二つのエントリが残ります。

もしNoahがその最初の支払いの返金を要求したら、システムはMayaの獲得クレジットを削除するreversalエントリを追加します。既に使われていたクレジットがあれば履歴を書き換えるのではなく次回の請求で差額を請求します。

継続的に進めるための二つの次のステップ：

1. 帰属、資格、台帳エントリ、請求への適用、回収を含むフルフローを短い設計ドキュメントでプロトタイプする。

2. サンドボックスで固定シナリオをテストする：トライアル→有料、クレジット使用後の返金、周期途中でのアップグレード／ダウングレード、管理者による調整。

速く進めつつ請求ロジックを失わないようにするなら、Koder.ai includes Planning Mode plus snapshots and rollback, which can help you iterate on the referral flow until invoice math stays consistent. You can do the whole pass inside the platform at koder.ai, then export the code when you’re ready.