Skip to main content
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: 
npm install dodopayments

​
Quick Start

Initialize the client with your API key and start processing payments: 
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

TypeScript First

Full TypeScript support with comprehensive type definitions for all API endpoints

Auto-Pagination

Automatic pagination for list responses makes working with large datasets effortless

Error Handling

Built-in error types with detailed messages for different failure scenarios

Smart Retries

Configurable automatic retries with exponential backoff for transient errors

​
Configuration

​
Environment Variables

Set environment variables for secure configuration:
.env
DODO_PAYMENTS_API_KEY=your_api_key_here

​
Timeout Configuration

Configure request timeouts globally or per-request: 
// 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: 0 }] },
  { timeout: 5 * 1000 }
);

​
Retry Configuration

Configure automatic retry behavior: 
// 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: 0 }] },
  { 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: 
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.url);

​
Manage Customers

Create and retrieve customer information: 
// 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: 
// Create a subscription
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_456',
  price_id: 'price_789'
});

// Retrieve subscription usage history
const usageHistory = await client.subscriptions.retrieveUsageHistory('sub_123', {
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-03-31T23:59:59Z'
});

​
Usage-Based Billing

​
Ingest Usage Events

Track custom events for usage-based billing: 
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: 
// 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)

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

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});

​
Deno

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: 
// Via client option
const client = new DodoPayments({
  logLevel: 'debug', // Show all log messages
});

# 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:

View Migration Guide

Learn how to migrate from the Node.js SDK to the TypeScript SDK

​
Resources

GitHub Repository

View source code and contribute

API Reference

Complete API documentation

Discord Community

Get help and connect with developers

Report Issues

Report bugs or request features

​
Support

Need help with the TypeScript SDK?

​
Contributing

We welcome contributions! Check the contributing guidelines to get started.