सब्सक्रिप्शन - Dodo Payments Documentation

सब्सक्रिप्शन आपको automated renewals के साथ निरंतर access बेचने की सुविधा देते हैं। प्रत्येक customer के लिए pricing को अनुकूलित करने हेतु flexible billing cycles, free trials, plan changes और add-ons का उपयोग करें।

Upgrade & Downgrade

Proration और quantity updates के साथ plan changes नियंत्रित करें।

On‑Demand Subscriptions

अभी mandate authorize करें और custom amounts के साथ बाद में charge करें।

Customer Portal

Customers को plans, billing और cancellations manage करने दें।

Subscription Webhooks

created, renewed और canceled जैसे lifecycle events पर प्रतिक्रिया दें।

सब्सक्रिप्शन क्या हैं?

सब्सक्रिप्शन recurring products होते हैं जिन्हें customers किसी schedule के अनुसार खरीदते हैं। ये इनके लिए आदर्श हैं:

SaaS licenses: Apps, APIs या platform access
Memberships: Communities, programs या clubs
Digital content: Courses, media या premium content
Support plans: SLAs, success packages या maintenance

मुख्य लाभ

Predictable revenue: Automated renewals के साथ recurring billing
Flexible cycles: Monthly, annual, custom intervals और trials
Plan agility: Upgrades और downgrades के लिए proration
Add-ons और seats: Optional, quantifiable upgrades जोड़ें
Seamless checkout: Hosted checkout और customer portal
Developer-first: Creation, changes और usage tracking के लिए स्पष्ट APIs

सब्सक्रिप्शन बनाना

अपने Dodo Payments dashboard में subscription products बनाएं, फिर उन्हें checkout या अपने API के माध्यम से बेचें। Products को active subscriptions से अलग रखने पर आप pricing के versions बना सकते हैं, add-ons जोड़ सकते हैं और performance को स्वतंत्र रूप से track कर सकते हैं।

Subscription product creation

अपने subscription की बिक्री, renewal और billing निर्धारित करने के लिए dashboard में fields configure करें। नीचे दिए गए sections creation form में दिखाई देने वाली चीज़ों से सीधे संबंधित हैं।

Product details

Product Name (required): Checkout, customer portal और invoices में दिखाई देने वाला display name।
Product Description (required): Checkout और invoices में दिखाई देने वाला स्पष्ट value statement।
Product Image (required): 3 MB तक PNG/JPG/WebP। Checkout और invoices पर उपयोग किया जाता है।
Brand: Theming और emails के लिए product को किसी specific brand से associate करें।
Tax Category (required): Tax rules निर्धारित करने के लिए category (उदाहरण के लिए, SaaS) चुनें।

प्रत्येक region में सही tax collection सुनिश्चित करने के लिए सबसे सटीक tax category चुनें।

Pricing

Pricing Type: Subscription चुनें (यह गाइड)। विकल्प हैं Single Payment और Usage Based Billing।
Price (required): मुद्रा सहित आधार recurring price। कीमत कम से कम $1 (या आपकी चुनी हुई मुद्रा में उसके बराबर) होनी चाहिए। इससे कम राशि समर्थित नहीं है और subscription काम नहीं करेगा।
Discount Applicable (%): आधार कीमत पर लागू होने वाली वैकल्पिक प्रतिशत छूट; checkout और invoices में दिखाई देती है।
Repeat payment every (required): renewals का interval, जैसे हर 1 Month। cadence (months या years) और quantity चुनें।
Subscription Period (required): वह कुल अवधि जिसके दौरान subscription active रहता है (जैसे 10 Years)। यह अवधि समाप्त होने के बाद, बढ़ाए जाने तक renewals रुक जाते हैं।
Trial Period Days (required): trial की अवधि दिनों में सेट करें। trials बंद करने के लिए 0 का उपयोग करें। trial समाप्त होने पर पहला charge अपने-आप होता है।
Trial Amount: paid trial के लिए वैकल्पिक upfront charge। free trial के लिए इसे unset छोड़ें। Paid Trials देखें।
Select add‑on: अधिकतम 10 add‑ons जोड़ें, जिन्हें ग्राहक base plan के साथ खरीद सकते हैं।

Active product की pricing बदलने से नई purchases प्रभावित होती हैं। Existing subscriptions आपकी plan-change और proration settings का पालन करती हैं।

Add-ons seats या storage जैसे quantifiable extras के लिए आदर्श हैं। Customers द्वारा इन्हें बदलने पर आप allowed quantities और proration behavior नियंत्रित कर सकते हैं।

Advanced settings

Tax Inclusive Pricing: लागू taxes सहित prices display करें। Final tax calculation customer location के अनुसार अलग हो सकता है।
Generate license keys: Purchase के बाद प्रत्येक customer को एक unique key जारी करें। License Keys guide देखें।
Digital Product Delivery: Purchase के बाद files या content automatically deliver करें। Digital Product Delivery में अधिक जानें।
Metadata: Internal tagging या client integrations के लिए custom key–value pairs जोड़ें। Metadata देखें।

