Subscriptions

​

What Are Subscriptions?

• 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

• Doanh thu có thể dự đoán: Thanh toán định kỳ với gia hạn tự động
• Chu kỳ linh hoạt: Hàng tháng, hàng năm, khoảng thời gian tùy chỉnh và thời gian dùng thử
• Linh hoạt về gói: Phân bổ theo tỷ lệ khi nâng cấp và hạ cấp
• Tiện ích bổ sung và số lượng chỗ: Gắn các nâng cấp tùy chọn có thể định lượng
• Checkout được lưu trữ: Các trang Checkout và Customer Portal
• Ưu tiên nhà phát triển: API rõ ràng để tạo, thay đổi và theo dõi mức sử dụng

​

Creating Subscriptions

​

Tạo sản phẩm Subscription

​

Thông tin sản phẩm

• Tên sản phẩm (bắt buộc): Tên hiển thị trong checkout, Customer Portal và hóa đơn.
• Mô tả sản phẩm (tùy chọn): Nội dung nêu rõ giá trị, xuất hiện trong checkout và hóa đơn.
• Hình ảnh sản phẩm (tùy chọn): PNG/JPG/WebP tối đa 3 MB. Được sử dụng trong checkout và hóa đơn.
• Thương hiệu: Liên kết sản phẩm với một thương hiệu cụ thể để áp dụng giao diện và email.
• Danh mục thuế (bắt buộc): Chọn danh mục (ví dụ: SaaS) để xác định các quy tắc thuế.

​

Pricing

• Loại giá: Chọn Subscription (theo hướng dẫn này). Các lựa chọn khác 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á khác 0 phải ít nhất là $1 (hoặc giá trị tương đương theo đơn vị tiền tệ đã chọn) — các khoản thấp hơn mức tối thiểu này không được hỗ trợ. Giá chính xác $0 là một trường hợp riêng được hỗ trợ; xem Card-Optional at Zero Price.
• Discount Applicable (%): Phần trăm giảm giá tùy chọn áp dụng cho giá cơ bản; được thể hiện trong checkout và hóa đơn.
• Repeat payment every (bắt buộc): Khoảng thời gian giữa các lần gia hạn, ví dụ mỗi 1 Month. Chọn tần suất (tháng hoặc năm) và số lượng.
• Subscription Period (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.
• Trial Period Days (bắt buộc): Đặt thời lượng dùng thử theo số ngày. Dùng 0 để tắt thời gian 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.
• Trial Amount: Khoản phí trả trước tùy chọn cho thời gian dùng thử có tính phí. Để trống nếu muốn dùng thử miễn phí. Xem Paid Trials.
• Card-optional at $0 Price: Cho phép khách hàng bắt đầu subscription mà không cần thêm thẻ khi giá là $0 hoặc khoản giảm giá khiến hôm nay không còn khoản phải trả. Thời gian dùng thử miễn phí có checkbox riêng Start the trial without a card. Xem Card-Optional at Zero Price.
• Select add-on: Gắn tối đa 10 tiện ích bổ sung mà khách hàng có thể mua cùng gói cơ bản.

​

Cài đặt nâng cao

• Tax Inclusive Pricing: Hiển thị giá đã bao gồm các loại thuế áp dụng. Phép tính thuế cuối cùng vẫn thay đổi tùy theo vị trí của khách hàng.
• Generate license keys: Cấp một key duy nhất cho mỗi khách hàng sau khi mua. Xem hướng dẫn License Keys.
• Digital Product Delivery: Tự động cung cấp tệp hoặc nội dung sau khi mua. Tìm hiểu thêm trong Digital Product Delivery.
• Metadata: Đính kèm các cặp key–value tùy chỉnh để gắn thẻ nội bộ hoặc tích hợp với client. Xem Metadata.

​

Subscription Trials

​

Cấu hình Trial

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

// Via subscription creation (deprecated)
// Note: POST /subscriptions is deprecated — prefer checkout sessions
const subscription = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_monthly',
  quantity: 1,
  trial_period_days: 14
});

​

Paid Trials

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_bps: 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,
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false
  }
});

​

Card-Optional at Zero Price

• Thời gian dùng thử miễn phí: trial_period_days được đặt nhưng không có trial_amount, vì vậy khoản phí đầu tiên là $0 trong thời gian dùng thử. Chọn Start the trial without a card bên dưới Trial Period (Days).
• Giá định kỳ $0: Giá tự thân là $0 hoặc một khoản giảm giá đưa giá xuống $0 (mục Default Discount (%) của sản phẩm hoặc mã giảm giá được áp dụng tại checkout). Chọn Card-optional at $0 Price.

​

Điều gì xảy ra khi không có thẻ

