Subscription Integration Guide
This guide will help you integrate the Dodo Payments Subscription Product into your website.
Prerequisites
To integrate the Dodo Payments API, you’ll need:
- A Dodo Payments merchant account
- API credentials (API key and webhook secret key) from the dashboard
If you don’t have an account yet, you can get your business approved by contacting the founder or by filling out this form.
For a more detailed guide on the prerequisites, check this section.
API Integration
Payment Links
Dodo Payments supports two types of payment links:
1. Static Payment Links
2. Dynamic Payment Links
Created via API call or our SDK with customer details. Here’s an example:
There are two APIs for creating dynamic payment links:
- Subscription Payment Link API - API reference
- One-time Payment Link API - API reference
The guide below focuses on subscription payment link creation.
For detailed instructions on integrating one-time products, refer to this One-time Integration Guide.
payment_link = true
to get payment link API Response
The following is an example of the response:
Redirect the customer to payment_link
.
Webhooks
When integrating subscriptions, you’ll receive webhooks to track the subscription lifecycle. These webhooks help you manage subscription states and payment scenarios effectively.
To set up your webhook endpoint, please follow our Detailed Integration Guide.
Subscription Event Types
The following webhook events track subscription status changes:
subscription.active
- Subscription is successfully activated.subscription.on_hold
- Subscription is put on hold due to failed renewal.subscription.failed
- Subscription creation failed during mandate creation.subscription.renewed
- Subscription is renewed for the next billing period.
For reliable subscription lifecycle management, we recommend tracking these subscription events.
Payment Scenarios
Successful Payment Flow
When a payment succeeds, you’ll receive the following webhooks:
subscription.active
- Indicates subscription activationpayment.succeeded
- Confirms the initial payment:- For immediate billing (0 trial days): Expect within 2-10 minutes
- For trial days: whenever that ends
subscription.renewed
- Indicates payment deduction and renewal for next cycle. (Basically, whenever payment gets deducted for subscription products, you will getsubscription.renewal
webhook along withpayment.succeeded
)
Payment Failure Scenarios
- Subscription Failure
subscription.failed
- Subscription creation failed due to failure to create a mandate.payment.failed
- Indicates failed payment.
Sample Subscription event payload
Property | Type | Required | Description |
---|---|---|---|
business_id | string | Yes | The unique identifier for the business |
timestamp | string | Yes | The timestamp of when the event occurred (not necessarily the same as when it was delivered) |
type | string | Yes | The type of event. See Event Types |
data | object | Yes | The main data payload. See Data Object |
Changing Subscription Plans
You can upgrade or downgrade a subscription plan using the change plan API endpoint. This allows you to modify the subscription’s product, quantity, and handle proration.
Change Plan API Reference
For detailed information about changing subscription plans, please refer to our Change Plan API documentation.
Proration Options
When changing subscription plans, you have two options for handling the immediate charge:
1. prorated_immediately
- Calculates the prorated amount based on the remaining time in the current billing cycle
- Charges the customer only for the difference between the old and new plan
- During a trial period, this will immediately switch the user to the new plan, charging the customer right away
2. full_immediately
- Charges the customer the full subscription amount for the new plan
- Ignores any remaining time or credits from the previous plan
- Useful when you want to reset the billing cycle or charge the full amount regardless of proration
Behavior
- When you invoke this API, Dodo Payments immediately initiates a charge based on your selected proration option
- If the plan change is a downgrade and you use
prorated_immediately
, credits will be automatically calculated and added to the subscription’s credit balance. These credits are specific to that subscription and will only be used to offset future recurring payments of the same subscription - The
full_immediately
option bypasses credit calculations and charges the complete new plan amount
Choose your proration option carefully: Use prorated_immediately
for fair billing that accounts for unused time, or full_immediately
when you want to charge the complete new plan amount regardless of the current billing cycle.
Charge Processing
- The immediate charge initiated upon plan change usually completes processing in less than 2 minutes
- If this immediate charge fails for any reason, the subscription is automatically placed on hold until the issue is resolved