अपने system के identifiers (जैसे, accountId) store करने के लिए metadata का उपयोग करें, ताकि बाद में events और invoices का reconciliation कर सकें।

Subscription Trials

Trials ग्राहकों को पूरी recurring price चुकाने से पहले subscription का मूल्यांकन करने देते हैं। trial free हो सकता है, जिसमें trial समाप्त होने तक कुछ charge नहीं किया जाता, या paid हो सकता है, जिसमें शुरुआत में कम राशि charge की जाती है। दोनों मामलों में trial समाप्त होने के बाद पहले renewal से full price लागू होती है।

Trials configure करना

Product pricing section में Trial Period Days set करें (disable करने के लिए 0 का उपयोग करें)। Subscriptions बनाते समय इसे override किया जा सकता है:

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_monthly',
  quantity: 1,
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});

trial_period_days value 0 से 10,000 दिनों के बीच होना चाहिए।

Paid Trials

Trials का free होना आवश्यक नहीं है। paid trial window के लिए कम upfront fee charge करने हेतु subscription product की recurring price पर Trial Amount सेट करें। इसके बाद पहले renewal पर full recurring price लागू हो जाती है।

Subscription pricing form with a trial duration and an optional trial amount for a paid trial

Paid trials product की price पर configure किए जाते हैं, subscription या checkout session के आधार पर नहीं:

Field	Type	Description
`trial_amount`	integer	trial के लिए आज charge की जाने वाली राशि, price currency की minor units में (उदाहरण के लिए, $5.00 के लिए `500`)। इसके लिए `trial_period_days > 0` आवश्यक है। free trial के लिए इसे omit करें या `null` पर सेट करें।
`trial_apply_discounts`	boolean	क्या checkout discount codes trial charge को कम करें। डिफ़ॉल्ट रूप से `false`, इसलिए recurring price पर discount लागू होने पर भी trial amount पूरी charge होती है।

const product = await client.products.create({
  name: 'Pro Plan',
  tax_category: 'saas',
  price: {
    type: 'recurring_price',
    price: 2900,                      // $29.00 per month after the trial
    currency: 'USD',
    discount: 0,
    purchasing_power_parity: false,
    payment_frequency_count: 1,
    payment_frequency_interval: 'Month',
    subscription_period_count: 1,
    subscription_period_interval: 'Year',
    trial_period_days: 14,            // A paid trial requires a positive trial period
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false      // Discounts apply to the recurring price only
  }
});

Paid trials checkout से भी गुजरते हैं। trial amount पर tax लगाया जाता है, checkout session calculations और payment link pricing में दिखाया जाता है, और प्रत्येक currency के अनुसार Adaptive Currency markup लागू होता है। preview endpoint trial_amount और trial_period_days लौटाता है, ताकि subscription बनने से पहले आप आज देय राशि दिखा सकें।

Free trials में कोई बदलाव नहीं है। Trial Amount को unset छोड़ने पर मौजूदा व्यवहार बना रहता है: पहला charge 0 होता है और trial समाप्त होने पर full price charge की जाती है।

Trial Misuse रोकना

Prevent Trial Misuse ग्राहकों को एक ही business के लिए बार-बार trials claim करने से रोकता है। सक्षम होने पर, जिस ग्राहक ने पहले trial redeem किया है, उसे नया trial देने के बजाय अपने-आप paid, no-trial purchase में बदल दिया जाता है।

Prevent Trial Misuse toggle in the Subscriptions settings tab

इसे Settings के Subscriptions tab से सक्षम करें। सक्षम होने के बाद:

ग्राहकों का मिलान normalized email से किया जाता है और plus-aliases हटा दिए जाते हैं, इसलिए user+trial@example.com और user@example.com को एक ही व्यक्ति माना जाता है।
Redemptions को trial activation पर दर्ज किया जाता है, इसलिए उसी दिन cancel करने वाला ग्राहक भी अपना trial इस्तेमाल कर चुका माना जाता है।
Existing customers को email के आधार पर उनके historical trials से backfill किया जाता है, इसलिए पुराने trial users तुरंत पहचान लिए जाते हैं।

यह setting डिफ़ॉल्ट रूप से off है। business-level subscription controls की पूरी सूची के लिए Subscription Settings देखें।

Trial Status पहचानना

वर्तमान में trial status पहचानने के लिए कोई direct field नहीं है। निम्न workaround के लिए payments query करना पड़ता है, जो inefficient है। हम अधिक efficient solution पर काम कर रहे हैं।

यह निर्धारित करने के लिए कि कोई free trial subscription trial में है या नहीं, subscription के payments की सूची प्राप्त करें। यदि amount 0 वाला ठीक एक payment है, तो subscription trial period में है:

const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

यह zero-amount check केवल free trials के लिए काम करता है। paid trial में पहला payment 0 नहीं, बल्कि trial amount के बराबर होता है। इसके बजाय पहले payment की तुलना subscription के trial_amount से करें, या जाँचें कि next_billing_date अभी भी trial window के भीतर है या नहीं।