1. Email nhắc nhở được gửi trước khi bắt đầu tính phí thực tế. Số ngày nhắc trước được thiết lập trên toàn doanh nghiệp tại Payment Method Reminder trong Settings → Subscriptions — xem Subscription Settings. Email Add Payment Method Reminder của khách hàng (xem Customer Emails) dẫn trực tiếp đến Customer Portal để thêm thẻ.
2. Nếu không thêm thẻ kịp thời, subscription sẽ chuyển sang on_hold khi trial kết thúc hoặc thời gian giảm giá hết hạn và khoản phí thực tế đến hạn — cùng trạng thái on_hold mà mọi subscription đều có thể chuyển sang, nhưng lần này là do chưa từng thêm payment method. Khách hàng sẽ nhận email Subscription On Hold, No Payment Method.
3. Thêm payment method sẽ kích hoạt lại subscription, đúng như mô tả trong Reactivating from On Hold — một khoản phí được tạo cho số tiền hiện đến hạn và subscription trở về active sau khi thanh toán thành công.

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

​

Thay đổi Subscription Plan

​

Proration Modes

​

prorated_immediately

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

​

difference_immediately

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

​

full_immediately

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

​

do_not_bill

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

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

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

​

Thay đổi Plan với Add-on

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

​

Xem trước thay đổi Plan

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);

​

Tạm dừng và tiếp tục Subscription

​

Điều gì xảy ra khi bạn tạm dừng

• Các lần gia hạn dừng lại. Không có invoice nào được tạo và không có khoản phí gia hạn nào được thực hiện trong khi subscription bị tạm dừng.
• Quyền truy cập bị thu hồi ngay lập tức. Việc tạm dừng sẽ thu hồi mọi entitlement grant đã cấp và đang chờ cấp trên subscription, vô hiệu hóa license keys và ngừng cấp URL tải xuống digital product mới. Khi tiếp tục, các quyền này sẽ được cấp lại, giống như khi khôi phục từ on_hold.
• Đồng hồ billing đóng băng. next_billing_date và expires_at đều tiến về sau chính xác bằng thời lượng tạm dừng, để customer giữ được khoảng thời gian họ đã thanh toán.
• Không có giới hạn về thời lượng tạm dừng. Subscription bị tạm dừng sẽ tiếp tục ở trạng thái đó cho đến khi có người tiếp tục. Bạn không cần đặt trước thời lượng tạm dừng.

​

Tạm dừng Subscription tính phí theo usage

​

Cho phép Customer tự tạm dừng Subscription

​

Tạm dừng qua API

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

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

​

Tạm dừng và các thao tác Subscription khác

• Việc hủy vẫn hoạt động. Bạn có thể hủy subscription bị tạm dừng giống hệt subscription đang active. Mọi settlement invoice đang mở từ lần tạm dừng sẽ bị void khi bạn thực hiện việc này.
• Các thay đổi plan đã lên lịch bị trì hoãn, không bị loại bỏ. Plan change được lên lịch vào ngày billing tiếp theo sẽ giữ nguyên trong khi subscription bị tạm dừng, sau đó được áp dụng vào ngày billing đã dịch chuyển khi subscription tiếp tục. scheduled_change.effective_at của thay đổi là snapshot tại thời điểm lên lịch và không được điều chỉnh theo thời gian tạm dừng, nên có thể hiển thị một ngày trong quá khứ — hãy hiểu đó là “đã được lên lịch vào”, không phải ngày được đảm bảo. Để loại bỏ thay đổi thay vì tiếp tục áp dụng, hãy sử dụng Cancel Scheduled Plan Change.

​

Các trạng thái Subscription

​

State Machine

​

Trạng thái On Hold

• Payment gia hạn thất bại (không đủ tiền, thẻ hết hạn, v.v.)
• Phí thay đổi plan thất bại
• Việc ủy quyền payment method thất bại
• Pause settlement invoice của subscription tính phí theo usage không được thanh toán

​

Kích hoạt lại từ trạng thái On Hold

1. Tạo khoản charge cho các khoản còn nợ
2. Tạo invoice
3. Xử lý payment bằng payment method mới
4. Đưa 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
}

​

Webhook Event theo Transition

​

Quản lý API

​

Các 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
• Content và media: Quyền truy cập hàng tháng với trial giới thiệu
• Plan hỗ trợ B2B: Hợp đồng hàng năm với add-on hỗ trợ cao cấp
• Tools và plugin: License key và các bản phát hành theo version

​

Ví dụ Integration

​

Checkout Sessions (subscription)

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

​

Thay đổi plan với proration

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

​

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

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

​

Gia hạn thời hạn Subscription

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

​

Subscription on-demand

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

​

Cập nhật payment method cho Subscription đang active

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

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

​

Giới hạn Mandate

