stigg-subscriptions

Stigg サブスクリプション — ライフサイクル運用

このスキルでは、日常的なサブスクリプション運用（プロビジョニング、プレビュー、更新、キャンセル、トライアル、複数サブスクリプションのプロダクト、およびプランバージョンの移行（公開後に既存のサブスクリプションをプラン v1 からプラン v2 に移行すること））を扱います。

始める前に

親となる stigg スキルに従い、まず検索してください。 プロビジョニングのオプション、課金サイクルの動作、トライアルからの移行の仕様は変わることがあります。作成を始める前に、該当する SDK／REST のページ（Mintlify Stigg docs MCP）を開いてください。

操作一覧

操作	目的	リファレンス
プロビジョニング	顧客にプランのサブスクリプションを作成します（アドオン、トライアル、課金情報を追加できます）	references/provisioning.md
プレビュー	プロビジョニング前に、仮のサブスクリプションの価格を計算します	以下に記載
更新	有効なサブスクリプションのプラン／アドオン／期間／数量／支出／クーポン／トライアルを変更します	references/updates.md
キャンセル	サブスクリプションを即時、期間終了時、または指定日に終了します	以下に記載
トライアル	トライアルの開始、有料プランへの移行、期限切れへの対応を行います	references/trials.md
複数の有効なサブスクリプション	1 人の顧客に複数のサブスクリプションを設定し、resourceId でスコープを指定します	以下に記載
プランバージョンの移行	公開後に既存のサブスクリプションをプラン v1 からプラン v2 に移行します	references/plan-version-migration.md

サブスクリプションのプロビジョニング

最小限のバックエンド呼び出し

const sub = await stigg.provisionSubscription({
  customerId: 'customer-123',
  planId: 'plan-pro',
  billingCountryCode: 'US',           // required for paid plans w/ price localization
});

プロビジョニングで指定できる項目は次のとおりです（一覧は references/provisioning.md を参照してください）。

• リソース ID — プロダクトで複数の有効なサブスクリプションが許可されている場合に必須です。
• 課金期間 — 有料プランの場合は、月次／年次などを指定します。
• プランの設定 — 前払いコミットメント料金および従量制エンタイトルメントの単位数、価格の上書きを指定します。
• アドオン — プランに対応したアドオンのリスト（および数量）を指定します。
• サブスクリプションの開始日 — Immediately（デフォルト）／EndOfCurrentBillingPeriod（有効な有料サブスクリプションがすでに存在する場合）／SpecificDate（過去の日付の場合は遡及適用となり、即時請求は行われません。未来の日付の場合はその日に有効になります）。
• 無料トライアル — 有料プラン／カスタムプランに適用できます。
• 支出管理 — minimumSpend、maximumSpend を指定します。
• 割引 — 適用するクーポン（カタログ全体に適用するもの、またはサブスクリプション固有のアドホックなもの）を指定します。
• 支払い方法 — automaticallyUsePaymentMethodOnFile／請求書を生成／Stigg 経由では支払いなし、から選択します。
• 課金サイクルの基準日 — UNCHANGED（デフォルト）／NOW を指定します。
• 日割り計算 — ProrateNow／ProrateOnNextInvoice／NoProration を指定します。

最も有利なエンタイトルメントのルール： 顧客の有効なエンタイトルメントが複数のソース（有効なサブスクリプション、アドオン、トライアル、プロモーション用エンタイトルメント、追加のプロダクトサブスクリプション）に由来する場合、Stigg はそのすべてから最も有利な値を選びます。「トライアルと有料プラン」のケースはこのルールの一例にすぎません。このルールは、ソースが重複する場合に常に適用されます。

サブスクリプションのプレビュー

プロビジョニングする前に、即時請求書と継続請求書をプレビューします。

const preview = await stigg.previewSubscription({
  customerId: 'customer-123',
  planId: 'plan-pro',
  billingPeriod: 'MONTHLY',
  addons: [{ addonId: 'addon-seats', quantity: 10 }],
  couponId: 'SAVE20',                          // optional
  subscriptionId: 'sub-789',                   // optional — preview an UPDATE to an existing sub
});

Node SDK／GraphQL では、immediateInvoice と recurringInvoice が返されます。各金額は { amount, currency } 形式の Money オブジェクトで、フィールド名は小文字の subtotal です。REST を直接呼び出す場合は、スカラー金額を含む、よりフラットな DTO が返され、フィールド名は subTotal（T が大文字）です。金額の単位は通貨のドル／単位そのもので、セントではありません。49 は 49.00 ドルを意味します（Stripe では逆の慣例が使われるため、Stripe に慣れた開発者は注意してください）。完全な形式と previewSubscription のユースケースについては、references/provisioning.md を参照してください。