Trial Period अपडेट करना

next_billing_date अपडेट करके trial बढ़ाएँ:

await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});

आप next_billing_date को past time पर सेट नहीं कर सकते। date future में होनी चाहिए।

Subscription Plan Changes

Plan changes से आप subscriptions को upgrade या downgrade कर सकते हैं, quantities समायोजित कर सकते हैं या अलग products पर migrate कर सकते हैं। आपके द्वारा चुने गए proration mode के आधार पर, बदलाव से तत्काल charge हो सकता है, credit बन सकता है या कोई billing adjustment लागू नहीं हो सकता।

आप Dodo Payments dashboard से सीधे subscription plans बदल सकते हैं और अगली billing date अपडेट कर सकते हैं। इससे customer support requests, promotional upgrades या plan migrations के लिए API calls किए बिना subscriptions समायोजित करने का तेज़ तरीका मिलता है।

self-service plan changes सक्षम करें: क्या आप चाहते हैं कि ग्राहक Customer Portal के माध्यम से अपनी subscriptions upgrade या downgrade कर सकें? अपने subscription products को Product Collection में जोड़ें और Subscription Settings में “Allow Subscription Updates” सक्षम करें।

Product Collections

Customer Portal में seamless upgrade/downgrade paths सक्षम करने के लिए संबंधित products को collections में समूहित करें।

Proration Modes

Plans बदलते समय ग्राहकों से billing कैसे की जाए, चुनें:

चार proration modes की त्वरित तुलना:

	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Upgrade	शेष दिनों के लिए prorated charge	पूरी price difference charge	नए plan की पूरी price charge	कोई charge नहीं — तुरंत switch
Downgrade	शेष दिनों के लिए prorated credit	पूरी price difference credit के रूप में	कोई credit नहीं, पूरी charge	कोई credit नहीं — तुरंत switch
Billing cycle	आज पर reset	आज पर reset	आज पर reset	वही रहता है
Best for	समय-आधारित fair billing	सरल tier changes	Billing cycle resets	Free migrations या courtesy switches

`prorated_immediately`

वर्तमान billing cycle में बचे समय के आधार पर prorated amount charge करता है। unused time को ध्यान में रखने वाली fair billing के लिए सबसे उपयुक्त।

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

`difference_immediately`

price difference को तुरंत charge करता है (upgrade) या future renewals के लिए credit जोड़ता है (downgrade)। सरल upgrade/downgrade scenarios के लिए सबसे उपयुक्त।

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

difference_immediately का उपयोग करके downgrades से मिलने वाले credits subscription-scoped होते हैं और future renewals पर अपने-आप लागू होते हैं। ये Credit-Based Billing entitlements से अलग हैं।

जब कोई ग्राहक difference_immediately के साथ downgrade करता है, तो unused value subscription-scoped credit बन जाती है, जो future renewals को अपने-आप offset करती है:

`full_immediately`

शेष समय की परवाह किए बिना नए plan की पूरी राशि तुरंत charge करता है। Billing cycles reset करने के लिए सबसे उपयुक्त।

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_monthly',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
});

`do_not_bill`

बिना किसी billing adjustment के नए plan पर switch करता है। कोई proration charges या credits नहीं — ग्राहक केवल नए plan पर चला जाता है। courtesy migrations, free plan switches या ऐसे scenarios के लिए सबसे उपयुक्त जहाँ आप cost difference वहन करना चाहते हैं।

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new_plan',
  quantity: 1,
  proration_billing_mode: 'do_not_bill'
});

Example: Prorated upgrade calculation

Scenario: Basic (

30/month) पर मौजूद ग्राहक `prorated_immediately` का उपयोग करके 30-day cycle के day 16 पर Pro (

80/month) में upgrade करता है।

Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
────────────────────────────────────────────────────────────────────
Immediate charge         = $40.00 − $15.00 = $25.00

अगला renewal February 15 (January 16 + 30 days) को: $80.00/month।

अधिक विस्तृत calculation examples और edge cases के लिए हमारी पूरी Upgrade & Downgrade Guide देखें।

Example: Downgrade credit calculation

Scenario: Pro (

80/month) पर मौजूद ग्राहक `difference_immediately` का उपयोग करके Starter (

20/month) में downgrade करता है।

Credit = Old plan − New plan = $80 − $20 = $60.00

$60 credit future renewals पर अपने-आप लागू होता है:

Renewal 1: $20 −$ 20 (credit) = ** $0.00** ($ 40 credit शेष)
Renewal 2: $20 −$ 20 (credit) = ** $0.00** ($ 20 credit शेष)
Renewal 3: $20 −$ 20 (credit) = $0.00 (credit समाप्त)
Renewal 4: $20.00 (पूरी price)

Credits कैसे manage किए जाते हैं, इसके बारे में अधिक जानकारी Upgrade & Downgrade Guide में प्राप्त करें।

