API reference: subscriptions

Recurring billing — Crypto Bot ke upar ek extension. Aap ek plan banate hain (amount + period), users ko uska approval link bhejte hain, aur platform har period unke wallet balance se charge karta hai aur fee kaat kar aapke app balance mein credit kar deta hai. Conventions Merchant API reference page par hain.

Model

Plan ek immutable snapshot hota hai: user jo mandate approve karta hai wo theek isi amount aur isi period ka hota hai. Price badalne ke liye naya plan banayein aur purana archive karein — maujooda subscribers unhi terms par renew hote rehte hain jo unhone approve ki thi. Pehla period approval par hi charge hota hai.

Renewals har period ke end par apne aap bill hote hain. Jab renewal fail hota hai (funds kaafi nahi hain, restricted account), subscription grace mein chali jaati hai aur platform grace period ke andar (abhi 48 hours) har ghante retry karta hai; phir bhi collect na ho paaye to subscription expired ho jaati hai. Merchants current_period_end ko access deadline ki tarah padhte hain.

Har lifecycle event ka ek opt-in webhook hai: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — scope subscriptions.

Parameter	Type	Zaroori	Matlab
name	string	haan	1–64 characters, subscriber ko dikhta hai
asset	string	haan	asset code
amount	string	haan	har period ka charge, positive decimal string
period_days	integer	haan	billing period din mein, platform ke minimum (abhi 7) se 365 tak

Result plan object hota hai: plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url — wo t.me link jo aap users ko approve karne ke liye bhejte hain — aur created_at.

Errors: 404 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled (feature platform ki taraf se band hai).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — scope read, koi parameters nahi. {"items": [plan, …]} deta hai, sabse naya pehle, har ek ke saath ek extra field: active_subscribers — us plan par live (active + grace) subscriptions ki ginti.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — scope subscriptions. Ek parameter: plan_id. Naye approvals rok deta hai; maujooda subscriptions apne snapshot par renew hoti rehti hain (unhe ek-ek karke cancelSubscription se khatam karein). Archive karne ko API se undo nahi kiya ja sakta. Result archived: true ke saath updated plan object hota hai. Error: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — scope read. Filters: plan_id, user_id, status (active / grace / cancelled / expired), aur saath mein offset / count (max 500). {"items": [subscription, …]} deta hai, sabse naya pehle.

subscription object: subscription_id, plan_id, user_id (subscriber ka Telegram ID), snapshot terms (asset, amount, amount_minor, period_days), status, auto_renew, period_no (ab tak pay ho chuke periods), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user ya merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription — scope subscriptions. Ek parameter: subscription_id. Renewals rok deta hai (cancelled_by: "merchant"); jo period pay ho chuka hai wo current_period_end tak chalta rehta hai, status turant cancelled ho jaata hai, aur subscriber ko notify kiya jaata hai. Cancel ho chuka subscriber baad mein usi plan link se dobara approve kar sakta hai. Result updated subscription object hota hai.

Errors: 404 sub_not_found, 409 sub_not_active (pehle hi cancel ya expire ho chuki).