サブスクリプションを更新する

重要： updateSubscription（GraphQL ミューテーション）では、プランを変更できません。サブスクリプションのプランを変更するには、provisionSubscription を再度呼び出してください。Stigg が適切な方法（プランタイプの移行に応じたインプレース更新または置き換え。下記の移行マトリックスを参照）を選択します。

// Update — addons, billing period, billable features, price overrides
await stigg.updateSubscription({
  subscriptionId: 'sub-123',
  addons: [{ addonId: 'addon-seats', quantity: 10 }],
  billingPeriod: 'ANNUAL',
});

// Change plan — re-provision (NOT updateSubscription)
await stigg.provisionSubscription({
  customerId: 'customer-123',
  planId: 'plan-pro',          // new plan
  // ...other provisioning fields
});

updateSubscription が直接サポートする内容（GraphQL ミューテーションの仕様に基づく）：

• 請求期間（有料プラン。例：MONTHLY → ANNUAL）。
• アドオン（既存の内容を置き換えます。新しいリスト全体を渡してください）。
• 課金対象の機能（前払い契約の数量、単位ごとの数量）。
• 価格の上書き。

Stigg アプリの UI で提供されるその他の更新フロー（トライアルの延長／短縮、利用上限の変更、クーポンの適用、請求サイクルのアンカーのリセット、変更時の按分）は、別の SDK メソッドまたは provisionSubscription の再呼び出しを介して行われます。特定の操作については、ドキュメントを検索してください。

スケジュール済みの更新はキューに追加されず、置き換えられます： 新しい更新は保留中のスケジュール済み更新を上書きし、すぐに適用されます（Stigg アプリの UI について記載されています。SDK の動作も一般的には同様ですが、使用する SDK のドキュメントで確認してください）。

詳しいフローとパターン：references/updates.md。

サブスクリプションをキャンセルする

@stigg/node-server-sdk を介して実行します（cancelSubscription GraphQL ミューテーションに変換されます）。

await stigg.cancelSubscription({
  subscriptionId: 'sub-789',                              // Node SDK uses subscriptionId
  subscriptionCancellationTime: 'END_OF_BILLING_PERIOD',  // or 'IMMEDIATE' / 'SPECIFIC_DATE'
  // endDate: '2026-06-01T00:00:00Z',                     // required when SPECIFIC_DATE
  // subscriptionCancellationAction: 'DEFAULT',           // or 'REVOKE_ENTITLEMENTS'
  // prorate: false,
});

フィールド名に関する注意： Node SDK では subscriptionId を使用します。Python／Go／Ruby／Java／.NET SDK と GraphQL ミューテーションでは subscriptionRefId を使用します。REST を直接呼び出す場合、ID は URL パスに指定します。

subscriptionCancellationTime：

値	動作
IMMEDIATE	すぐにキャンセルします。
END_OF_BILLING_PERIOD	現在の請求期間の終了時にキャンセルします。ほとんどの製品でのデフォルトです。カスタム価格のプランまたはトライアルのサブスクリプションには適用されません。
SPECIFIC_DATE	endDate で指定した日にキャンセルします。トライアル期間には適用されません。

subscriptionCancellationAction：

値	動作
DEFAULT	製品のデフォルトのキャンセル動作（製品ポリシーに応じて、アクセス権を取り消す または 無料プランにダウングレードします）。
REVOKE_ENTITLEMENTS	キャンセル時にすべてのエンタイトルメントをすぐに取り消します。

キャンセル後の状態：CANCELED（すでに終了）または CANCELLATION_SCHEDULED（保留中）。

REST を直接利用する場合（curl で https://api.stigg.io/api/v1 を呼び出す場合）：接頭辞のない REST フィールド名は cancellationTime、cancellationAction、endDate、prorate です。列挙値は同じです。

トライアル

トライアルは有料プランとカスタムプランに適用されます。デフォルトのトライアルはプランで定義し、プロビジョニング時に上書きできます。

• トライアル付きでプロビジョニングする — プロビジョニング時にトライアル設定を渡します。
• トライアルから有料プランに移行する — 有料サブスクリプションを重ねてプロビジョニングします。Stigg はトライアル終了時に有料プランを開始します。
• 移行されないままトライアルが期限切れになった場合 — trial.expired イベントが発生します。アプリから再獲得施策を開始してください。
• セルフサービスのフローでは、顧客が製品ごとに利用できるトライアルは 1 回です（管理者による上書きは可能です）。
• すでに支払いを行った顧客は、セルフサービスの無料トライアルを再度利用できません。