Add-ons के साथ Plans बदलना

Plans बदलते समय add-ons संशोधित करें। Add-ons proration calculations में शामिल होते हैं:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});

डिफ़ॉल्ट रूप से, effective_at: 'immediately' प्लान में बदलाव होने पर तुरंत शुल्क लगते हैं। बदलाव को अगली billing date के लिए शेड्यूल करने हेतु effective_at: 'next_billing_date' पास करें — लंबित बदलाव subscription पर scheduled_change के रूप में लौटाया जाता है, और आप इसे शेड्यूल किए गए प्लान बदलाव को रद्द करें के माध्यम से रद्द कर सकते हैं। असफल शुल्क subscription को on_hold status में ले जा सकते हैं, जब तक कि आप on_payment_failure: 'prevent_change' पास न करें। ऐसा करने पर payment सफल होने तक subscription अपने वर्तमान प्लान पर बना रहता है। subscription.plan_changed webhook events के माध्यम से बदलावों को ट्रैक करें।

Plan Changes का Preview देखना

Plan change लागू करने से पहले exact charge और resulting subscription का preview देखें:

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);

Preview Change Plan API

Plan changes लागू करने से पहले उनका preview देखें।

सब्सक्रिप्शन को रोकना और फिर से शुरू करना

रोकने से सब्सक्रिप्शन समाप्त होने के बजाय स्थिर हो जाता है। बिलिंग रुक जाती है, एक्सेस रद्द हो जाता है, और सब्सक्रिप्शन अपना प्लान और इतिहास बनाए रखता है, ताकि ग्राहक ठीक वहीं से फिर शुरू कर सके जहाँ उसने छोड़ा था। इसे cancellation के विकल्प के रूप में retention के लिए इस्तेमाल करें। Sales → Subscriptions के अंतर्गत कोई भी active subscription खोलें और Pause subscription पर क्लिक करें। स्थिति paused में बदल जाती है और subscription resume होने तक renewals रुक जाती हैं।

Pause करने पर क्या होता है

Renewals रुक जाती हैं। Subscription paused होने पर कोई invoice generate नहीं होता और renewal charge का प्रयास नहीं किया जाता।
Access तुरंत रद्द हो जाता है। Pausing से subscription पर दिए गए और pending सभी entitlement grants रद्द हो जाते हैं, जिससे उसकी license keys निष्क्रिय हो जाती हैं और नए digital product download URLs जारी होना रुक जाता है। Resume करने पर इन्हें फिर से grant किया जाता है, ठीक उसी तरह जैसे on_hold से recovery करने पर होता है।
Billing clock रुक जाती है। next_billing_date और expires_at दोनों pause की सटीक अवधि के अनुसार आगे बढ़ते हैं, इसलिए ग्राहक को पहले से भुगतान किया गया समय मिलता रहता है।
Pause duration की कोई सीमा नहीं है। Paused subscription तब तक paused रहता है जब तक कोई उसे resume न कर दे। Pause की अवधि पहले से सेट नहीं की जाती।

Pausing से access billing period के अंत में नहीं, बल्कि तुरंत रद्द हो जाता है। यदि subscription आपके product तक access नियंत्रित करता है, तो customer के confirm करने से पहले यह बात स्पष्ट कर दें।

Resume करने पर subscription active में लौटता है और उसके entitlements restore हो जाते हैं। Clock freeze होने के कारण अगला renewal मूल schedule से pause की अवधि जितना देर से होता है — 12 दिनों के लिए paused subscription 12 दिन देर से renew होता है।

Usage-Based Subscriptions को रोकना

Usage-based subscription में pause किए जाने के समय ऐसा usage हो सकता है जो recorded है, लेकिन अभी billed नहीं हुआ है। Settings → Subscriptions के अंतर्गत Bill Usage at Pause तय करता है कि इसका क्या होगा:

Setting	Behavior
On (default)	Dodo Payments पिछली billing date के बाद जमा हुए usage के लिए invoice बनाता है और उसे तुरंत collect करता है।
Off	बकाया usage आगे ले जाया जाता है और subscription के अगले नियमित invoice में billed किया जाता है।

इस तरह केवल metered usage settle होता है — recurring base fee pause के समय कभी charge नहीं की जाती। Standard और on-demand subscriptions में settle करने के लिए कुछ नहीं होता, इसलिए यह setting उन्हें प्रभावित नहीं करती।

Bill Usage at Pause प्रत्येक billing cycle के लिए record किया जाता है। Cycle के बीच में इसे बदलने से पहले से चल रहे cycle के settlement पर कोई प्रभाव नहीं पड़ता; नया value अगले cycle से लागू होता है।

Settlement invoice को किसी भी अन्य invoice की तरह collect किया जाता है, इसलिए यह fail हो सकता है। यदि dunning grace period के बाद भी इसका भुगतान नहीं होता, तो subscription on_hold में चला जाता है और paused के रूप में flagged रहता है।

