billing-setup

Credyt のセットアップ

ユーザーが課金モデルを理解できるよう案内し、その後、MCP ツールを使って Credyt のすべてを設定し、最後に課金サイクル全体をエンドツーエンドで自動検証します。このスキルは複数回実行できます。新しい製品の追加、価格の変更、追加アセットのセットアップに利用できます。

最初に、すでにあるものを確認する

検討を始める前に、credyt:list_assets と credyt:list_products を呼び出して現在の状態を確認します。

すでに製品が設定されている場合は、何があるかを伝えます。

「すでに [X] が設定されています。新しいものを追加しますか、既存の価格を変更しますか、それとも最初から始めますか？」

最初から始めたいと言われた場合も、既存の製品をアーカイブまたは削除しないでください。そのまま残します。ユーザーは会話を通じていつでも既存の製品を管理できます（例：「Pro 製品をアーカイブして」「この製品を削除して」）。自動で行うことは決してありません。

初めての場合は、最初から最後までヒアリングを進めます。

ヒアリング：ビジネスを理解する

質問は一度に1つずつ行います。次の質問をする前に、回答をよく聞きます。回答に応じて追加の質問を調整してください。これは会話であり、フォームではありません。

アプリでは何ができますか？

「アプリについて教えてください。何ができ、ユーザーは主にどんなことをしますか？」

追加の質問はすべて、そのアプリやユーザーの具体的な活動に即したものにします。

どの部分に費用がかかりますか？

「そうした活動のうち、提供するのに費用がかかるものはどれですか？たとえば、AI モデルを呼び出す場合、呼び出しごとにコストがかかります。費用の大きい部分はどこですか？」

これにより、課金対象のイベント、つまり追跡し、最終的に課金する活動を特定します。

どのような課金方法にしますか？

次の3つから選べるよう支援します。それぞれを抽象的な概念ではなく、ユーザーのアプリに即した例で説明します。

• 従量課金（前払いウォレット）：ユーザーが残高を追加します。活動ごとに残高から差し引かれます。残高がなくなると、ユーザーが追加チャージするか、サービスが一時停止します。OpenAI や Replicate がこの方式です。

• 月額サブスクリプション：利用量にかかわらず、毎月定額を請求します。Netflix のような従来型の SaaS モデルです。価格をまだ検討中の場合や、安定した収益を得たい場合に適しています。

• ハイブリッド（サブスクリプション＋クレジット）：月額料金に一定量のクレジットが含まれます。追加利用分には別途料金がかかります。Cursor や Clay がこの方式です。

まだ決まっていなくても大丈夫です

価格が決まっていない場合は、まず追跡を始めて、価格設定は後から行うよう案内します。

「問題ありません。今すぐ価格を決める必要はありません。まず、アプリ内の重要な活動と、それにかかる費用をすべて追跡できます。Credyt でユニットエコノミクスを確認し、実データに基づいて価格を設定できます。」

この方法を選ぶ場合は、価格をゼロまたは仮の値にして製品を設定し、イベントにコストを紐付けることを重視します。

ドル建てにしますか、それともクレジット建てにしますか？

「ユーザーに価格をドル（例：『動画1本あたり $2.50』）で表示しますか、それともクレジットやトークンなど独自の通貨（例：『動画1本あたり10クレジット』）で表示しますか？」

クレジットが適しているのは、裏側でコストが変動する場合、ユーザーが技術に詳しくない場合、ユーザーにクレジットを獲得させたい場合、または後から価格を調整する可能性がある場合です。

ドル建てが適しているのは、活動ごとのコストが固定されている場合、ユーザーが開発者である場合、価格を完全に透明化したい場合です。

迷っている場合は、後から柔軟に調整できるクレジットを提案します。

価格は変動しますか？

「何かによってコストは変わりますか？たとえば、高品質な出力ほど料金が高くなる、または別の AI モデルのほうが高価になる、といったことはありますか？」

変動する場合は、具体的な条件を確認します。これらは Credyt の価格ディメンションになります。

ヒアリングの確認

設定を始める前に、次の内容を理解できているか確認します。

• アプリの内容と重要な活動
• 費用がかかる活動
• 課金方法（従量課金、サブスクリプション、ハイブリッド、またはまず追跡）
• ドル建てか独自通貨か
• 価格が何らかのディメンションによって変動するか

不明な点があれば質問します。ヒアリングが完了するまで先に進まないでください。

MCP 経由で設定する

