APIリファレンス：サブスクリプション

継続課金です。Crypto Botに対する拡張にあたります。 プラン（金額と期間）を作り、その承認リンクをユーザーに送ると、期間ごとにユーザーのウォレット残高から自動で課金され、手数料を引いた額がアプリの残高に入ります。 共通の決まりはMerchant APIリファレンスにまとめています。

モデル

プランは変更できないスナップショットです。 ユーザーが承認するのは、この期間にこの金額という内容そのものです。 価格を変えるには、新しいプランを作って古いプランをアーカイブします。 すでに登録している人は、承認した条件のまま更新を続けます。 最初の期間は、承認の時点で課金されます。

更新は、期間の終わりごとに自動で課金されます。 更新が失敗すると（残高不足、アカウントの制限など）、サブスクリプションはgraceに入り、プラットフォームが設定した猶予期間のあいだ1時間おきに再試行されます。 それでも回収できない場合はexpiredになります。 加盟店はcurrent_period_endをアクセスの期限として読んでください。

ライフサイクルのイベントには、それぞれ選んで受け取るWebhookがあります。 subscription_activated・subscription_charged・subscription_cancelled・subscription_expiredです。

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan、スコープはsubscriptionsです。

パラメーター	型	必須	説明
name	string	必須	1〜64文字。登録者に表示されます
asset	string	必須	資産コード
amount	string	必須	1期間あたりの課金額。正の10進数の文字列
period_days	integer	必須	課金の期間（日数）。プラットフォームの最小値（短すぎる場合はinvalid_periodで案内）から365まで

結果はプランオブジェクトです。 plan_id・name・asset・amount・amount_minor・period_days・archived・mini_app_subscribe_url（ユーザーに送る承認用のt.meリンク）・created_atです。

エラーは400 unknown_asset・400 invalid_amount・409 invalid_period・503 subs_disabled（機能を利用できない）・409 too_many_plans（新規作成前に未使用のプランをアーカイブする必要がある）です。

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans、スコープはread、パラメーターはありません。 {"items": [plan, …]}を新しい順に返します。 どのプランにもactive_subscribersが1つ加わります。 これは、そのプランで継続中の（activeとgraceの）サブスクリプションの件数です。

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan、スコープはsubscriptionsです。 パラメーターはplan_idの1つです。 新しい承認を止めます。 既存のサブスクリプションは、承認時の条件で更新を続けます。終了する場合は、cancelSubscriptionで1件ずつキャンセルしてください。 アーカイブはAPIからは取り消せません。 結果はarchived: trueになったプランオブジェクトです。 エラーは404 plan_not_foundです。

getSubscriptions

GET /pay/api/getSubscriptions、スコープはreadです。 絞り込みはplan_id・user_id・status（active・grace・cancelled・expired）と、offset・count（最大500）です。 {"items": [subscription, …]}を新しい順に返します。

サブスクリプションオブジェクトは、subscription_id・plan_id・user_id（登録者のTelegram ID）、スナップショットの条件（asset・amount・amount_minor・period_days）、status・auto_renew・period_no（ここまでに支払われた期間の数）・current_period_start・current_period_end・created_at・cancelled_at・cancelled_by（userまたはmerchant）・expired_atです。

cancelSubscription

POST /pay/api/cancelSubscription、スコープはsubscriptionsです。 パラメーターはsubscription_idの1つです。 更新を止めます（cancelled_by: "merchant"）。 支払い済みの期間はcurrent_period_endまで使え、ステータスはすぐcancelledになり、登録者に通知が届きます。 キャンセルした人は、プランとアプリが引き続き利用可能なら、同じリンクから再承認できます。再承認するとすぐに課金され、新しい期間が始まります。 結果は、更新後のサブスクリプションオブジェクトです。

エラーは404 sub_not_found・409 sub_not_active（すでにキャンセル済み、または期限切れ）です。