उस स्थिति में subscription से बाहर निकलने के दो तरीके हैं, और दोनों में बकाया usage को कौन वहन करता है, यह अलग होता है:

Exit	Result
Settlement invoice का भुगतान किया जाता है	Subscription `paused` में लौटता है, `active` में नहीं। Customer तैयार होने पर इसे स्पष्ट रूप से resume करें।
आप इसे सीधे resume करते हैं	Subscription सीधे `active` में चला जाता है और unpaid settlement invoice को उसके pending retries सहित voided कर दिया जाता है। बकाया usage को write off कर दिया जाता है।

इस hold से बाहर निकलने के लिए resume करना मान्य तरीका है — पहले settlement invoice collect करना आवश्यक नहीं है। ध्यान रखें कि resume करने पर outstanding usage को defer करने के बजाय माफ कर दिया जाता है।

Customers को अपना Subscription खुद Pause करने देना

Settings → Subscriptions के अंतर्गत Allow Subscription Pause यह नियंत्रित करता है कि customers Customer Portal से pause और resume कर सकते हैं या नहीं। यह off by default है, इसलिए self-service pause opt-in है।

यह setting केवल Customer Portal पर लागू होती है। Toggle की स्थिति चाहे जो हो, आप dashboard या API से हमेशा pause और resume कर सकते हैं। इसे off करने से नए customer pauses रुक जाते हैं, लेकिन जो customer पहले से paused है, वह फँसता नहीं है — वह अपने द्वारा शुरू किए गए pause को resume कर सकता है। आपके द्वारा शुरू किए गए pauses आपके नियंत्रण में रहते हैं।

Pausing from the Customer Portal

देखें कि customer को क्या दिखाई देता है, जिसमें confirmation dialog भी शामिल है।

API के माध्यम से Pause करना

Pause और resume, update subscription endpoint पर एक ही pause field से किए जाते हैं। कोई अलग pause endpoint नहीं है।

// Pause
await client.subscriptions.update('sub_123', { pause: true });

// Resume
await client.subscriptions.update('sub_123', { pause: false });

pause हर दूसरे field के साथ exclusive है — इसे किसी अन्य field के साथ भेजने पर request 422 के साथ reject हो जाती है। status को paused पर set करने से subscription pause नहीं होता; इसके बजाय pause field का उपयोग करें।

Pausing से subscription.paused और resuming से subscription.unpaused emit होता है। दोनों में पूरा subscription object होता है, जिसमें paused रहते समय paused_at set होता है और resume होने के बाद null set होता है।

Pause और अन्य Subscription Actions

Cancellation फिर भी काम करता है। Paused subscription को उसी तरह cancel किया जा सकता है जैसे active subscription को। Pause से बना कोई भी open settlement invoice cancel करने पर voided कर दिया जाता है।
Scheduled plan changes delay होते हैं, हटाए नहीं जाते। अगली billing date के लिए scheduled plan change subscription paused रहने तक अपरिवर्तित रहता है, फिर resume होने पर shifted billing date पर लागू होता है। इसका scheduled_change.effective_at scheduling के समय का snapshot होता है और pause के अनुसार adjust नहीं किया जाता, इसलिए इसमें पिछली date दिखाई दे सकती है — इसे guaranteed date के बजाय “was scheduled for” समझें। Change को लागू होने देने के बजाय हटाने के लिए Cancel Scheduled Plan Change का उपयोग करें।

Subscription States

Subscription अपने lifetime में statuses के एक निर्धारित set से गुजरता है। यह table प्रत्येक status, उसके कारण और उससे recovery के तरीके (या recovery संभव है या नहीं) का reference है।

Status	What it means	Recoverable?	Recovery path / next step
`pending`	Subscription बनाया या process किया जा रहा है	—	`subscription.active` (या `subscription.failed`) की प्रतीक्षा करें
`active`	Subscription active है और अपने-आप renew होगा	—	किसी action की आवश्यकता नहीं
`on_hold`	Renewal payment (या plan-change charge) fail हो गया; renewals रुक गई हैं	Yes	Payment method update करके reactivate करें — Payment Retries और Dunning के माध्यम से automatically, या Update Payment Method API के माध्यम से manually
`paused`	Subscription को आपने या customer ने जानबूझकर pause किया; billing freeze है और access revoke है	Yes	`pause: false` से या self-service pause enabled होने पर Customer Portal से resume करें — Pausing and Resuming Subscriptions देखें
`cancelled`	Subscription cancel किया गया है और renew नहीं होगा	केवल re-purchase	Customer को नया subscription शुरू करना होगा; Dunning re-purchase के लिए prompt कर सकता है
`failed`	Subscription creation fail हुआ (initial mandate या payment सफल नहीं हुआ)	No — terminal	Customer को working payment method के साथ नया subscription बनाना होगा
`expired`	Subscription अपनी अवधि के अंत तक पहुँच गया	—	आवश्यकता होने पर customer को नया subscription शुरू करना होगा

