OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add dodopayments/skills --skill subscription-integration
Guide for managing recurring subscriptions after checkout, including trials, lifecycle states, plan changes, cancellation, failed-payment recovery, proration, mandates, and on-demand charges.
npx skills add dodopayments/skills --skill subscription-integration
Implement recurring billing with trials, plan changes, and on-demand charging. Subscriptions are created through Checkout Sessions, managed via the subscriptions API, and monitored through webhooks.
Subscription lifecycle: The six subscription statuses are pending, active, on_hold, cancelled, failed, and expired. A trialing subscription reports active; subscription.renewed is an event, not a status. Failed payments can move a subscription to on_hold (recoverable) or failed (terminal). Cancellation sets it to cancelled or schedules it to become expired at period end.
Checkout Sessions: The recommended path for creating subscriptions. A single-use hosted checkout that collects payment and customer data, then creates the subscription server-side.
Proration: When a customer changes plans mid-cycle, Dodo calculates credits or charges based on the time remaining. Proration mode controls whether the customer is billed immediately, credited, or neither.
Mandates: Authorization to charge a customer's payment method repeatedly (for subscriptions) or on-demand (for usage-based billing). Created during Checkout, can be updated if payment fails.
The customer completes payment on the hosted checkout. On success, Dodo creates the subscription and fires the subscription.active webhook.
| Status | Meaning | Transitions |
|---|---|---|
pending | Creation in progress | → active, failed |
active | Actively renewing | → on_hold, cancelled, expired |
on_hold | Renewal/plan-change payment failed; recoverable | → active (payment method updated), failed (retries exhausted), cancelled |
cancelled | Will not renew | → expired (at period end) |
failed | Initial mandate/payment failed; terminal | (no recovery) |
expired | Subscription term ended | (terminal) |
Trial period: If trial_period_days is set, the subscription enters active immediately but charges nothing until the trial ends. The first charge occurs on the trial end date.
When a subscription is on_hold due to failed payment, the customer can update their payment method. This automatically charges any outstanding dues.
Success emits payment.succeeded followed by subscription.active.
Proration modes:
| Mode | Upgrade | Downgrade | Billing date |
|---|---|---|---|
prorated_immediately | Time-prorated charge | Time-prorated credit | Resets to change date |
difference_immediately | Full new-plan charge | Difference becomes credit | Resets |
full_immediately | Full new-plan charge | Full new-plan charge, no credit | Resets |
do_not_bill | No charge | No credit | Preserved |
Payment failure handling:
prevent_change: Keep the old plan if the charge fails.apply_change: Apply the new plan even if payment fails (subscription may become on_hold).Show the customer a quote before committing:
Access is revoked immediately.
The subscription remains active until the next billing date, then transitions to expired. The subscription.cancelled webhook includes cancel_at_next_billing_date: true and next_billing_date so you know when to revoke access.
For usage-based or metered subscriptions, charge the customer on-demand without a scheduled renewal.
This creates a subscription with a mandate but no automatic renewal. You control when to charge.
Amounts are in the smallest currency unit (cents for USD, paise for INR, etc.).
Dodo does not automatically retry on-demand charges. You own retry logic and decline filtering. Monitor payment.failed webhooks and implement your own retry strategy.
When a renewal or plan-change charge fails, the subscription moves to on_hold. This is recoverable.
Payment Retries: Opt-in under Settings → Recovery. Dodo retries failed renewals up to 8 times over a configurable 1–30 day window (default 13 days). Only for soft declines.
Customer Portal: Customer updates payment method → automatic charge for outstanding dues → subscription.active.
Manual Charge: You update the payment method server-side, then call updatePaymentMethod().
Dunning sends up to four configurable emails for on_hold renewals and customer-portal cancellations. Exhausted dunning does not change the subscription state; you must handle the final outcome.
Allow customers to self-serve: view subscriptions, update payment methods, cancel, and upgrade/downgrade.
Portal links expire after 24 hours. Customers can:
on_hold subscriptionsFor full customer management (creating, updating, listing), see the customer-management skill.
| Event | When | Action |
|---|---|---|
subscription.active | Subscription becomes active, including a trial start or recovery | Grant access |
subscription.renewed | Successful renewal | Log renewal, send receipt |
subscription.on_hold | Renewal/plan-change payment failed | Notify customer, offer recovery |
subscription.plan_changed | Plan upgraded/downgraded or add-ons changed | Update entitlements |
subscription.cancelled | Customer cancels | Schedule access revocation per cancel_at_next_billing_date |
subscription.failed | Initial mandate/payment failed | Notify customer, offer retry or new subscription |
subscription.expired | Subscription term ended | Revoke access |
Webhook signature verification, raw-body handling, durable processing, and idempotency are covered in the webhook-integration skill.
Attach credit entitlements to subscription products to grant credits each billing cycle. For full credit management, see the credit-based-billing skill.
Quick example:
On each renewal, credits are issued. Monitor credit.added and credit.deducted webhooks to sync your ledger.
return_url Instead of WebhookWrong:
The return_url is hit before the subscription is fully created. Dodo may still be processing the mandate or payment. Always wait for subscription.active webhook.
Right:
subscriptions.createWrong:
This endpoint is deprecated. Use Checkout Sessions.
Right:
subscription.plan_changedsubscription.plan_changed fires for upgrades, downgrades, add-on changes, AND when cancel_at_next_billing_date is toggled. Don't assume every plan_changed event means a paid upgrade succeeded. Inspect the payload and check the subscription's current product_id.
Wrong:
This will fail. Always specify a proration mode.
on_hold with Pauseon_hold means payment failed, not that the customer paused. There is no general pause/resume operation. on_hold is recoverable only by updating the payment method or waiting for retry.
cancel_at_next_billing_dateconst session = await client.checkoutSessions.create({
product_cart: [
{
product_id: 'pdt_pro_monthly',
quantity: 1,
addons: [
{ addon_id: 'adn_extra_seats', quantity: 3 }
]
}
],
subscription_data: {
trial_period_days: 7,
},
customer: { email: 'user@example.com' },
return_url: 'https://yoursite.com/success',
});const subscription = await client.subscriptions.retrieve('sub_xxxxx');
console.log(subscription.status, subscription.next_billing_date);await client.subscriptions.updatePaymentMethod('sub_xxxxx', {
payment_method: {
type: 'existing',
payment_method_id: 'pm_new_method',
},
});const history = await client.subscriptions.retrieveUsageHistory('sub_xxxxx', {
page_size: 50,
page_number: 0,
});const creditUsage = await client.subscriptions.retrieveCreditUsage('sub_xxxxx');
console.log('Subscription:', creditUsage.subscription_id);
for (const item of creditUsage.items) {
console.log(item.credit_entitlement_name, item.balance); // balance is a string
}await client.subscriptions.changePlan('sub_xxxxx', {
product_id: 'pdt_higher_tier',
quantity: 1,
proration_billing_mode: 'prorated_immediately',
on_payment_failure: 'prevent_change',
});const preview = await client.subscriptions.previewChangePlan('sub_xxxxx', {
product_id: 'pdt_new_plan',
quantity: 1,
proration_billing_mode: 'prorated_immediately',
});
console.log('Effective at:', preview.immediate_charge.effective_at);
console.log('Line items:', preview.immediate_charge.line_items);
console.log('Summary:', preview.immediate_charge.summary);
console.log('New plan:', preview.new_plan);await client.subscriptions.cancelChangePlan('sub_xxxxx');await client.subscriptions.update('sub_xxxxx', {
status: 'cancelled',
});await client.subscriptions.update('sub_xxxxx', {
cancel_at_next_billing_date: true,
});const session = await client.checkoutSessions.create({
product_cart: [
{ product_id: 'pdt_usage_based', quantity: 1 }
],
subscription_data: {
on_demand: {
mandate_only: true,
}
},
customer: { email: 'user@example.com' },
return_url: 'https://yoursite.com/success',
});const charge = await client.subscriptions.charge('sub_xxxxx', {
product_price: 2500, // $25.00 in cents
product_currency: 'USD',
product_description: 'API calls for January 2025',
});
console.log('Payment ID:', charge.payment_id);// Listen for subscription.on_hold webhook
case 'subscription.on_hold':
// Notify customer, offer payment method update
await sendPaymentFailedEmail(data.customer.customer_id);
break;const portalSession = await client.customers.customerPortal.create(
'cus_xxxxx',
{ return_url: 'https://yoursite.com/account' }
);
// Redirect to portalSession.linkimport { NextRequest, NextResponse } from 'next/server';
export async function POST(req: NextRequest) {
const raw = await req.text();
const headers = Object.fromEntries(req.headers.entries());
const event = await client.webhooks.unwrap(raw, { headers });
const webhookId = req.headers.get('webhook-id');
if (!webhookId) {
return NextResponse.json({ error: 'Missing webhook-id' }, { status: 400 });
}
// Implement this as an atomic insert backed by a UNIQUE constraint.
// Keep the claim and entitlement changes in the same database transaction.
const claimed = await claimWebhookId(webhookId);
if (!claimed) {
return NextResponse.json({ received: true });
}
switch (event.type) {
case 'subscription.active':
await grantAccess(event.data.customer.customer_id, event.data.product_id);
break;
case 'subscription.on_hold':
await notifyPaymentFailed(event.data.customer.customer_id);
break;
case 'subscription.cancelled':
if (event.data.cancel_at_next_billing_date) {
await scheduleAccessRevocation(event.data.subscription_id, new Date(event.data.next_billing_date));
} else {
await revokeAccessImmediately(event.data.subscription_id);
}
break;
case 'subscription.expired':
await revokeAccess(event.data.customer.customer_id);
break;
}
return NextResponse.json({ received: true });
}// Product has credit entitlement attached (e.g., 10,000 tokens/month)
const session = await client.checkoutSessions.create({
product_cart: [
{ product_id: 'pdt_pro_with_credits', quantity: 1 }
],
subscription_data: {
trial_period_days: 14,
},
customer: { email: 'user@example.com' },
return_url: 'https://yoursite.com/success',
});// On return_url redirect
await grantAccess(user.id);// In webhook handler
case 'subscription.active':
await grantAccess(data.customer.customer_id);
break;const sub = await client.subscriptions.create({
product_id: 'pdt_monthly',
customer_id: 'cus_xxxxx',
});const session = await client.checkoutSessions.create({
product_cart: [{ product_id: 'pdt_monthly', quantity: 1 }],
customer: { customer_id: 'cus_xxxxx' },
return_url: 'https://yoursite.com/success',
});// Missing proration_billing_mode
await client.subscriptions.changePlan('sub_xxxxx', {
product_id: 'pdt_new',
quantity: 1,
// proration_billing_mode: 'prorated_immediately', // REQUIRED
});// Wrong: revoke immediately
await revokeAccess(data.customer.customer_id);
// Right: check the flag
if (data.cancel_at_next_billing_date) {
await scheduleAccessRevocation(data.subscription_id, new Date(data.next_billing_date));
} else {
await revokeAccessImmediately(data.subscription_id);
}