ユーザーに各手順を案内します。データを作成または変更する MCP 呼び出しを実行する前に、必ず設定予定のパラメーターを表で示し、明示的な確認を得てください。

「以下の設定で [X] を作成します。内容に問題はありませんか？」

フィールド	値
...	...

「実行前に変更したい点があればお知らせください。」

これは、アセット、商品、ベンダー、バージョン、調整の作成を含む、すべての変更に適用されます。特に精度、価格、イベントタイプについては、ユーザーが確認していない値を決して推測しないでください。

カスタム通貨を作成する（クレジット／トークン／コインを使用する場合）

カスタム通貨を選択した場合に限ります。これを使用する商品を作成する前に、必ず作成してください。

credyt:create_asset を使用します。精度を明示的に確認してください。通常、クレジットは整数（精度 0）ですが、必ず確認が必要です。たとえば、次のようにします。

フィールド	値
名前	Credits
コード	credits
精度	0（クレジットは整数、小数なし）
為替レート	1 クレジット = $0.05 → $1 で 20 クレジット

ユーザーが妥当性を確認できるよう、換算を具体的な値で説明してください。

作成後、credyt:quote_asset を使用して換算を確認します。$1、$10、$50 でそれぞれ何単位購入できるかを提示してください。

「換算を確認します……✓ $1 で 20 クレジット、$10 で 200 クレジット、$50 で 1,000 クレジットです。これで問題ありませんか？」

換算が正しくない場合は、credyt:add_asset_rate を使用して修正し、再度見積もりを出してください。

価格を設定して商品を作成する

課金対象となる各アクティビティについて、credyt:create_product を使用します。たとえば、次のようにします。

フィールド	値
名前	Image Generation
コード	image_gen
イベントタイプ	image_generated
使用量タイプ	unit
価格	イベントごとに 10 クレジット

ユーザーに確認する主なフィールド：

• 商品名とコード：課金項目の名称とその識別子
• イベントタイプ：課金のトリガーとなるアクティビティ名（例：「image_generated」）。アプリが送信する値と完全に一致する必要があります
• 使用量タイプ：発生ごと（「unit」）か、トークンなどの数量に応じたもの（「volume」）か
• 価格：イベントごとの料金

「まず計測を行う」場合は、価格をゼロに設定し、その旨を表に明記してください。

商品には、固定の定期価格と使用量に応じたリアルタイム価格の両方を設定できます。 たとえば、月額 $20 のサブスクリプションに AI ジョブごとに 1 クレジットを課金する場合、定期 USD 価格とイベントごとのクレジット価格を持つ単一の商品として設定できます。デフォルトでは、複数の価格を持つ単一の商品を使用してください。ユーザーが明確に希望した場合に限り、商品を分けて作成します。

既存商品の価格を更新する場合は、新しい商品を作成せず、必ず credyt:create_product_version を使用して新しいバージョンを作成してください。 これにより課金履歴が保持され、顧客は既存のサブスクリプションを継続できます。バージョンを作成する前にも、同じ確認用の表を提示してください。

各商品の作成または更新後、credyt:simulate_usage を使用して検証してください。シミュレーションでは、デフォルトに頼らず、必ず商品バージョンを明示してください（例：version: 1）。これにより、直前に設定した内容を確実にテストできます。

「テストしてみます。画像を 1 枚生成すると 10 クレジットかかるはずです……✓ 確認できました。10 クレジットが差し引かれ、これは $0.50 に相当します。想定どおりですか？」

シミュレーション結果が想定と異なる場合は、credyt:create_product_version を使用して正しい価格で新しい商品バージョンを作成し、正しくなるまで再度シミュレーションしてください。新しいバージョンを作成する前に、パラメーターを表で確認してください。

バージョン変更に関する注意：新しい商品バージョンを作成しても、既存のテスト顧客は引き続き古いバージョンを利用します。新しいバージョンを利用する新しいテスト顧客を作成するか、検証を実行する前に既存顧客のサブスクリプションを更新してください。

含まれるクレジット（特典）

課金モデルにサブスクリプションに含まれるクレジット（例：「月額 $20 に 1,000 クレジットを含む」）がある場合は、マイナス価格や別商品としてではなく、商品レベルで 特典 として設定します。

create_product（または create_product_version）の呼び出しに entitlements 配列を含めます。特典には 2 つのモードがあります。

定期付与 — クレジットがスケジュールに従って補充されます（例：毎月 1,000 クレジット）。