on_hold और failed को अक्सर भ्रमित किया जाता है। on_hold पहले से active subscription के renewal fail होने पर आने वाली recoverable state है। failed terminal state है, जो केवल initial subscription creation fail होने पर आती है — इसे reactivate नहीं किया जा सकता।

on_hold और paused भी अलग हैं। on_hold अनैच्छिक है — payment fail हुआ। paused जानबूझकर किया गया है — आपने या customer ने subscription freeze करने का विकल्प चुना, और paused रहने तक renewal का प्रयास नहीं किया जाता। Usage-based subscription पर pause के समय one-off settlement invoice बकाया हो सकता है; Pausing Usage-Based Subscriptions देखें।

State Machine

On Hold State

Subscription on_hold state में तब जाता है जब:

Renewal payment fail हो (insufficient funds, expired card आदि)
Plan change charge fail हो
Payment method authorization fail हो
Usage-based subscription का pause settlement invoice unpaid रह जाए

जब subscription on_hold state में होता है, तो वह अपने-आप renew नहीं होगा। Subscription को reactivate करने के लिए आपको payment method update करना होगा।

On Hold से Reactivate करना

Subscription को on_hold state से reactivate करने के लिए payment method update करें। यह automatically:

शेष dues के लिए charge बनाता है
Invoice generate करता है
नए payment method का उपयोग करके payment process करता है
Payment सफल होने पर subscription को active state में reactivate करता है

एक अपवाद unpaid pause settlement invoice के कारण लगा hold है। उस invoice को clear करने पर subscription paused में लौटता है, active में नहीं, क्योंकि payment fail होने से पहले वह pause state में था। Invoice settle होने के बाद इसे स्पष्ट रूप से resume करें।

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

on_hold subscription के लिए payment method सफलतापूर्वक update करने के बाद आपको payment.succeeded और उसके बाद subscription.active webhook events मिलेंगे।

Transition के अनुसार Webhook Events

हर transition एक webhook emit करता है, ताकि आप polling के बिना entitlement logic चला सकें:

Transition	Event
Subscription activated	`subscription.active`
Renewal succeeds	`subscription.renewed`
Renewal fails → on hold	`subscription.on_hold`
Subscription paused	`subscription.paused`
Paused subscription resumed	`subscription.unpaused`
Creation fails	`subscription.failed`
Plan upgraded/downgraded	`subscription.plan_changed`
Cancelled	`subscription.cancelled`
Term ended	`subscription.expired`
Any field changes	`subscription.updated`

Subscription Webhook Payloads

Subscription lifecycle events के लिए पूरा payload schema देखें।

API Management

Create subscriptions

Products से programmatically subscriptions बनाने के लिए POST /checkouts का उपयोग करें; इसमें optional trials (subscription_data.trial_period_days) और add-ons (product_cart[].addons) शामिल किए जा सकते हैं।

POST /subscriptions deprecated है। Existing integrations काम करते रहेंगे, लेकिन नए integrations को Checkout Sessions का उपयोग करना चाहिए।

API Reference

Create checkout session API देखें।

Update subscriptions

अगली billing date पर cancel करने, subscription period बढ़ाने, billing details update करने या metadata बदलने के लिए PATCH /subscriptions/{subscription_id} का उपयोग करें। Quantity बदलने के लिए Change Plan API का उपयोग करें — PATCH, quantity स्वीकार नहीं करता।

API Reference

Subscription details update करने का तरीका जानें।

Pause and resume subscriptions

Pause और resume, pause field का उपयोग करके उसी PATCH /subscriptions/{subscription_id} endpoint से किए जाते हैं: pause: true active subscription को pause करता है और pause: false उसे resume करता है। एक ही request में field को किसी अन्य field के साथ combine नहीं किया जा सकता। पूरे behavior, billing effects और संबंधित business settings के लिए Pausing and Resuming Subscriptions देखें।

API Reference

pause field सहित update subscription API देखें।

Change plans (proration)

Proration controls के साथ active product और quantities बदलें।

API Reference

Plan change options की समीक्षा करें।

On‑demand charges

On-demand subscriptions के लिए, आवश्यकता के अनुसार specific amounts charge करें।

API Reference

On-demand subscription charge करें।

List and retrieve

सभी subscriptions list करने के लिए GET /subscriptions और किसी एक को retrieve करने के लिए GET /subscriptions/{id} का उपयोग करें।

API Reference

Listing और retrieval APIs ब्राउज़ करें।

Usage history

Metered या hybrid pricing models के लिए recorded usage प्राप्त करें।

API Reference

Usage history API देखें।

Update payment method

Subscription का payment method update करें। Active subscriptions के लिए यह future renewals का payment method update करता है। on_hold state वाली subscriptions के लिए, यह remaining dues का charge बनाकर subscription को reactivate करता है।नया payment-method link बनाते समय (New request type), आप allowed_payment_method_types पास कर सकते हैं, ताकि customer उस page पर देखे जाने वाले payment methods सीमित कर सके। Customers को list में मौजूद न होने वाला method कभी दिखाई नहीं देगा, हालांकि किसी method को शामिल करने से उसके दिखाई देने की guarantee नहीं होती (availability customer location और आपकी business settings जैसे factors पर निर्भर करती है)।

