Subscriptions let you sell ongoing access with automated renewals. Use flexible billing cycles, free trials, plan changes, and add‑ons to tailor pricing for each customer.
Upgrade & Downgrade
Control plan changes with proration and quantity updates.
On‑Demand Subscriptions
Authorize a mandate now and charge later with custom amounts.
Customer Portal
Let customers manage plans, billing, and cancellations.
Subscription Webhooks
React to lifecycle events like created, renewed, and canceled.
What Are Subscriptions?
Subscriptions are recurring products customers purchase on a schedule. They’re ideal for:- SaaS licenses: Apps, APIs, or platform access
- Memberships: Communities, programs, or clubs
- Digital content: Courses, media, or premium content
- Support plans: SLAs, success packages, or maintenance
Key Benefits
- Predictable revenue: Recurring billing with automated renewals
- Flexible cycles: Monthly, annual, custom intervals, and trials
- Plan agility: Proration for upgrades and downgrades
- Add‑ons and seats: Attach optional, quantifiable upgrades
- Seamless checkout: Hosted checkout and customer portal
- Developer-first: Clear APIs for creation, changes, and usage tracking
Creating Subscriptions
Create subscription products in your Dodo Payments dashboard, then sell them through checkout or your API. Separating products from active subscriptions lets you version pricing, attach add‑ons, and track performance independently.Subscription product creation
Configure the fields in the dashboard to define how your subscription sells, renews, and bills. The sections below map directly to what you see in the creation form.Product details
- Product Name (required): The display name shown in checkout, customer portal, and invoices.
- Product Description (required): A clear value statement that appears in checkout and invoices.
- Product Image (required): PNG/JPG/WebP up to 3 MB. Used on checkout and invoices.
- Brand: Associate the product with a specific brand for theming and emails.
- Tax Category (required): Choose the category (for example, SaaS) to determine tax rules.
Pricing
- Pricing Type: Choose Subscription (this guide). Alternatives are Single Payment and Usage Based Billing.
- Price (required): Base recurring price with currency.
- Discount Applicable (%): Optional percentage discount applied to the base price; reflected in checkout and invoices.
- Repeat payment every (required): Interval for renewals, e.g., every 1 Month. Select the cadence (months or years) and quantity.
- Subscription Period (required): Total term for which the subscription remains active (e.g., 10 Years). After this period ends, renewals stop unless extended.
- Trial Period Days (required): Set trial length in days. Use 0 to disable trials. The first charge occurs automatically when the trial ends.
- Select add‑on: Attach up to 10 add‑ons that customers can purchase alongside the base plan.
Add‑ons are ideal for quantifiable extras such as seats or storage. You can control allowed quantities and proration behavior when customers change them.
Advanced settings
- Tax Inclusive Pricing: Display prices inclusive of applicable taxes. Final tax calculation still varies by customer location.
- Generate license keys: Issue a unique key to each customer after purchase. See the License Keys guide.
- Digital Product Delivery: Deliver files or content automatically after purchase. Learn more in Digital Product Delivery.
- Metadata: Attach custom key–value pairs for internal tagging or client integrations. See Metadata.
Subscription Trials
Trials let customers access subscriptions without immediate payment. The first charge occurs automatically when the trial ends.Configuring Trials
Set Trial Period Days in the product pricing section (use0 to disable). You can override this when creating subscriptions:
Detecting Trial Status
To determine if a subscription is in trial, retrieve the list of payments for the subscription. If there is exactly one payment with amount 0, the subscription is in trial period:Updating Trial Period
Extend the trial by updatingnext_billing_date:
Subscription Plan Changes
Plan changes let you upgrade or downgrade subscriptions, adjust quantities, or migrate to different products. Depending on the proration mode you select, a change may trigger an immediate charge, create credit, or apply no billing adjustment.Product Collections
Group related products into collections to enable seamless upgrade/downgrade paths in the Customer Portal.
Proration Modes
Choose how customers are billed when changing plans:Quick comparison of the four proration modes:
prorated_immediately | difference_immediately | full_immediately | do_not_bill | |
|---|---|---|---|---|
| Nâng cấp | Phí theo tỷ lệ cho các ngày còn lại | Tính toàn bộ sự chênh lệch giá | Tính toàn bộ giá gói mới | Không tính phí — chuyển ngay lập tức |
| Giảm cấp | Tín dụng theo tỷ lệ cho các ngày còn lại | Toàn bộ số chênh lệch giá thành tín dụng | Không tín dụng, tính toàn bộ phí | Không tín dụng — chuyển ngay lập tức |
| Chu kỳ thanh toán | Đặt lại về hôm nay | Đặt lại về hôm nay | Đặt lại về hôm nay | Giữ nguyên |
| Tốt nhất cho | Thanh toán theo thời gian hợp lý | Thay đổi cấp độ đơn giản | Đặt lại chu kỳ thanh toán | Di chuyển miễn phí hoặc chuyển đổi danh nghĩa |
prorated_immediately
Charges prorated amount based on remaining time in the current billing cycle. Best for fair billing that accounts for unused time.
difference_immediately
Charges the price difference immediately (upgrade) or adds credit for future renewals (downgrade). Best for simple upgrade/downgrade scenarios.
Credits from downgrades using
difference_immediately are subscription-scoped and auto-applied to future renewals. They’re distinct from Credit-Based Billing entitlements.difference_immediately, the unused value becomes a subscription-scoped credit that automatically offsets future renewals:
full_immediately
Charges full new plan amount immediately, ignoring remaining time. Best for resetting billing cycles.
do_not_bill
Switches to the new plan without any billing adjustment. No proration charges, no credits — the customer simply moves to the new plan. Best for courtesy migrations, free plan switches, or scenarios where you want to absorb the cost difference.
Example: Prorated upgrade calculation
Example: Prorated upgrade calculation
Scenario: Customer on Basic (80/month) on day 16 of a 30-day cycle using Gia hạn tiếp theo vào ngày 15 tháng 2 (16 tháng 1 + 30 ngày): 80,00 USD/tháng.
prorated_immediately.Example: Downgrade credit calculation
Example: Downgrade credit calculation
Scenario: Customer on Pro (20/month) using The $60 credit auto-applies to future renewals:
difference_immediately.- Renewal 1: 20 (credit) = **40 credit remaining)
- Renewal 2: 20 (credit) = **20 credit remaining)
- Renewal 3: 20 (credit) = $0.00 (credit exhausted)
- Renewal 4: $20.00 (full price)
Learn more about how credits are managed in the Upgrade & Downgrade Guide.
Changing Plans with Add-ons
Modify add-ons when changing plans. Add-ons are included in proration calculations:Plan changes trigger immediate charges. Failed charges may move the subscription to
on_hold status. Track changes via subscription.plan_changed webhook events.Previewing Plan Changes
Before committing to a plan change, preview the exact charge and resulting subscription:Preview Change Plan API
Preview plan changes before committing to them.
Subscription States
Một đăng ký sẽ trải qua một tập hợp trạng thái xác định trong suốt vòng đời của nó. Bảng này là tài liệu tham khảo cho mọi trạng thái, nguyên nhân xảy ra và cách (hoặc nếu có thể) bạn có thể khôi phục nó.| Trạng thái | Ý nghĩa | Có thể khôi phục? | Đường dẫn khôi phục / bước tiếp theo |
|---|---|---|---|
pending | Đăng ký đang được tạo hoặc xử lý | — | Chờ subscription.active (hoặc subscription.failed) |
active | Đăng ký đang hoạt động và sẽ tự động gia hạn | — | Không cần hành động nào |
on_hold | Thanh toán gia hạn (hoặc phí thay đổi gói) đã thất bại; đăng ký bị tạm dừng | Có | Cập nhật phương thức thanh toán để kích hoạt lại — tự động qua Thử Lại Thanh Toán và Dunning, hoặc thủ công qua API Cập nhật Phương thức Thanh toán |
cancelled | Đăng ký đã bị hủy và sẽ không được gia hạn | Chỉ có thể mua lại | Khách hàng phải bắt đầu đăng ký mới; Dunning có thể nhắc nhở mua lại |
failed | Tạo đăng ký không thành công (ủy nhiệm ban đầu hoặc thanh toán không thành công) | Không — cuối cùng | Khách hàng phải tạo đăng ký mới với phương thức thanh toán hoạt động |
expired | Đăng ký đã hết hạn | — | Khách hàng phải bắt đầu đăng ký mới nếu muốn |
Máy Trạng Thái
Trạng Thái Tạm Dừng
Một đăng ký sẽ vào trạng tháion_hold khi:
- Thanh toán gia hạn thất bại (không đủ tiền, thẻ hết hạn, v.v.)
- Phí thay đổi gói thất bại
- Ủy quyền phương thức thanh toán thất bại
Kích Hoạt Lại từ Trạng Thái Tạm Dừng
Để kích hoạt lại một đăng ký từ trạng tháion_hold, cập nhật phương thức thanh toán. Điều này tự động:
- Tạo một khoản phí cho các khoản nợ còn lại
- Tạo hóa đơn
- Xử lý thanh toán bằng phương thức thanh toán mới
- Kích hoạt lại đăng ký về trạng thái
activekhi thanh toán thành công
Sau khi cập nhật thành công phương thức thanh toán cho một đăng ký
on_hold, bạn sẽ nhận được các sự kiện webhook payment.succeeded tiếp theo là subscription.active.Sự Kiện Webhook theo Chuyển Đổi
Mỗi chuyển đổi phát ra một webhook để bạn có thể thực hiện logic quyền mà không cần khảo sát liên tục:| Chuyển đổi | Sự kiện |
|---|---|
| Đăng ký được kích hoạt | subscription.active |
| Gia hạn thành công | subscription.renewed |
| Gia hạn thất bại → tạm dừng | subscription.on_hold |
| Tạo thất bại | subscription.failed |
| Nâng cấp/giảm cấp gói | subscription.plan_changed |
| Bị hủy | subscription.cancelled |
| Kết thúc thời hạn | subscription.expired |
| Bất kỳ thay đổi trường nào | subscription.updated |
Subscription Webhook Payloads
Xem toàn bộ lược đồ payload cho các sự kiện vòng đời đăng ký.
Quản Lý API
Create subscriptions
Create subscriptions
Sử dụng
POST /subscriptions để tạo đăng ký theo cách lập trình từ các sản phẩm, với các giai đoạn thử nghiệm và bổ sung tùy chọn.API Reference
Xem API tạo đăng ký.
Update subscriptions
Update subscriptions
Sử dụng
PATCH /subscriptions/{id} để cập nhật số lượng, hủy vào ngày lập hóa đơn tiếp theo hoặc sửa đổi metadata.API Reference
Tìm hiểu cách cập nhật chi tiết đăng ký.
Change plans (proration)
Change plans (proration)
Thay đổi sản phẩm và số lượng đang hoạt động với kiểm soát tỷ lệ.
API Reference
Xem xét tùy chọn thay đổi kế hoạch.
On‑demand charges
On‑demand charges
Đối với đăng ký theo yêu cầu, tính phí các khoản cụ thể theo yêu cầu.
API Reference
Tính phí một đăng ký theo yêu cầu.
List and retrieve
List and retrieve
Sử dụng
GET /subscriptions để liệt kê tất cả các đăng ký và GET /subscriptions/{id} để lấy thông tin một đăng ký.API Reference
Duyệt API danh sách và truy xuất.
Usage history
Usage history
Lấy lịch sử sử dụng đã ghi nhận cho các mô hình định giá đo lường hoặc hỗn hợp.
API Reference
Xem API lịch sử sử dụng.
Update payment method
Update payment method
Cập nhật phương thức thanh toán cho một đăng ký. Đối với các đăng ký đang hoạt động, điều này cập nhật phương thức thanh toán cho các lần gia hạn tiếp theo. Đối với các đăng ký trong trạng thái
on_hold, điều này kích hoạt lại đăng ký bằng cách tạo một khoản phí cho các khoản nợ còn lại.Khi tạo một liên kết phương thức thanh toán mới (loại yêu cầu New), bạn có thể truyền allowed_payment_method_types để giới hạn các phương thức thanh toán mà khách hàng nhìn thấy trên trang đó. Khách hàng sẽ không bao giờ thấy một phương pháp không nằm trong danh sách, mặc dù bao gồm một phương pháp không đảm bảo nó xuất hiện (sự sẵn có vẫn phụ thuộc vào các yếu tố như vị trí của khách hàng và cài đặt doanh nghiệp của bạn).API Reference
Tìm hiểu cách cập nhật phương thức thanh toán và kích hoạt lại đăng ký.
Trường Hợp Sử Dụng Phổ Biến
- SaaS và API: Truy cập phân cấp với bổ sung cho chỗ ngồi hoặc sử dụng
- Nội dung và truyền thông: Truy cập hàng tháng với các giai đoạn thử nghiệm giới thiệu
- Kế hoạch hỗ trợ B2B: Hợp đồng hàng năm với bổ sung hỗ trợ cao cấp
- Công cụ và plugin: Khóa giấy phép và phát hành theo phiên bản
Ví Dụ Tích Hợp
Phiên Thanh Toán (đăng ký)
Khi tạo phiên thanh toán, bao gồm sản phẩm đăng ký và bổ sung tùy chọn của bạn:Thay đổi gói với tỷ lệ
Nâng cấp hoặc giảm cấp một đăng ký và kiểm soát hành vi tỷ lệ:Hủy vào ngày lập hóa đơn tiếp theo
Lên lịch hủy bỏ có hiệu lực vào cuối kỳ lập hóa đơn hiện tại:Đăng ký theo Yêu Cầu
Tạo một đăng ký theo yêu cầu và tính phí sau nếu cần:Cập nhật phương thức thanh toán cho đăng ký đang hoạt động
Cập nhật phương thức thanh toán cho một đăng ký đang hoạt động:Kích hoạt lại đăng ký từ on_hold
Kích hoạt lại một đăng ký đã bị tạm dừng do thanh toán thất bại:Đăng ký với Ủy Nhiệm Tuân Thủ RBI
Đăng ký UPI và thẻ Ấn Độ hoạt động theo quy định của RBI (Ngân hàng Dự trữ Ấn Độ) với yêu cầu ủy nhiệm cụ thể:Giới Hạn Ủy Nhiệm
Loại và số lượng ủy nhiệm phụ thuộc vào khoản phí định kỳ của đăng ký của bạn:- Phí dưới mức sàn ủy nhiệm (mặc định ₹15,000): Chúng tôi tạo một ủy nhiệm theo yêu cầu cho số tiền sàn. Số tiền đăng ký được tính định kỳ theo tần suất đăng ký của bạn, lên đến giới hạn ủy nhiệm.
- Phí tại hoặc trên mức sàn ủy nhiệm: Chúng tôi tạo một ủy nhiệm đăng ký (hoặc ủy nhiệm theo yêu cầu) cho chính xác số tiền đăng ký.
mandate_min_amount_inr_paise (INR paise). Số tiền đăng ký với ngân hàng là max(mandate_floor, billing_amount) — do đó, mức sàn thực tế sẽ trở thành giới hạn ủy quyền mà khách hàng thấy khi mô tả khi phí thấp hơn.
Để biết thông tin chi tiết về các ủy nhiệm tuân thủ RBI và mức sàn ủy nhiệm có thể cấu hình cho các phương thức thanh toán tại Ấn Độ, xem trang Phương thức Thanh toán tại Ấn Độ.
Lưu Ý về Nâng cấp và Giảm cấp
Quan trọng: Khi nâng cấp hoặc giảm cấp đăng ký, cần cân nhắc kỹ về giới hạn ủy nhiệm:- Nếu nâng cấp/giảm cấp dẫn đến số tiền phí vượt quá Rs 15,000 và vượt qua giới hạn thanh toán theo yêu cầu hiện tại, phí giao dịch có thể thất bại.
- Trong những trường hợp như vậy, khách hàng có thể cần cập nhật phương thức thanh toán của họ hoặc thay đổi đăng ký một lần nữa để thiết lập một ủy nhiệm mới với giới hạn chính xác.
Ủy quyền cho các khoản phí có giá trị cao
Đối với các khoản phí đăng ký từ Rs 15,000 trở lên:- Khách hàng sẽ được ngân hàng yêu cầu để ủy quyền cho giao dịch.
- Nếu khách hàng không ủy quyền giao dịch, việc giao dịch sẽ thất bại và đăng ký sẽ bị tạm dừng.
48 Giờ Trì Hoãn Xử Lý
Thời gian Xử lý: Các khoản phí định kỳ trên thẻ Ấn Độ và đăng ký UPI tuân theo một mô hình xử lý duy nhất:- Các khoản phí được khởi tạo vào ngày đã lên lịch theo tần suất đăng ký của bạn.
- Thực tế khấu trừ từ tài khoản khách hàng chỉ diễn ra sau 48 giờ từ khi khởi tạo thanh toán.
- Khoảng thời gian 48 giờ này có thể kéo dài thêm lên tới 2-3 giờ tùy thuộc vào các phản hồi của API ngân hàng.
Cửa Sổ Hủy Ủy Nhiệm
Trong khoảng thời gian 48 giờ xử lý:- Khách hàng có thể hủy ủy nhiệm qua ứng dụng ngân hàng của họ.
- Nếu khách hàng hủy ủy nhiệm trong thời gian này, đăng ký sẽ vẫn hoạt động (đây là một trường hợp đặc biệt đối với đăng ký tự động UPI và thẻ Ấn Độ).
- Tuy nhiên, việc khấu trừ thực tế có thể thất bại, và trong trường hợp đó, chúng tôi sẽ đặt đăng ký tạm dừng.
- Trì hoãn kích hoạt quyền lợi cho đến khi xác nhận thanh toán
- Triển khai các giai đoạn ân hạn hoặc quyền truy cập tạm thời
- Giám sát trạng thái đăng ký để phát hiện hủy ủy nhiệm
- Xử lý trạng thái tạm dừng đăng ký trong logic ứng dụng của bạn
Thực Hành Tốt Nhất
- Bắt đầu với các cấp rõ ràng: 2–3 kế hoạch có sự khác biệt rõ ràng
- Truyền đạt giá cả: Hiển thị tổng cộng, tỷ lệ, và lần gia hạn tiếp theo
- Sử dụng thử nghiệm một cách khôn ngoan: Chuyển đổi với quá trình onboarding, không chỉ là thời gian
- Tận dụng bổ sung: Giữ các kế hoạch cơ bản đơn giản và bán thêm những thứ phụ
- Thử nghiệm thay đổi: Xác nhận các thay đổi kế hoạch và tỷ lệ trong chế độ thử nghiệm
Đăng ký là một nền tảng linh hoạt cho doanh thu định kỳ. Bắt đầu đơn giản, kiểm tra kỹ lưỡng, và lặp lại dựa trên số liệu chấp nhận, rời bỏ và mở rộng.