Subscriptions - Dodo Payments Documentation

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.

Pick the most accurate tax category to ensure correct tax collection per region.

Pricing

Loại giá: Chọn Subscription (hướng dẫn này). Các lựa chọn thay thế là Single Payment và Usage Based Billing.
Giá (bắt buộc): Giá định kỳ cơ bản kèm đơn vị tiền tệ. Giá phải ít nhất là $1 (hoặc giá trị tương đương theo đơn vị tiền tệ bạn chọn). Các khoản tiền dưới mức tối thiểu này không được hỗ trợ và subscription sẽ không hoạt động.
Discount Applicable (%): Tỷ lệ giảm giá tùy chọn áp dụng cho giá cơ bản; được phản ánh trong checkout và hóa đơn.
Lặp lại thanh toán mỗi (bắt buộc): Khoảng thời gian gia hạn, ví dụ mỗi 1 Month. Chọn chu kỳ (tháng hoặc năm) và số lượng.
Thời hạn Subscription (bắt buộc): Tổng thời hạn subscription duy trì trạng thái hoạt động (ví dụ 10 Years). Sau khi thời hạn này kết thúc, việc gia hạn sẽ dừng trừ khi được kéo dài.
Số ngày dùng thử (bắt buộc): Đặt thời lượng dùng thử theo ngày. Sử dụng 0 để tắt dùng thử. Khoản phí đầu tiên sẽ tự động được thu khi thời gian dùng thử kết thúc.
Số tiền dùng thử: Khoản phí trả trước tùy chọn cho paid trial. Để trống nếu muốn dùng thử miễn phí. Xem Paid Trials.
Chọn add-on: Đính kèm tối đa 10 add-on mà khách hàng có thể mua cùng gói cơ bản.

Changing pricing on an active product affects new purchases. Existing subscriptions follow your plan‑change and proration settings.

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.

Use metadata to store identifiers from your system (e.g., accountId) so you can reconcile events and invoices later.

Subscription Trials

Trial cho phép khách hàng đánh giá subscription trước khi thanh toán đầy đủ mức giá định kỳ. Trial có thể là free, trong đó không khoản phí nào được thu cho đến khi trial kết thúc, hoặc paid, trong đó một khoản tiền giảm được thu trước. Trong cả hai trường hợp, giá đầy đủ sẽ bắt đầu từ lần gia hạn đầu tiên sau khi trial kết thúc.

Configuring Trials

Set Trial Period Days in the product pricing section (use 0 to disable). You can override this when creating subscriptions:

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_monthly',
  trial_period_days: 14  // Overrides product's trial period
});

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

The trial_period_days value must be between 0 and 10,000 days.

Paid Trials

Trial không nhất thiết phải miễn phí. Đặt Trial Amount trên giá định kỳ của sản phẩm subscription để thu một khoản phí trả trước đã giảm trong thời gian trial. Sau đó, giá định kỳ đầy đủ sẽ được áp dụng từ lần gia hạn đầu tiên.

Biểu mẫu định giá subscription với thời lượng trial và số tiền trial tùy chọn cho paid trial

Paid trial được cấu hình trên giá của sản phẩm, không phải trên từng subscription hoặc checkout session:

Trường	Kiểu	Mô tả
`trial_amount`	integer	Số tiền được thu hôm nay cho trial, theo đơn vị nhỏ nhất của đơn vị tiền tệ trong giá (ví dụ `500` cho $5.00). Yêu cầu `trial_period_days > 0`. Bỏ qua hoặc đặt thành `null` để dùng free trial.
`trial_apply_discounts`	boolean	Cho biết mã giảm giá checkout có làm giảm khoản phí trial hay không. Mặc định là `false`, vì vậy toàn bộ Trial Amount vẫn được thu ngay cả khi giảm giá áp dụng cho giá định kỳ.

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',
    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 trial cũng đi qua checkout. Trial amount chịu thuế, được hiển thị trong các phép tính của checkout session và giá của payment link, đồng thời markup Adaptive Currency được áp dụng theo từng đơn vị tiền tệ. Preview endpoint trả về trial_amount và trial_period_days để bạn có thể hiển thị số tiền đến hạn hôm nay trước khi subscription được tạo.