API Reference

Payment methods update करने और subscriptions reactivate करने का तरीका जानें।

सामान्य Use Cases

SaaS और APIs: Seats या usage के लिए add-ons के साथ tiered access
Content और media: Introductory trials के साथ monthly access
B2B support plans: Premium support add-ons के साथ annual contracts
Tools और plugins: License keys और versioned releases

Integration Examples

Checkout Sessions (subscriptions)

Checkout sessions बनाते समय अपना subscription product और optional add-ons शामिल करें:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_subscription',
      quantity: 1
    }
  ]
});

Proration के साथ Plan changes

Subscription को upgrade या downgrade करें और proration behavior नियंत्रित करें:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

अगली billing date पर Cancel करना

वर्तमान billing period के अंत में प्रभावी होने वाला cancellation schedule करें:

await client.subscriptions.update('sub_123', {
  cancel_at_next_billing_date: true
});

Subscription period बढ़ाना

subscription_period_count और subscription_period_interval को PATCH /subscriptions/{subscription_id} में पास करके subscription की अवधि बढ़ाएँ। Subscription की expiry नए count और interval से फिर calculate की जाती है — उदाहरण के लिए, customer को उसके current plan पर अतिरिक्त समय देने के लिए:

await client.subscriptions.update('sub_123', {
  subscription_period_count: 5,
  subscription_period_interval: 'Month'
});

Subscription की अवधि केवल बढ़ाई जा सकती है, कभी घटाई नहीं जा सकती।

On-demand subscriptions

On-demand subscription बनाएँ और आवश्यकता के अनुसार बाद में charge करें:

const onDemand = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_on_demand',
  quantity: 1,
  on_demand: { mandate_only: true }
});

await client.subscriptions.charge(onDemand.subscription_id, {
  product_price: 4900,
  product_currency: 'USD',
  product_description: 'Extra usage for September'
});

Active subscription का Payment method update करना

Active subscription का payment method update करें:

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'existing',
    payment_method_id: 'pm_abc123'
  }
});

on_hold से Subscription reactivate करना

Failed payment के कारण on hold हुई subscription को reactivate करें:

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

RBI-Compliant Mandates वाली Subscriptions

UPI और Indian card subscriptions, mandate की specific requirements के साथ RBI (Reserve Bank of India) regulations के अंतर्गत operate करती हैं:

Mandate Limits

Mandate type और amount आपकी subscription के recurring charge पर निर्भर करते हैं:

Mandate floor (default ₹15,000) से कम charges: हम floor amount के लिए on-demand mandate बनाते हैं। Subscription amount आपकी subscription frequency के अनुसार periodic रूप से charge किया जाता है, mandate limit तक।
Mandate floor के बराबर या उससे अधिक charges: हम exact subscription amount के लिए subscription mandate (या on-demand mandate) बनाते हैं।

Mandate floor को merchant के अनुसार या request के अनुसार mandate_min_amount_inr_paise (INR paise) के माध्यम से configure किया जा सकता है। Bank के साथ registered amount max(mandate_floor, billing_amount) होता है — इसलिए जब billing कम हो, तो floor customer-facing authorization ceiling बन जाता है। RBI-compliant mandates और Indian payment methods के लिए configurable mandate floor की विस्तृत जानकारी के लिए India Payment Methods page देखें।

Upgrade और Downgrade संबंधी विचार

Important: Subscriptions upgrade या downgrade करते समय mandate limits पर सावधानी से विचार करें:

यदि upgrade/downgrade के परिणामस्वरूप charge amount Rs 15,000 से अधिक हो जाता है और existing on-demand payment limit से भी आगे निकल जाता है, तो transaction charge fail हो सकता है।
ऐसे मामलों में customer को अपना payment method update करना या subscription को फिर से बदलना पड़ सकता है, ताकि सही limit वाला नया mandate बनाया जा सके।

High-Value Charges के लिए Authorization

Rs 15,000 या उससे अधिक के subscription charges के लिए:

Bank customer को transaction authorize करने के लिए prompt करेगा।
यदि customer transaction authorize नहीं करता है, तो transaction fail हो जाएगा और subscription को on hold कर दिया जाएगा।

48-Hour Processing Delay

Processing Timeline: Indian cards और UPI subscriptions पर recurring charges एक विशिष्ट processing pattern का पालन करते हैं:

Charges आपकी subscription frequency के अनुसार scheduled date पर initiated किए जाते हैं।
Customer के account से वास्तविक deduction, payment initiation के 48 hours बाद ही होता है।
Bank API responses के आधार पर यह 48-hour window 2-3 additional hours तक बढ़ सकती है।

Mandate Cancellation Window

48-hour processing window के दौरान:

