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 activatedsubscription.on_hold
- Subscription is paused due to payment failuressubscription.failed
- Subscription creation failssubscription.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 in sequence:
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
Payment Failure Scenarios
- Subscription Failure
subscription.failed
- Subscription creation fails
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 |
Data Object
The data
object contains the following properties:
Property | Type | Required | Description |
---|---|---|---|
created_at | string | Yes | Creation timestamp |
currency | string | Yes | Three-letter currency code |
customer | object | Yes | Customer information |
metadata | object | Yes | Additional metadata |
next_billing_date | string | Yes | Next scheduled billing date |
payment_frequency_count | integer | Yes | Number of payment frequency units |
payment_frequency_interval | string | Yes | Payment frequency unit |
product_id | string | Yes | Unique product identifier |
quantity | integer | Yes | Quantity of the subscription |
recurring_pre_tax_amount | integer | Yes | Pre-tax amount for recurring payments |
status | string | Yes | Current subscription status |
subscription_id | string | Yes | Unique subscription identifier |
subscription_period_count | integer | Yes | Number of subscription period units |
subscription_period_interval | string | Yes | Subscription period unit |
trial_period_days | integer | Yes | Number of trial days |
payload_type | string | Yes | Type of payload (always “Subscription”) |
Enums
Time Intervals
Both payment_frequency_interval
and subscription_period_interval
accept the following values:
Day
Week
Month
Year
Status
The status
field can have the following values:
pending
- Initial stateactive
- Subscription is activeon_hold
- Temporarily on holdrenewed
- New Billing Cycle startedpaused
- Paused by user or systemcancelled
- Subscription has been cancelledfailed
- Payment or other failureexpired
- Subscription has expired
Event Types
Subscription Events
subscription.active
subscription.on_hold
subscription.paused
subscription.cancelled
subscription.failed
subscription.expired