> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# TypeScript
> Integrate Dodo Payments into your TypeScript and Node.js applications with type safety and modern async/await support
The TypeScript SDK provides convenient server-side access to the Dodo Payments REST API for TypeScript and JavaScript applications. It features comprehensive type definitions, error handling, retries, timeouts, and auto-pagination for seamless payment processing.
## Installation
Install the SDK using your package manager of choice:
```bash npm theme={null}
npm install dodopayments
```
```bash yarn theme={null}
yarn add dodopayments
```
```bash pnpm theme={null}
pnpm add dodopayments
```
## Quick Start
Initialize the client with your API key and start processing payments:
```javascript theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
environment: 'test_mode', // defaults to 'live_mode'
});
const checkoutSessionResponse = await client.checkoutSessions.create({
product_cart: [{ product_id: 'product_id', quantity: 1 }],
});
console.log(checkoutSessionResponse.session_id);
```
Always store your API keys securely using environment variables. Never commit them to version control or expose them in client-side code.
## Core Features
Full TypeScript support with comprehensive type definitions for all API endpoints
Automatic pagination for list responses makes working with large datasets effortless
Built-in error types with detailed messages for different failure scenarios
Configurable automatic retries with exponential backoff for transient errors
## Configuration
### Environment Variables
Set environment variables for secure configuration:
```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```
### Timeout Configuration
Configure request timeouts globally or per-request:
```typescript theme={null}
// Configure default timeout for all requests (default is 1 minute)
const client = new DodoPayments({
timeout: 20 * 1000, // 20 seconds
});
// Override per-request
await client.checkoutSessions.create(
{ product_cart: [{ product_id: 'product_id', quantity: 1 }] },
{ timeout: 5 * 1000 },
);
```
### Retry Configuration
Configure automatic retry behavior:
```javascript theme={null}
// Configure default for all requests (default is 2 retries)
const client = new DodoPayments({
maxRetries: 0, // disable retries
});
// Override per-request
await client.checkoutSessions.create(
{ product_cart: [{ product_id: 'product_id', quantity: 1 }] },
{ maxRetries: 5 },
);
```
The SDK automatically retries requests that fail due to network errors or server issues (5xx responses) with exponential backoff.
## Common Operations
### Create a Checkout Session
Generate a checkout session for collecting payment information:
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: 'prod_123',
quantity: 1
}
],
return_url: 'https://yourdomain.com/return'
});
console.log('Redirect to:', session.checkout_url);
```
### Manage Customers
Create and retrieve customer information:
```typescript theme={null}
// Create a customer
const customer = await client.customers.create({
email: 'customer@example.com',
name: 'John Doe',
metadata: {
user_id: '12345'
}
});
// Retrieve customer
const retrieved = await client.customers.retrieve('cus_123');
console.log(`Customer: ${retrieved.name} (${retrieved.email})`);
```
### Handle Subscriptions
Create and manage recurring subscriptions:
```typescript theme={null}
// Create a subscription
const subscription = await client.subscriptions.create({
billing: {
country: 'US',
city: 'San Francisco',
state: 'CA',
street: '1 Market St',
zipcode: '94105',
},
customer: {
customer_id: 'cus_123', // or pass { email, name } to create a new customer
},
product_id: 'pdt_456',
quantity: 1,
});
// Charge an on-demand subscription
// product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
const chargeResponse = await client.subscriptions.charge(subscription.subscription_id, {
product_price: 2500,
});
// Retrieve subscription usage history (for metered subscriptions)
const usageHistory = await client.subscriptions.retrieveUsageHistory(subscription.subscription_id, {
start_date: '2024-01-01T00:00:00Z',
end_date: '2024-03-31T23:59:59Z',
});
```
`billing` requires at minimum the two-letter ISO country code. `customer` is a union of `{ customer_id }` (to attach an existing customer) or `{ email, name? }` (to create a new one). `product_price` is expressed in the lowest currency denomination.
## Usage-Based Billing
### Ingest Usage Events
Track custom events for usage-based billing:
```typescript theme={null}
await client.usageEvents.ingest({
events: [
{
event_id: 'api_call_12345',
customer_id: 'cus_abc123',
event_name: 'api_request',
timestamp: '2024-01-15T10:30:00Z',
metadata: {
endpoint: '/api/v1/users',
method: 'GET',
tokens_used: '150'
}
}
]
});
```
Events must have unique `event_id` values for idempotency. Duplicate IDs within the same request are rejected, and subsequent requests with existing IDs are ignored.
### Retrieve Usage Events
Fetch detailed information about usage events:
```typescript theme={null}
// Get a specific event
const event = await client.usageEvents.retrieve('api_call_12345');
// List events with filtering
const events = await client.usageEvents.list({
customer_id: 'cus_abc123',
event_name: 'api_request',
start: '2024-01-14T10:30:00Z',
end: '2024-01-15T10:30:00Z'
});
```
## Proxy Configuration
Configure proxy settings for different runtimes:
### Node.js (using undici)
```typescript theme={null}
import DodoPayments from 'dodopayments';
import * as undici from 'undici';
const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new DodoPayments({
fetchOptions: {
dispatcher: proxyAgent,
},
});
```
### Bun
```typescript theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
fetchOptions: {
proxy: 'http://localhost:8888',
},
});
```
### Deno
```typescript theme={null}
import DodoPayments from 'npm:dodopayments';
const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new DodoPayments({
fetchOptions: {
client: httpClient,
},
});
```
## Logging
Control log verbosity using environment variables or client options:
```typescript theme={null}
// Via client option
const client = new DodoPayments({
logLevel: 'debug', // Show all log messages
});
```
```bash theme={null}
# Via environment variable
export DODO_PAYMENTS_LOG=debug
```
**Available log levels:**
* `'debug'` - Show debug messages, info, warnings, and errors
* `'info'` - Show info messages, warnings, and errors
* `'warn'` - Show warnings and errors (default)
* `'error'` - Show only errors
* `'off'` - Disable all logging
At the debug level, all HTTP requests and responses are logged, including headers and bodies. Some authentication headers are redacted, but sensitive data in bodies may still be visible.
## Migration from Node.js SDK
If you're upgrading from the legacy Node.js SDK, the TypeScript SDK offers improved type safety and features:
Learn how to migrate from the Node.js SDK to the TypeScript SDK
## Auto-Pagination
List methods in the DodoPayments API are paginated. You can use the `for await … of` syntax to iterate through items across all pages:
```typescript theme={null}
async function fetchAllPayments() {
const allPayments = [];
// Automatically fetches more pages as needed.
for await (const paymentListResponse of client.payments.list()) {
allPayments.push(paymentListResponse);
}
return allPayments;
}
```
Alternatively, you can request a single page at a time:
```typescript theme={null}
let page = await client.payments.list();
for (const paymentListResponse of page.items) {
console.log(paymentListResponse);
}
// Convenience methods are provided for manually paginating:
while (page.hasNextPage()) {
page = await page.getNextPage();
// ...
}
```
## Requirements
The following runtimes are supported:
* Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
* Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions
* Deno v1.28.0 or higher
* Bun 1.0 or later
* Cloudflare Workers
* Vercel Edge Runtime
* Jest 28 or greater with the `"node"` environment
* Nitro v2.6 or greater
TypeScript >= 4.9 is supported.
## Resources
View source code and contribute
Complete API documentation
Get help and connect with developers
Report bugs or request features
## Support
Need help with the TypeScript SDK?
* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-typescript)
## Contributing
We welcome contributions! Check the [contributing guidelines](https://github.com/dodopayments/dodopayments-typescript/blob/main/CONTRIBUTING.md) to get started.