Customers अपने banking apps के माध्यम से mandate cancel कर सकते हैं।
यदि customer इस अवधि में mandate cancel करता है, तो subscription active रहता है (यह Indian card और UPI AutoPay subscriptions से संबंधित edge case है)।
हालांकि वास्तविक deduction fail हो सकता है, और ऐसी स्थिति में subscription को on hold कर दिया जाएगा।

Edge Case Handling: यदि आप charge initiation के तुरंत बाद customers को benefits, credits या subscription usage देते हैं, तो आपको अपने application में इस 48-hour window को उचित रूप से handle करना होगा। इन विकल्पों पर विचार करें:

Payment confirmation तक benefit activation में देरी करना
Grace periods या temporary access लागू करना
Mandate cancellations के लिए subscription status monitor करना
अपने application logic में subscription hold states को handle करना

Payment status changes track करने और 48-hour window के दौरान mandates cancel होने वाले edge cases handle करने के लिए subscription webhooks monitor करें।

Best Practices

Clear tiers से शुरुआत करें: स्पष्ट अंतर वाले 2–3 plans
Pricing communicate करें: Totals, proration और next renewal दिखाएँ
Trials का सोच-समझकर उपयोग करें: केवल समय नहीं, onboarding के माध्यम से convert करें
Add-ons का लाभ उठाएँ: Base plans सरल रखें और अतिरिक्त सुविधाओं को upsell करें
Changes test करें: Test mode में plan changes और proration validate करें

Subscriptions recurring revenue के लिए एक flexible foundation हैं। सरल शुरुआत करें, अच्छी तरह test करें, और adoption, churn तथा expansion metrics के आधार पर सुधार करते रहें।

अंतिम संशोधन 21 अगस्त 2026

Upgrade & Downgrade

On‑Demand Subscriptions

Customer Portal

Subscription Webhooks

​सब्सक्रिप्शन क्या हैं?

​मुख्य लाभ

​सब्सक्रिप्शन बनाना

​Subscription product creation

​Product details

​Pricing

​Advanced settings

​Subscription Trials

​Trials configure करना

​Paid Trials

​Trial Misuse रोकना

​Trial Status पहचानना

​Trial Period अपडेट करना

​Subscription Plan Changes

Product Collections

​Proration Modes

​prorated_immediately

​difference_immediately

​full_immediately

​do_not_bill

​Add-ons के साथ Plans बदलना

​Plan Changes का Preview देखना

Preview Change Plan API

​सब्सक्रिप्शन को रोकना और फिर से शुरू करना

​Pause करने पर क्या होता है

​Usage-Based Subscriptions को रोकना

​Customers को अपना Subscription खुद Pause करने देना

Pausing from the Customer Portal

​API के माध्यम से Pause करना

​Pause और अन्य Subscription Actions

​Subscription States

​State Machine

​On Hold State

​On Hold से Reactivate करना

​Transition के अनुसार Webhook Events

Subscription Webhook Payloads

​API Management

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​सामान्य Use Cases

​Integration Examples

​Checkout Sessions (subscriptions)

​Proration के साथ Plan changes

​अगली billing date पर Cancel करना

​Subscription period बढ़ाना

​On-demand subscriptions

​Active subscription का Payment method update करना

​on_hold से Subscription reactivate करना

​RBI-Compliant Mandates वाली Subscriptions

​Mandate Limits

​Upgrade और Downgrade संबंधी विचार

​High-Value Charges के लिए Authorization

​48-Hour Processing Delay

​Mandate Cancellation Window

​Best Practices

सब्सक्रिप्शन क्या हैं?

मुख्य लाभ

सब्सक्रिप्शन बनाना

Subscription product creation

Product details

Pricing

Advanced settings

Subscription Trials

Trials configure करना

Paid Trials

Trial Misuse रोकना

Trial Status पहचानना

Trial Period अपडेट करना

Subscription Plan Changes

Proration Modes

`prorated_immediately`

`difference_immediately`

`full_immediately`

`do_not_bill`

Add-ons के साथ Plans बदलना

Plan Changes का Preview देखना

सब्सक्रिप्शन को रोकना और फिर से शुरू करना

Pause करने पर क्या होता है

Usage-Based Subscriptions को रोकना

Customers को अपना Subscription खुद Pause करने देना

API के माध्यम से Pause करना

Pause और अन्य Subscription Actions

Subscription States

State Machine

On Hold State

On Hold से Reactivate करना

Transition के अनुसार Webhook Events

API Management

सामान्य Use Cases

Integration Examples

Checkout Sessions (subscriptions)

Proration के साथ Plan changes

अगली billing date पर Cancel करना

Subscription period बढ़ाना

On-demand subscriptions

Active subscription का Payment method update करना

on_hold से Subscription reactivate करना

RBI-Compliant Mandates वाली Subscriptions

Mandate Limits

Upgrade और Downgrade संबंधी विचार

High-Value Charges के लिए Authorization

48-Hour Processing Delay

Mandate Cancellation Window

Best Practices