stigg-credits

Stigg Credits — クレジットベースのマネタイズ

このスキルは、クレジットに関する一連の機能の標準的な参照先です。クレジット通貨の定義、クレジットの付与（定期付与／前払い／プロモーション／手動／オーバードラフト）、実行時の消費（マッピング、カスタム数式、台帳）、自動チャージ、シートベースのプール、請求との統合、収益認識を扱います。静的な カタログ の形式（プラン／アドオンにエンタイトルメントとして紐付ける定期クレジット付与）は stigg-pricing-modeling/references/credits-modeling.md にあり、それ以外はすべてこのスキルで扱います。

始める前に

親となる stigg スキルに従い、まず検索してください。 クレジットの機能は急速に進化しています（カスタム数式、オーバードラフトの仕組み、シートベースのプールは最近追加されました）。執筆前に、Mintlify Stigg docs MCP（search_stigg、query_docs_filesystem_stigg）を使って詳細を確認してください。

メンタルモデル — 5つの要素

                              ┌──────────────────────────────────┐
                              │   Credit currency (the unit)     │
                              │   "AI tokens", "API credits",    │
                              │   "compute units"                │
                              └────────────────┬─────────────────┘
                                               │ denominates
                                               ▼
   Grants funded by:        ┌──────────────────────────────────┐
   • Recurring (plan/addon)  │   Credit pool (per customer,    │
   • Prepaid (purchase)      │   per credit currency)          │
   • Promotional (zero cost) │   = balance + many grants       │
   • Manual                  └────────────────┬─────────────────┘
   • Overdraft (system)                       │ deducted by
                                              ▼
                              ┌──────────────────────────────────┐
                              │   Consumption mapping or         │
                              │   custom formula  (per plan)     │
                              │   metered feature → credits      │
                              └────────────────┬─────────────────┘
                                               │ records
                                               ▼
                              ┌──────────────────────────────────┐
                              │   Credit ledger (append-only)    │
                              │   grants, burns, expirations,    │
                              │   revocations, adjustments       │
                              └──────────────────────────────────┘

references/grants.md、references/consumption.md、references/ledger.md、references/auto-recharge.md、references/seat-pools.md、references/custom-formulas.md、references/billing-integration.md、references/revenue-recognition.md。

クレジット通貨

クレジット通貨（Stigg アプリのカタログ UI では「クレジットタイプ」と呼ばれます）は、消費単位です。たとえば、tokens、credits、compute units があります。顧客が従量課金機能を利用すると、その通貨建てのプールから差し引かれます。

• 通貨のライフサイクル全体（定義、更新、アーカイブ、アーカイブ解除、一覧表示、関連するプラン／アドオンの確認）は、Stigg MCP（AI 支援開発に推奨）または Stigg アプリの「Product Catalog → Credits」から利用できます。 通貨 → 従量課金機能 → プランごとの消費マッピング → 付与 → 使用状況レポート、という一連のクレジット消費ワークフローは、すべて MCP で実行できます。執筆前に、実際の MCP ツール一覧またはドキュメントを最新の状態にしてください。操作名とフィールド形式は、このスキルではなく実際のサーフェスで管理されています。
• 「token」／「tokens」のような単数形／複数形の表示名と、変更不可の ID を使用します。アーカイブする前に依存関係を確認してください。有効なプランまたはアドオンがその通貨を参照している間、Stigg はアーカイブをブロックします。
• 通貨間で相互交換はできません。ある通貨に対する使用量を、別の通貨から消費することはできません。
• 請求通貨ではありません。 カスタムクレジット通貨は消費単位です。複数通貨での請求（USD/EUR/JPY）については、stigg-pricing-modeling/references/price-localization.md を参照してください。
• カタログ側のモデリング形式（プラン／アドオンにエンタイトルメントとして紐付ける定期付与）については、stigg-pricing-modeling/references/credits-modeling.md を参照してください。

クレジットプール

(customer, credit currency) ごとに1つのプールがあり、複数の製品を同時に有効にしている場合は resourceId ごとにもプールが作成されます。プールには複数のクレジットブロック（「付与」または「割り当て」とも呼ばれます）が含まれます。各ブロックには amount、ライフサイクル日付（effective_at／expires_at）、category（有料／プロモーション）、cost_basis（クレジットあたりの金額。収益認識に使用）、priority（値が小さいほど優先度が高い）、status があります。フィールドの全リファレンスは references/grants.md を参照してください。

5種類の付与

種類	発生元	原価基準	通常の頻度
定期付与	プラン／アドオンのエンタイトルメント	有料（プランの価格）	請求サイクルごと（月次／年次など）
前払い	顧客による前払い購入	有料	1回限りのパック
プロモーション	導入促進／インセンティブ目的の手動付与	ゼロ（収益には影響しません）	1回限り。通常は期間限定
手動調整	管理者による追加または削除	有料またはゼロ（管理者が選択）	随時
オーバードラフト	システムが生成し、マイナス残高を追跡	該当なし	自動作成、自動精算