Free trial không thay đổi. Để trống Trial Amount sẽ giữ nguyên hành vi hiện tại, trong đó khoản phí đầu tiên là 0 và giá đầy đủ được thu khi trial kết thúc.

Ngăn lạm dụng Trial

Prevent Trial Misuse ngăn khách hàng liên tục yêu cầu trial cho cùng một doanh nghiệp. Khi được bật, khách hàng đã từng sử dụng trial sẽ tự động được chuyển thành paid, no-trial purchase thay vì nhận một trial mới.

Công tắc Prevent Trial Misuse trong tab cài đặt Subscriptions

Bật tùy chọn này từ tab Subscriptions trong Settings. Sau khi được bật:

Khách hàng được đối chiếu theo email đã chuẩn hóa, trong đó các bí danh dấu cộng bị loại bỏ, vì vậy user+trial@example.com và user@example.com được tính là cùng một người.
Lượt sử dụng được ghi nhận tại thời điểm kích hoạt trial, vì vậy khách hàng hủy ngay trong ngày vẫn đã sử dụng trial.
Khách hàng hiện tại được bổ sung dữ liệu từ các trial trước đây của họ dựa trên email, nên người dùng trial trong quá khứ được nhận diện ngay lập tức.

Tùy chọn này tắt theo mặc định. Xem Subscription Settings để biết danh sách đầy đủ các tùy chọn kiểm soát subscription ở cấp doanh nghiệp.

Phát hiện trạng thái Trial

Hiện tại chưa có field trực tiếp để phát hiện trạng thái trial. Cách giải quyết tạm thời dưới đây yêu cầu truy vấn các payment, nên không hiệu quả. Chúng tôi đang phát triển một giải pháp hiệu quả hơn.

Để xác định một subscription free trial có đang trong thời gian trial hay không, hãy lấy danh sách payment của subscription. Nếu có chính xác một payment với amount bằng 0, subscription đang trong thời gian trial:

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;

Kiểm tra amount bằng 0 này chỉ hoạt động với free trial. Với paid trial, payment đầu tiên bằng trial amount, không phải 0. Thay vào đó, hãy so sánh payment đầu tiên với trial_amount của subscription hoặc kiểm tra xem next_billing_date còn nằm trong thời gian trial hay không.

Cập nhật thời gian Trial

Kéo dài trial bằng cách cập nhật next_billing_date:

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

Bạn không thể đặt next_billing_date thành thời điểm trong quá khứ. Ngày này phải nằm trong tương lai.

Thay đổi Subscription Plan

Thay đổi plan cho phép bạn nâng cấp hoặc hạ cấp subscription, điều chỉnh số lượng hoặc chuyển sang sản phẩm khác. Tùy theo proration mode được chọn, thay đổi có thể tạo khoản phí ngay lập tức, tạo credit hoặc không điều chỉnh billing.

Bạn có thể thay đổi subscription plan và cập nhật ngày billing tiếp theo trực tiếp từ dashboard Dodo Payments. Đây là cách nhanh chóng để điều chỉnh subscription theo yêu cầu hỗ trợ khách hàng, nâng cấp khuyến mãi hoặc chuyển đổi plan mà không cần gọi API.

Bật tính năng thay đổi plan tự phục vụ: Bạn muốn khách hàng tự nâng cấp hoặc hạ cấp subscription thông qua Customer Portal? Thêm các sản phẩm subscription vào Product Collection và bật “Allow Subscription Updates” trong Subscription Settings.

Product Collections

Nhóm các sản phẩm liên quan vào collections để bật quy trình nâng cấp/hạ cấp liền mạch trong Customer Portal.