"entitlements": [
  {
    "name": "Monthly Credit Allowance",
    "asset": "{assetCode}",
    "amount": 1000,
    "purpose": "bundled",
    "lifecycle": {
      "duration": "month",
      "duration_count": 1,
      "refresh": {
        "strategy": "expire_and_replace"
      }
    },
    "accounting": {
      "revenue_basis": 0.00,
      "cost_basis": "auto"
    }
  }
]

1 回限り — クレジットが一度だけ付与され、補充されません（例：新規登録ボーナスやプロモーション付与）。lifecycle.refresh は省略します。

"entitlements": [
  {
    "name": "Welcome Bonus",
    "asset": "{assetCode}",
    "amount": 500,
    "purpose": "promotion",
    "lifecycle": {
      "duration": "month",
      "duration_count": 1
    },
    "accounting": {
      "revenue_basis": 0.00,
      "cost_basis": "auto"
    }
  }
]

lifecycle.duration は有効期限の期間を設定し、duration_count はその期間に乗じる数値を設定します（例：duration: "month", duration_count: 3 の場合、3 か月後に期限切れになります）。purpose は、サブスクリプションに含まれるクレジットの場合は "bundled"、1 回限りの付与の場合は "promotion" です。

作成前に、標準のパラメータ表を使って、特典のフィールド（名前、アセット、数量、有効期間、補充の有無）をユーザーに確認してください。

含まれるクレジットをマイナスの固定価格としてモデル化しようとしないでください。これは検証に失敗し、正しい方法ではありません。

コスト追跡を設定する（この項目について確認する）

検証の前に、各アクティビティのコストを追跡するかどうかを尋ねます。

「各アクティビティに実際にかかるコストを追跡しますか？ たとえば、画像生成に API 料金として $0.03 かかる場合、Credyt はそのコストを収益とあわせて記録し、リアルタイムで利益率を確認できるようにします。」

はいの場合、サービスプロバイダー（OpenAI、Anthropic、AWS など）ごとに credyt:create_vendor を使ってベンダーを作成します。

「画像生成に OpenAI を使用するとおっしゃっていたので、コストを追跡できるよう、コストプロバイダーとして登録します。」

アプリから使用状況イベントを送信する際に、ベンダーと金額を含む costs 配列を含めることを説明します。Credyt はその後、利益を自動的に計算します。

いいえの場合、問題ありません。コスト追跡は後から追加できます。

設定を検証する

すべての商品を設定したら、請求サイクルのテストを自動的に実行します。尋ねずに実行してください。

「それでは、テスト請求サイクルを実行して、すべてが最初から最後まで正しく動作することを確認します……」

このセッションで作成または変更した各商品に対して検証を実行します。各商品について、skills/billing-verification/references/procedure.md に記載された 6 段階の手順に従います。

いずれかの手順が失敗した場合は、何が問題だったかを説明して修正を支援し、その商品の検証を再実行します。

「テスト顧客はアカウントに残ります。テストモードなので、影響はありません。」

まとめ

作成・検証した内容を要約し、次のステップを提案します。

「Credyt で設定および検証した内容は次のとおりです。

• [作成したアセットの一覧]
• [価格の概要と検証ステータスを含む商品の一覧]
• [作成した場合はベンダーの一覧]

アプリへの組み込みを始める準備ができたら /credyt:billing-integration を実行してください。商品を追加する場合は、再度 /credyt:billing-setup を実行してください。」

次のステップ

このスキルで設定するのは商品と価格のみです。統合コードを自分で書かないでください。SDK の形式、エンドポイント、認証ヘッダーは誤りやすいためです。

次に billing-integration スキルを実行します。インストールされていない場合は、ユーザーにインストールを依頼してください。

「npx skills add credyt/ai-tools を実行してから、billing-integration スキルの実行を依頼してください。」

スキルを利用できず、ユーザーから統合コードの作成を明示的に依頼されていない場合は、ここで停止し、インストールされるのを待ちます。独自に fetch 呼び出しを実装したり、API エンドポイントを考案したりしないでください。

アプリケーションコードから Credyt API を呼び出す場合は、公式 SDK のいずれかを使う方法が推奨されます。@credyt/api-client（TypeScript/Node.js）または credyt-api（Python）を使用してください。どちらの SDK もスタックに適さない場合は、billing-integration スキルで HTTP の直接呼び出しについても説明しています。