モデリング形式（プランまたはアドオンにエンタイトルメントとして紐付ける定期クレジット）は、stigg-pricing-modeling/references/credits-modeling.md で説明しています。実行時のクレジット付与（前払い／プロモーション／手動）については、こちらの references/grants.md を参照してください。

消費 — プランで設定

従量課金機能をクレジットに換算する方法は、機能やクレジット通貨ではなく、プラン（および各アドオン）で設定します。各プランでは、一定の換算レート（1 token = 1 credit）または各ディメンションに基づくカスタム計算式（credits = 2.5 × input + 10 × output）を選択できます。同じ機能に対して、プランごとに異なるルールを設定できます。

パス：製品カタログ → プラン → プランを選択 → 価格を編集 → 価格を設定 → クレジット消費（プランの従量課金機能ごと）。

消費順序 — 複数の付与が対象となる場合

イベントで N クレジットを消費する際、Stigg は次の順序でどの付与から差し引くかを決定します。

1. 優先度 — 数値が小さいほど優先度が高くなります。
2. 有効期限 — 有効期限が早い付与から消費します。
3. カテゴリ — その他の属性が同じ場合、プロモーション分を有料分より先に消費します。
4. 有効開始日 — 有効開始日が早いものから消費します。
5. 作成日 — ほかの条件がすべて同じ場合、古いものから消費します。

1 つのイベントで必要なクレジットが最優先の付与の残高を超える場合、Stigg は次の付与から、さらにその次の付与から消費します。消費した付与ごとに、個別の台帳エントリーが作成されます。具体例は references/consumption.md を参照してください。

超過使用 — マイナス残高

Stigg はクレジット残高がマイナスになることをサポートしています。使用イベントで顧客の保有クレジットを超える量が必要になると、不足分を追跡するために超過使用付与が自動作成されます。常に有効で、無効にする方法はありません。 超過使用付与の特徴は次のとおりです。

• grant_type: OVERDRAFT、amount: 0、consumed_amount = 不足分。
• (customer, currency) ごとに 1 つの超過使用付与（リソース単位のスコープがある場合は、リソースごとにも 1 つ）。
• 手動で編集または無効化することはできません。
• 新しいクレジットが付与されると、自動的に全額または一部が精算されます。

詳細な動作と具体例：references/consumption.md。

カスタム消費計算式

変動コストのワークロード（複数モデルの LLM 操作、複数入力の処理、トークンコストの重み付け）では、固定の換算レートの代わりにカスタム計算式を定義できます。

credits_used = (a × documents) + (b × emails) + (c × images)
credits_used = (1.1 × model1_tokens) + (1.5 × model2_tokens) + (5 × model3_tokens)

従量課金機能ごとに、製品カタログ → プラン → 価格を編集 → 価格を設定 → クレジット消費 → 計算モード：高度な計算式で設定します。詳細な仕組みは references/custom-formulas.md を参照してください。

自動チャージ

残高がしきい値を下回ったときにクレジットを自動購入して、顧客の前払い残高が枯渇するのを防ぎます。

設定	説明
クレジット残高が次の値を下回ったとき	チャージを開始するしきい値です。
クレジット残高を次の値まで回復	チャージ後の目標残高です。
月間総支出を次の額に制限	期間ごとの自動チャージ支出の上限です。
支出上限をリセットする間隔	上限をリセットする頻度です。
付与の有効期限	自動購入したクレジットの有効期間です。
支払い方法	自動チャージに使用するカードなどです。

処理が必要な Webhook イベント：

• automatic_recharge.operation.attempted — 成功と失敗を問わず、すべての試行で発火します。
• credits.automatic_recharge_limit_exceeded — 支出上限の 80%、90%、100% に達したときに発火します。
• automatic_recharge.configuration.changed — システムによる変更（支払い失敗など）を含め、有効化または無効化されたときに発火します。

設定手順：references/auto-recharge.md。

シート数に応じたクレジットプール

定期的なクレジット付与を従量課金のシート機能に紐付け、チームの規模に応じてクレジットを増やせます。

「1 シートあたり月 1,000 AI クレジット」→ 5 シートなら月 5,000 クレジット → 6 つ目のシートを追加すると、さらに 1,000 クレジットが自動的に付与されます。

クレジットはユーザーごとの個別プールではなく、共有プールに入ります。組織全体で 1 つの残高を利用します。Stripe との連携が必要です。 クレジットの権利と従量課金のシート機能の両方が含まれるプランまたはアドオンで利用できます。設定方法は references/seat-pools.md を参照してください。