Proration Modes

Chọn cách tính phí cho khách hàng khi thay đổi plan:

So sánh nhanh bốn proration mode:

	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Nâng cấp	Tính phí theo tỷ lệ cho số ngày còn lại	Thu toàn bộ phần chênh lệch giá	Thu toàn bộ giá của plan mới	Không tính phí — chuyển ngay lập tức
Hạ cấp	Tạo credit theo tỷ lệ cho số ngày còn lại	Toàn bộ phần chênh lệch giá được chuyển thành credit	Không có credit, thu đầy đủ	Không có credit — chuyển ngay lập tức
Chu kỳ billing	Đặt lại về hôm nay	Đặt lại về hôm nay	Đặt lại về hôm nay	Giữ nguyên
Phù hợp nhất cho	Billing công bằng theo thời gian	Thay đổi tier đơn giản	Đặt lại chu kỳ billing	Chuyển đổi miễn phí hoặc hỗ trợ đặc biệt

`prorated_immediately`

Tính phí theo tỷ lệ dựa trên thời gian còn lại trong chu kỳ billing hiện tại. Phù hợp nhất cho cách tính phí công bằng, có tính đến thời gian chưa sử dụng.

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

`difference_immediately`

Thu phần chênh lệch giá ngay lập tức (khi nâng cấp) hoặc cộng credit cho các lần gia hạn trong tương lai (khi hạ cấp). Phù hợp nhất cho các trường hợp nâng cấp/hạ cấp đơn giản.

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

Credit từ việc hạ cấp bằng difference_immediately được giới hạn trong subscription và tự động áp dụng cho các lần gia hạn trong tương lai. Chúng khác với các quyền lợi của Credit-Based Billing.

Khi khách hàng hạ cấp bằng difference_immediately, giá trị chưa sử dụng trở thành credit giới hạn trong subscription và tự động bù trừ cho các lần gia hạn trong tương lai:

`full_immediately`

Thu toàn bộ số tiền của plan mới ngay lập tức, bỏ qua thời gian còn lại. Phù hợp nhất để đặt lại chu kỳ billing.

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

`do_not_bill`

Chuyển sang plan mới mà không điều chỉnh billing. Không có phí proration và không có credit — khách hàng chỉ cần chuyển sang plan mới. Phù hợp nhất cho việc chuyển đổi hỗ trợ đặc biệt, chuyển đổi plan miễn phí hoặc các trường hợp bạn muốn tự chịu phần chênh lệch chi phí.

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

Example: Prorated upgrade calculation

Tình huống: Khách hàng đang dùng Basic (

30/tháng) nâng cấp lên Pro (

80/tháng) vào ngày thứ 16 của chu kỳ 30 ngày bằng prorated_immediately.

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

Lần gia hạn tiếp theo vào 15 tháng 2 (16 tháng 1 + 30 ngày): $80.00/tháng.

Để xem thêm các ví dụ tính toán chi tiết và trường hợp đặc biệt, hãy xem Upgrade & Downgrade Guide đầy đủ của chúng tôi.

Example: Downgrade credit calculation

Tình huống: Khách hàng đang dùng Pro (

80/tháng) hạ cấp xuống Starter (

20/tháng) bằng difference_immediately.

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

Credit $60 tự động được áp dụng cho các lần gia hạn trong tương lai:

Lần gia hạn 1: $20 −$ 20 (credit) = ** $0.00** (còn lại$ 40 credit)
Lần gia hạn 2: $20 −$ 20 (credit) = ** $0.00** (còn lại$ 20 credit)
Lần gia hạn 3: $20 −$ 20 (credit) = $0.00 (credit đã hết)
Lần gia hạn 4: $20.00 (giá đầy đủ)

Tìm hiểu thêm về cách quản lý credit trong Upgrade & Downgrade Guide.

