subscription-integration_skill

Overview

This skill guides implementation of subscription billing with Dodo Payments, covering trials, upgrades/downgrades, metered usage, webhooks, and customer self-service. It provides concrete patterns for checkout session creation, webhook handling, plan changes, access control, and testing. Use it to wire recurring billing into your app and automate entitlement management.

How this skill works

Create subscription products in the Dodo dashboard and generate checkout sessions that optionally include trial periods or mandate creation for usage billing. Listen to subscription and payment webhooks to update your database, grant or revoke access, and send notifications. Support plan changes via the API (with proration options) and expose a customer portal for self-service management.

When to use it

• Launching recurring plans with trials or fixed billing intervals
• Implementing usage-based (on-demand) metered billing
• Automating access granting and revocation via webhooks
• Handling upgrades, downgrades, and proration in-app
• Providing a customer portal for billing self-service

Best practices

• Treat webhooks as the source of truth; upsert subscription records on events
• Keep access until end-of-period when cancel_at_next_billing_date is true
• Implement a grace period and retry logic for failed payments
• Map product IDs to entitlement sets and update user features on plan changes
• Test all lifecycle scenarios in dashboard test mode and with webhook triggers

Example use cases

• Create a checkout session that starts a 14-day trial and grant access on subscription.active
• Charge a metered subscription with subscriptions.charge when usage occurs and handle payment.succeeded/failed
• Update a subscription to a higher plan with proration_behavior:create_prorations to bill the difference
• Use middleware to block premium routes unless the subscription status is active and entitlements match
• Provide a portal session so customers can update payment methods, cancel, or view billing history