メインコンテンツへスキップ

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.

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: 1 }] },
  { 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: 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: 
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({
  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 には最低限2文字のISO国コードが必要です。 customer は { customer_id } （既存の顧客を添付するため）または { email, name? } （新しい顧客を作成するため）のユニオンです。 product_price は最小の通貨単位で表されます。

​
使用量に基づく請求

​
使用イベントの取り込み

使用量に基づく請求のためのカスタムイベントを追跡します： 
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'
      }
    }
  ]
});
イベントには一意の event_id 値が必要で、冪等性を確保します。同じリクエスト内の重複したIDは拒否され、既存のIDを持つ後続のリクエストは無視されます。

​
使用イベントの取得

使用イベントに関する詳細情報を取得します： 
// 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'
});

​
プロキシ設定

異なるランタイムのプロキシ設定を構成します：

​
Node.js（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,
  },
});

​
ロギング

環境変数やクライアントオプションを使用してログの冗長性を制御します： 
// Via client option
const client = new DodoPayments({
  logLevel: 'debug', // Show all log messages
});

# Via environment variable
export DODO_PAYMENTS_LOG=debug
利用可能なログレベル：
  • 'debug' - デバッグメッセージ、情報、警告、およびエラーを表示
  • 'info' - 情報メッセージ、警告、およびエラーを表示
  • 'warn' - 警告およびエラーを表示（デフォルト）
  • 'error' - エラーのみを表示
  • 'off' - すべてのログを無効化
デバッグレベルでは、すべてのHTTPリクエストとレスポンスがログに記録され、ヘッダーと本文を含みます。一部の認証ヘッダーは隠されますが、本文内の機密データはまだ見える可能性があります。

​
Node.js SDKからの移行

従来のNode.js SDKからのアップグレードの場合、TypeScript SDKは型の安全性と機能を改善しています：

View Migration Guide

Node.js SDKからTypeScript SDKへの移行方法を学ぶ

​
自動ページネーション

DodoPayments APIのリストメソッドはページネーションされています。すべてのページにわたってアイテムを繰り返し処理するには、 for await … of 構文を使用できます： 
async function fetchAllPayments() {
  const allPayments = [];
  // Automatically fetches more pages as needed.
  for await (const paymentListResponse of client.payments.list()) {
    allPayments.push(paymentListResponse);
  }
  return allPayments;
}
代わりに、一度に1ページのみをリクエストすることもできます： 
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();
  // ...
}

​
必要条件

次のランタイムがサポートされています：
  • Webブラウザ（最新のChrome、Firefox、Safari、Edgeなど）
  • Node.js 20 LTS以降の（非EOL）バージョン
  • Deno v1.28.0以降
  • Bun 1.0以降
  • Cloudflare Workers
  • Vercel Edge Runtime
  • Jest 28以上で "node" 環境
  • Nitro v2.6以上
TypeScript >= 4.9がサポートされています。

​
リソース

GitHub Repository

ソースコードを表示し、貢献する

API Reference

完全なAPIドキュメント

Discord Community

ヘルプを取得し、開発者とつながる

Report Issues

バグを報告するか、機能をリクエストする

​
サポート

TypeScript SDKに関するヘルプが必要ですか？

​
コントリビューション

貢献を歓迎します！コントリビューションガイドラインを確認して始めてください。
Last modified on May 14, 2026