Thay đổi Plan với Add-on

Điều chỉnh add-on khi thay đổi plan. Add-on được đưa vào các phép tính proration:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_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
});

Thay đổi plan sẽ tạo khoản phí ngay lập tức. Các khoản phí thất bại có thể chuyển subscription sang trạng thái on_hold. Theo dõi thay đổi qua các webhook event subscription.plan_changed.

Xem trước thay đổi Plan

Trước khi xác nhận thay đổi plan, hãy xem trước khoản phí chính xác và subscription sau thay đổi:

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'prod_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

Xem trước các thay đổi plan trước khi xác nhận.

Trạng thái Subscription

Một subscription sẽ trải qua một tập hợp trạng thái được xác định trong suốt vòng đời. Bảng này là tài liệu tham chiếu cho từng trạng thái, nguyên nhân tạo ra trạng thái đó và cách (hoặc liệu) bạn có thể khôi phục hay không.

Trạng thái	Ý nghĩa	Có thể khôi phục?	Cách khôi phục / bước tiếp theo
`pending`	Subscription đang được tạo hoặc xử lý	—	Chờ `subscription.active` (hoặc `subscription.failed`)
`active`	Subscription đang hoạt động và sẽ tự động gia hạn	—	Không cần thao tác
`on_hold`	Payment gia hạn (hoặc khoản phí thay đổi plan) thất bại; subscription bị tạm dừng	Có	Cập nhật payment method để kích hoạt lại — tự động qua Payment Retries và Dunning, hoặc thủ công qua Update Payment Method API
`cancelled`	Subscription đã bị hủy và sẽ không gia hạn	Chỉ mua lại	Khách hàng phải bắt đầu subscription mới; Dunning có thể nhắc khách hàng mua lại
`failed`	Tạo subscription thất bại (mandate hoặc payment ban đầu không thành công)	Không — trạng thái kết thúc	Khách hàng phải tạo subscription mới bằng payment method hoạt động
`expired`	Subscription đã đến cuối thời hạn	—	Khách hàng phải bắt đầu subscription mới nếu có nhu cầu

on_hold và failed thường bị nhầm lẫn. on_hold là trạng thái có thể khôi phục của subscription đã hoạt động nhưng gia hạn thất bại. failed là trạng thái kết thúc chỉ xảy ra khi việc tạo subscription ban đầu thất bại — không thể kích hoạt lại trạng thái này.

State Machine

Trạng thái On Hold

Subscription chuyển sang trạng thái on_hold khi:

Payment gia hạn thất bại (không đủ tiền, thẻ hết hạn, v.v.)
Khoản phí thay đổi plan thất bại
Ủy quyền payment method thất bại

Khi subscription ở trạng thái on_hold, subscription sẽ không tự động gia hạn. Bạn phải cập nhật payment method để kích hoạt lại subscription.

Kích hoạt lại từ On Hold

Để kích hoạt lại subscription từ trạng thái on_hold, hãy cập nhật payment method. Thao tác này tự động:

Tạo khoản phí cho các khoản còn nợ
Tạo hóa đơn
Xử lý payment bằng payment method mới
Chuyển subscription về trạng thái active sau khi payment thành công

// 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
}

Sau khi cập nhật thành công payment method cho subscription on_hold, bạn sẽ nhận được webhook event payment.succeeded, tiếp theo là subscription.active.

Webhook Event theo Chuyển đổi Trạng thái

Mỗi lần chuyển đổi sẽ phát ra một webhook để bạn có thể điều khiển logic entitlement mà không cần polling:

