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

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

モデル

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

更新は、期間の終わりごとに自動で課金されます。 更新が失敗すると（残高不足、アカウントの制限など）、サブスクリプションはgraceに入り、猶予期間（現在は48時間）のあいだ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	必須	課金の期間（日数）。プラットフォームの最小値（現在は7）から365まで

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

エラーは404 unknown_asset・400 invalid_amount・409 invalid_period・503 subs_disabled（プラットフォーム側で機能が止まっている）です。

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（すでにキャンセル済み、または期限切れ）です。