詳しい仕組みと例（アプリ内アップグレード、アドオン付きトライアル）：references/trials.md。

顧客ごとの複数の有効なサブスクリプション

マルチテナント製品（ワークスペース／プロジェクト／アプリ）では、1 人の顧客が resourceId のスコープごとに複数のサブスクリプションを持ちます。

const sub = await stigg.provisionSubscription({
  customerId: 'customer-123',
  resourceId: 'workspace-abc',
  planId: 'plan-team',
});

有効にすると（製品レベルの設定であり、製品の作成時に固定されます）：

• 関連するすべての呼び出しで resourceId を渡します — プロビジョニング、更新、エンタイトルメントの確認、使用状況の報告、ペイウォールウィジェット。
• 顧客は各ワークスペースで別々のプランを利用でき、すべて同じ支払い方法で支払えます。
• トライアルと有料プラン： (customer, resource) の組み合わせごとに、有効なトライアルサブスクリプションと有効な非トライアルサブスクリプションをそれぞれ最大 1 つ持てます。
• 単一インスタンス製品と組み合わせて（もう一方の製品を「有効なサブスクリプションは 1 つ」に設定）、「アカウント＋サブアカウント」／「プラットフォーム＋アプリインスタンス」のモデルを作れます。たとえば、Webflow のアカウント＋サイトごとのモデルです。

製品にサブスクリプションが 1 つでもあると、複数有効のオン／オフは切り替えられません。 製品の作成時に決めてください。

プランバージョンの移行（Catalog v1 → v2）

プランを再公開しても、既存のサブスクリプションは移行しない限り古いバージョンのままです。定期的に継続して行う運用です。

カタログ側の公開フロー（ドラフト、バージョンポリシー、グランドファーザー条項が適用される条件）については、stigg-pricing-modeling/references/plans.md を参照してください。このセクションでは、サブスクリプション側の移行方法を説明します。

移行には 2 つの方式があり、プランタイプの変更に基づいて Stigg が自動的に選択します。

パス	方式	理由
Free → Paid	新しいサブスクリプションをプロビジョニング	有料プランには請求対象のメトリクス値が必要です。
Free → Custom	新しいサブスクリプションをプロビジョニング	カスタムプランには、可変のエンタイトルメントの値が必要です。
Paid → Free	最新バージョンに移行	インプレースで移行します。
Paid → Custom	最新バージョンに移行	インプレースで移行します。既存の外部請求システムのサブスクリプションはキャンセルされず、Stigg 側のメタデータのみが削除されます。
Custom → Paid	新しいサブスクリプションをプロビジョニング	有料プランには請求対象のメトリクス値が必要です。
Custom → Free	最新バージョンに移行	インプレースで移行します。

移行の開始方法：

• UI： サブスクリプションを開き、⋮ → 最新バージョンに移行 → 直ちにまたは現在の期間の終了時を選択します。
• プログラムから： サブスクリプション移行のミューテーション／SDK メソッドを使用します。段階的なロールアウトが可能です。

移行が直ちに行われ、顧客の現在の価格が最新の公開価格と異なる場合、Stigg は日割り計算額を自動で請求または返金します。

移行の詳細については、references/plan-version-migration.md を参照してください。

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

• 機能／プラン／アドオンのモデル化 → stigg-pricing-modeling。
• 実行時のエンタイトルメント確認／使用状況の報告 → stigg-entitlements。
• 価格モデルに関する戦略的なアドバイス → stigg-pricing-expert。

よくある間違い

間違い	修正方法
複数有効の製品で resourceId を渡し忘れる	すべての呼び出し（プロビジョニング／更新／エンタイトルメント／使用状況／ウィジェット）で必要です。
スケジュール済みの更新をキューとして扱う	新しい更新は、スケジュール済みの更新を置き換えます。キューが必要な場合は、アプリでモデル化してください。
製品ポリシーで期間終了時のキャンセルが指定されているのに、直ちにキャンセルする	製品のデフォルト設定を使用し、直ちにキャンセルしたい場合にのみ明示的に選択してください。
カスタム価格のプランを期間終了時にキャンセルしようとする	キャンセルモーダルではサポートされていません。特定の日付を指定するか、請求担当者と調整してください。
すでに支払い済みの顧客にセルフサービストライアルを提供する	対象外です。管理者による上書きが必要です。アプリには適切な CTA を表示してください。
課金前に previewSubscription を実行しない	顧客は支払い額を事前に確認したいものです。まずプレビューし、その後プロビジョニングしてください。
大幅なアップグレードで billingCycleAnchor: NOW を設定しない	顧客の請求サイクルがずれていきます。変更時に新しい期間を開始する場合は、明示的にリセットしてください。