Chuyển đổi	Event
Subscription đượ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`
Plan được nâng cấp/hạ cấp	`subscription.plan_changed`
Đã hủy	`subscription.cancelled`
Kết thúc thời hạn	`subscription.expired`
Bất kỳ field nào thay đổi	`subscription.updated`

Subscription Webhook Payloads

Xem schema payload đầy đủ cho các event trong vòng đời subscription.

Quản lý API

Create subscriptions

Sử dụng POST /subscriptions để lập trình tạo subscription từ các sản phẩm, với trial và add-on tùy chọn.

API Reference

Xem API tạo subscription.

Update subscriptions

Sử dụng PATCH /subscriptions/{id} để cập nhật số lượng, hủy vào ngày billing tiếp theo hoặc chỉnh sửa metadata.

API Reference

Tìm hiểu cách cập nhật thông tin subscription.

Change plans (proration)

Thay đổi sản phẩm đang hoạt động và số lượng bằng các tùy chọn kiểm soát proration.

API Reference

Xem lại các tùy chọn thay đổi plan.

On‑demand charges

Đối với subscription on-demand, thu các khoản tiền cụ thể theo nhu cầu.

API Reference

Thu phí subscription on-demand.

List and retrieve

Sử dụng GET /subscriptions để liệt kê tất cả subscription và GET /subscriptions/{id} để lấy một subscription.

API Reference

Duyệt các API liệt kê và truy xuất.

Usage history

Lấy usage đã ghi nhận cho các mô hình định giá theo usage hoặc hybrid.

API Reference

Xem API lịch sử usage.

Update payment method

Cập nhật payment method cho subscription. Đối với subscription đang hoạt động, thao tác này cập nhật payment method cho các lần gia hạn trong tương lai. Đối với subscription ở trạng thái on_hold, thao tác này kích hoạt lại subscription bằng cách tạo khoản phí cho các khoản còn nợ.Khi tạo payment-method link mới (loại request New), bạn có thể truyền allowed_payment_method_types để giới hạn các payment method khách hàng nhìn thấy trên trang đó. Khách hàng sẽ không bao giờ thấy phương thức không có trong danh sách, dù việc đưa một phương thức vào danh sách không đảm bảo phương thức đó sẽ xuất hiện (tính khả dụng 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).

API Reference

Tìm hiểu cách cập nhật payment method và kích hoạt lại subscription.

Trường hợp sử dụng phổ biến

SaaS và API: Quyền truy cập theo tier với add-on cho seat hoặc usage
Nội dung và media: Quyền truy cập hàng tháng với trial giới thiệu
Gói hỗ trợ B2B: Hợp đồng hàng năm với add-on hỗ trợ cao cấp
Công cụ và plugin: License key và bản phát hành theo version

Ví dụ tích hợp

Checkout Session (subscription)

Khi tạo checkout session, hãy thêm sản phẩm subscription và các add-on tùy chọn:

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

Thay đổi plan với proration

Nâng cấp hoặc hạ cấp subscription và kiểm soát hành vi proration:

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

Hủy vào ngày billing tiếp theo

Lên lịch hủy có hiệu lực vào cuối kỳ billing hiện tại:

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

Kéo dài thời hạn subscription

Kéo dài thời gian subscription bằng cách truyền subscription_period_count và subscription_period_interval mới vào PATCH /subscriptions/{id}. Thời điểm hết hạn của subscription được tính lại từ số lượng và khoảng thời gian mới — ví dụ để cấp thêm thời gian cho khách hàng trong plan hiện tại:

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

Thời hạn của subscription chỉ có thể được tăng, không thể rút ngắn.

Subscription on-demand

Tạo subscription on-demand và thu phí sau khi cần:

const onDemand = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_on_demand',
  on_demand: { mandate_only: true }
});

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

Cập nhật payment method cho subscription đang hoạt động

Cập nhật payment method cho subscription đang hoạt động:

// 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'
  }
});

Kích hoạt lại subscription từ on_hold

Kích hoạt lại subscription bị on hold do payment thất bại:

// 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
}

Subscription với Mandate tuân thủ RBI

Subscription UPI và thẻ Ấn Độ hoạt động theo quy định RBI (Reserve Bank of India) với các yêu cầu mandate cụ thể:

Giới hạn Mandate

Loại và số tiền mandate phụ thuộc vào khoản phí định kỳ của subscription:

Khoản phí dưới mức sàn mandate (mặc định ₹15,000): Chúng tôi tạo mandate on-demand cho số tiền sàn. Số tiền subscription được thu định kỳ theo tần suất subscription, tối đa đến giới hạn mandate.
Khoản phí bằng hoặc cao hơn mức sàn mandate: Chúng tôi tạo mandate subscription (hoặc mandate on-demand) cho đúng số tiền subscription.

Mức sàn mandate có thể được cấu hình theo merchant hoặc theo request thông qua mandate_min_amount_inr_paise (INR paise). Số tiền đăng ký với ngân hàng là max(mandate_floor, billing_amount) — vì vậy mức sàn thực tế trở thành giới hạn ủy quyền mà khách hàng nhìn thấy bất cứ khi nào số tiền billing thấp hơn. Để biết thông tin chi tiết về mandate tuân thủ RBI và mức sàn mandate có thể cấu hình cho các payment method của Ấn Độ, hãy xem trang India Payment Methods.

Lưu ý khi Nâng cấp và Hạ cấp

Quan trọng: Khi nâng cấp hoặc hạ cấp subscription, hãy cân nhắc cẩn thận các giới hạn mandate:

Nếu việc nâng cấp/hạ cấp dẫn đến khoản phí vượt quá Rs 15,000 và vượt giới hạn payment on-demand hiện tại, khoản phí giao dịch có thể thất bại.
Trong trường hợp này, khách hàng có thể cần cập nhật payment method hoặc thay đổi subscription lần nữa để thiết lập mandate mới với giới hạn phù hợp.

Ủy quyền cho Khoản phí Giá trị cao

Đối với khoản phí subscription từ Rs 15,000 trở lên:

Ngân hàng sẽ yêu cầu khách hàng ủy quyền giao dịch.
Nếu khách hàng không ủy quyền giao dịch, giao dịch sẽ thất bại và subscription sẽ bị on hold.

Trì hoãn Xử lý 48 giờ

Lịch xử lý: Các khoản phí định kỳ trên thẻ Ấn Độ và subscription UPI tuân theo một quy trình xử lý đặc biệt:

Khoản phí được khởi tạo vào ngày đã lên lịch theo tần suất subscription.
Khoản khấu trừ thực tế từ tài khoản khách hàng chỉ diễn ra sau 48 giờ kể từ khi khởi tạo payment.
Khoảng thời gian 48 giờ này có thể kéo dài thêm 2-3 giờ tùy theo phản hồi của bank API.

Khoảng thời gian Hủy Mandate

Trong khoảng thời gian xử lý 48 giờ:

Khách hàng có thể hủy mandate thông qua ứng dụng ngân hàng.
Nếu khách hàng hủy mandate trong khoảng thời gian này, subscription vẫn giữ trạng thái active (đây là trường hợp đặc biệt chỉ áp dụng cho subscription AutoPay bằng thẻ Ấn Độ và UPI).
Tuy nhiên, khoản khấu trừ thực tế có thể thất bại và trong trường hợp đó, chúng tôi sẽ chuyển subscription sang on hold.

Xử lý trường hợp đặc biệt: Nếu bạn cung cấp quyền lợi, credit hoặc usage subscription cho khách hàng ngay khi khởi tạo khoản phí, bạn cần xử lý phù hợp khoảng thời gian 48 giờ này trong ứng dụng. Hãy cân nhắc:

Trì hoãn việc kích hoạt quyền lợi cho đến khi xác nhận payment
Triển khai thời gian gia hạn hoặc quyền truy cập tạm thời
Theo dõi trạng thái subscription để phát hiện việc hủy mandate
Xử lý trạng thái on hold của subscription trong logic ứng dụng

Theo dõi webhook của subscription để kiểm tra các thay đổi trạng thái payment và xử lý những trường hợp đặc biệt khi mandate bị hủy trong khoảng thời gian 48 giờ.

Best Practices

Bắt đầu với các tier rõ ràng: 2–3 plan có khác biệt dễ nhận thấy
Truyền đạt thông tin giá: Hiển thị tổng tiền, proration và lần gia hạn tiếp theo
Sử dụng trial hợp lý: Tăng chuyển đổi bằng onboarding, không chỉ bằng thời gian
Tận dụng add-on: Giữ plan cơ bản đơn giản và bán thêm tính năng bổ sung
Kiểm thử các thay đổi: Xác thực thay đổi plan và proration ở test mode

Subscription là nền tảng linh hoạt cho doanh thu định kỳ. Hãy bắt đầu đơn giản, kiểm thử kỹ lưỡng và cải tiến dựa trên các chỉ số adoption, churn và expansion.

Upgrade & Downgrade

On‑Demand Subscriptions

Customer Portal

Subscription Webhooks

​What Are Subscriptions?

​Key Benefits

​Creating Subscriptions

​Subscription product creation

​Product details

​Pricing

​Advanced settings

​Subscription Trials

​Configuring Trials

​Paid Trials

​Ngăn lạm dụng Trial

​Phát hiện trạng thái Trial

​Cập nhật thời gian Trial

​Thay đổi Subscription Plan

Product Collections

​Proration Modes

​prorated_immediately

​difference_immediately

​full_immediately

​do_not_bill

​Thay đổi Plan với Add-on

​Xem trước thay đổi Plan

Preview Change Plan API

​Trạng thái Subscription

​State Machine

​Trạng thái On Hold

​Kích hoạt lại từ On Hold

​Webhook Event theo Chuyển đổi Trạng thái

Subscription Webhook Payloads

​Quản lý API

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​Trường hợp sử dụng phổ biến

​Ví dụ tích hợp

​Checkout Session (subscription)

​Thay đổi plan với proration

​Hủy vào ngày billing tiếp theo

​Kéo dài thời hạn subscription

​Subscription on-demand

​Cập nhật payment method cho subscription đang hoạt động

​Kích hoạt lại subscription từ on_hold

​Subscription với Mandate tuân thủ RBI

​Giới hạn Mandate

​Lưu ý khi Nâng cấp và Hạ cấp

​Ủy quyền cho Khoản phí Giá trị cao

​Trì hoãn Xử lý 48 giờ

​Khoảng thời gian Hủy Mandate

​Best Practices

What Are Subscriptions?

Key Benefits

Creating Subscriptions

Subscription product creation

Product details

Pricing

Advanced settings

Subscription Trials

Configuring Trials

Paid Trials

Ngăn lạm dụng Trial

Phát hiện trạng thái Trial

Cập nhật thời gian Trial

Thay đổi Subscription Plan

Proration Modes

`prorated_immediately`

`difference_immediately`

`full_immediately`

`do_not_bill`

Thay đổi Plan với Add-on

Xem trước thay đổi Plan

Trạng thái Subscription

State Machine

Trạng thái On Hold

Kích hoạt lại từ On Hold

Webhook Event theo Chuyển đổi Trạng thái

Quản lý API

Trường hợp sử dụng phổ biến

Ví dụ tích hợp

Checkout Session (subscription)

Thay đổi plan với proration

Hủy vào ngày billing tiếp theo

Kéo dài thời hạn subscription

Subscription on-demand

Cập nhật payment method cho subscription đang hoạt động

Kích hoạt lại subscription từ on_hold

Subscription với Mandate tuân thủ RBI

Giới hạn Mandate

Lưu ý khi Nâng cấp và Hạ cấp

Ủy quyền cho Khoản phí Giá trị cao

Trì hoãn Xử lý 48 giờ

Khoảng thời gian Hủy Mandate

Best Practices