• Charge thấp hơn mandate floor (mặc định ₹15,000): Chúng tôi tạo on-demand mandate với amount bằng floor. Amount subscription được tính định kỳ theo tần suất subscription, tối đa bằng mandate limit.
• Charge bằng hoặc cao hơn mandate floor: Chúng tôi tạo subscription mandate (hoặc on-demand mandate) với amount subscription chính xác.

​

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

• Nếu việc nâng cấp/hạ cấp tạo ra amount charge vượt quá Rs 15,000 và vượt existing on-demand payment limit, transaction charge có thể thất bại.
• Trong trường hợp này, customer 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 limit phù hợp.

​

Authorization cho Charge có Giá trị Cao

• Ngân hàng sẽ yêu cầu customer authorize transaction.
• Nếu customer không authorize transaction, transaction sẽ thất bại và subscription sẽ được chuyển sang on hold.

​

Độ trễ Xử lý 48 giờ

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

​

Khoảng thời gian Hủy Mandate

• Customer có thể hủy mandate qua banking app của họ.
• Nếu customer hủy mandate trong khoảng thời gian này, subscription vẫn active (đây là edge case chỉ áp dụng cho Indian card và subscription UPI AutoPay).
• Tuy nhiên, deduction 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.

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

​

Best Practices

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

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

​

Plan changes with proration

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

​

Cancel at next billing date

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

​

Extend the subscription period

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

​

On‑demand subscriptions

// Note: POST /subscriptions is deprecated — prefer checkout sessions for new integrations
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'
});

​

Update payment method for active subscription

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

​

Reactivate subscription from on_hold

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

​

Subscriptions with RBI-Compliant Mandates

​

Mandate Limits

• Charges below the mandate floor (default ₹15,000): We create an on-demand mandate for the floor amount. The subscription amount is charged periodically according to your subscription frequency, up to the mandate limit.
• Charges at or above the mandate floor: We create a subscription mandate (or on-demand mandate) for the exact subscription amount.

​

Upgrade and Downgrade Considerations

• If an upgrade/downgrade results in a charge amount that exceeds Rs 15,000 and goes beyond the existing on-demand payment limit, the transaction charge may fail.
• In such cases, the customer may need to update their payment method or change the subscription again to establish a new mandate with the correct limit.

​

Authorization for High-Value Charges

• The customer will be prompted by their bank to authorize the transaction.
• If the customer fails to authorize the transaction, the transaction will fail and the subscription will be put on hold.

​

48-Hour Processing Delay

• Nếu việc nâng cấp/hạ cấp dẫn đến số tiền tính phí vượt quá hạn mức tối thiểu của mandate (mặc định là ₹15.000) và vượt quá giới hạn thanh toán on-demand hiện tại, giao dịch có thể bị lỗi.
• Khách hàng có thể cần cập nhật phương thức thanh toán hoặc thay đổi gói đăng ký một lần nữa để thiết lập mandate mới với giới hạn chính xác.
  • Charges are initiated on the scheduled date according to your subscription frequency.
  • The actual deduction from the customer’s account occurs only after 48 hours from payment initiation.
  • This 48-hour window may extend up to 2-3 additional hours depending on bank API responses.

  ​

  Mandate Cancellation Window

  During the 48-hour processing window:
  • Customers can cancel the mandate via their banking apps.
  • If a customer cancels the mandate during this period, the subscription will remain active (this is an edge case specific to Indian card and UPI AutoPay subscriptions).
  • However, the actual deduction may fail, and in that case, we will put the subscription on hold.
  Edge Case Handling: If you provide benefits, credits, or subscription usage to customers immediately upon charge initiation, you need to handle this 48-hour window appropriately in your application. Consider:
  • Delaying benefit activation until payment confirmation
  • Implementing grace periods or temporary access
  • Monitoring subscription status for mandate cancellations
  • Handling subscription hold states in your application logic
  Monitor subscription webhooks to track payment status changes and handle edge cases where mandates are cancelled during the 48-hour window.

​

Best Practices

• Start with clear tiers: 2–3 plans with obvious differences
• Communicate pricing: Show totals, proration, and next renewal
• Use trials thoughtfully: Convert with onboarding, not just time
• Leverage add‑ons: Keep base plans simple and upsell extras
• Test changes: Validate plan changes and proration in test mode

• Delay benefit activation until payment confirmation
• Implement grace periods or temporary access
• Monitor subscription status for mandate cancellations
• Handle subscription hold states in your application logic

​

Best Practices

• Start with clear tiers: 2-3 plans with obvious differences
• Communicate pricing: Show totals, proration, and next renewal date
• Use trials thoughtfully: Convert with onboarding, not just time
• Leverage add-ons: Keep base plans simple and upsell extras
• Test changes: Validate plan changes and proration in test mode