請求との連携

Stigg は請求スタックと並行して機能します。全面的な置き換えは不要です。請求プロバイダー（Stripe／Zuora／カスタム）は、支払い、税金、請求書、支払い方法を処理します。Stigg はクレジットプール、付与、消費、適用を処理します。

金銭が動くとき：

イベント	Stigg の反応
顧客が支払う	Stigg は金額、cost_basis、日付を含む有料付与を作成し、プールを更新して、台帳に記録します。
プロモーションを発行	Stigg は cost_basis がゼロの付与を作成します（収益への影響はありません）。
返金／取り消し	繰延収益と認識済み収益の整合性を保つため、対応する付与を Stigg で取り消します。

システムの境界（各システムが管理するもの）：

• **請求システム：**製品カタログと価格、税金、請求書発行、支払い、返金、債権回収。
• **Stigg：**クレジット通貨（カタログ UI では「credit types」と呼ばれます）、プール、付与、リアルタイム消費、台帳、顧客ウィジェット。

一般的なフロー（セルフサービストップアップ、営業主導の請求書、自動トップアップ）：references/billing-integration.md。

収益認識

Stigg は、監査可能な証跡を経理部門に提供します。付与ごとに、amount_granted、amount_remaining、amount_consumed、expires_at、category、cost_basis（単位あたり）が記録されます。追記専用の台帳には、すべての消費／期限切れ／取り消しが記録されます。

Deferred revenue   = amount_remaining × cost_basis      (paid grants only)
Recognized revenue = consumed_in_period × cost_basis
Breakage           = expired_in_period × cost_basis     (per your policy)

プロモーション付与の cost_basis はゼロのため、収益に影響することはありません。仕訳モデル全体と照合パターンについては、references/revenue-recognition.md を参照してください。

クレジットの Webhook

クレジット固有のイベント（credit.balance.low／.depleted、credit.grant.*、automatic_recharge.*）は、アプリ内通知、再獲得キャンペーン、支払い失敗時のフローを駆動します。ペイロードの形式、署名の検証、再試行の仕様、ハンドラーのひな形については、stigg-webhooks を参照してください。

このスキルを使用しない場合

• クレジット以外の機能／プラン／アドオンをモデル化する場合 → stigg-pricing-modeling。
• ブール値／構成機能（クレジットを伴わない）のランタイム権限チェックを行う場合 → stigg-entitlements。
• サブスクリプションをプロビジョニング／キャンセルする場合 → stigg-subscriptions。
• そもそもクレジットが適切な価格モデルかどうかを判断する場合 → stigg-pricing-expert。

よくある間違い

間違い	修正方法
オーバードラフトを無効にしようとする	設定できません。システムはイベントを拒否せず、常に不足分を記録します。この仕様を前提に計画してください。
プロモーションの cost_basis をゼロ以外に設定する	収益認識が汚染されます。プロモーションではゼロにする必要があります。
サブスクリプションのプロビジョニング前にクレジットを付与する	付与は可能です（プールは保持されます）が、多くのチームはクレジットをプランのライフサイクルに連動させたいと考えています。期待される動作を確認してください。
付与ごとに優先度の数値を場当たり的に決める	数値が小さいほど優先度は高くなります。規則（例：プロモーション＝1、定期＝10、プリペイド＝20）を文書化し、それに従ってください。
プランに消費マッピングを追加し忘れる	マッピングを設定するのは機能ではなく、プランです。カタログに従量制機能を追加しても、既存のプランでクレジットが消費されるようにはなりません。各プランに独自のマッピングが必要です。
プランではなく機能に数式を設定する	機能は測定対象を定義し、測定値をクレジットに換算する方法はプランが決定します。同じ機能でも、プランごとに異なるレートや数式を使用できます。
トークンモデルごとの価格を個別の機能としてモデル化する	代わりにカスタム数式を使用してください。credits_used = w1 * tok1 + w2 * tok2
決済方法が失敗する状態で自動チャージを設定する	Stigg は automatic_recharge.configuration.changed を発行し、自動チャージを無効にします。アプリですぐにこの状態を通知してください。
クレジット残高の UI を一から構築する	Stigg にはすぐに使えるウィジェット（クレジット残高、利用状況、使用量チャート、付与テーブル、自動チャージのステータス、自動チャージの設定）が用意されています。stigg-widgets を参照してください。
cost_basis なしでクレジットデータを BI にエクスポートする	cost_basis がないと収益を計算できません。エクスポートには必ず cost_basis と付与 ID を含めてください。
台帳が結果整合性を持つものとして扱う	台帳は追記専用で、正しい情報源です。財務照合には台帳から読み取り、個々のイベントから再構築しないでください。