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

<CodeGroup>
  ```bash npm theme={null}
  npm install dodopayments
  ```

  ```bash yarn theme={null}
  yarn add dodopayments
  ```

  ```bash pnpm theme={null}
  pnpm add dodopayments
  ```
</CodeGroup>

## 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);
```

<Warning>
  Always store your API keys securely using environment variables. Never commit them to version control or expose them in client-side code.
</Warning>

## Core Features

<CardGroup cols={2}>
  <Card title="TypeScript First" icon="shield-check">
    Full TypeScript support with comprehensive type definitions for all API endpoints
  </Card>

  <Card title="Auto-Pagination" icon="arrows-rotate">
    Automatic pagination for list responses makes working with large datasets effortless
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation">
    Built-in error types with detailed messages for different failure scenarios
  </Card>

  <Card title="Smart Retries" icon="repeat">
    Configurable automatic retries with exponential backoff for transient errors
  </Card>
</CardGroup>

## 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 },
);
```

<Tip>
  The SDK automatically retries requests that fail due to network errors or server issues (5xx responses) with exponential backoff.
</Tip>

## 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',
});
```

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

## 使用量に基づく請求

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

使用量に基づく請求のためのカスタムイベントを追跡します：

```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'
      }
    }
  ]
});
```

<Info>
  イベントには一意の `event_id` 値が必要で、冪等性を確保します。同じリクエスト内の重複したIDは拒否され、既存のIDを持つ後続のリクエストは無視されます。
</Info>

### 使用イベントの取得

使用イベントに関する詳細情報を取得します：

```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'
});
```

## プロキシ設定

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

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

## ロギング

環境変数やクライアントオプションを使用してログの冗長性を制御します：

```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
```

**利用可能なログレベル：**

* `'debug'` - デバッグメッセージ、情報、警告、およびエラーを表示
* `'info'` - 情報メッセージ、警告、およびエラーを表示
* `'warn'` - 警告およびエラーを表示（デフォルト）
* `'error'` - エラーのみを表示
* `'off'` - すべてのログを無効化

<Warning>
  デバッグレベルでは、すべてのHTTPリクエストとレスポンスがログに記録され、ヘッダーと本文を含みます。一部の認証ヘッダーは隠されますが、本文内の機密データはまだ見える可能性があります。
</Warning>

## Node.js SDKからの移行

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

<Card title="View Migration Guide" icon="arrow-right" href="https://github.com/dodopayments/dodopayments-typescript/blob/main/MIGRATION.md">
  Node.js SDKからTypeScript SDKへの移行方法を学ぶ
</Card>

## 自動ページネーション

DodoPayments APIのリストメソッドはページネーションされています。すべてのページにわたってアイテムを繰り返し処理するには、 `for await … of` 構文を使用できます：

```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;
}
```

代わりに、一度に1ページのみをリクエストすることもできます：

```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();
  // ...
}
```

## 必要条件

次のランタイムがサポートされています：

* Webブラウザ（最新のChrome、Firefox、Safari、Edgeなど）
* Node.js 20 LTS以降の（[非EOL](https://endoflife.date/nodejs)）バージョン
* Deno v1.28.0以降
* Bun 1.0以降
* Cloudflare Workers
* Vercel Edge Runtime
* Jest 28以上で `"node"` 環境
* Nitro v2.6以上

TypeScript >= 4.9がサポートされています。

## リソース

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-typescript">
    ソースコードを表示し、貢献する
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    完全なAPIドキュメント
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    ヘルプを取得し、開発者とつながる
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-typescript/issues">
    バグを報告するか、機能をリクエストする
  </Card>
</CardGroup>

## サポート

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

* **Discord**: [コミュニティサーバー](https://discord.gg/bYqAp4ayYh)に参加してリアルタイムのサポートを受ける
* **Email**: [support@dodopayments.com](mailto:support@dodopayments.com)  に連絡してください
* **GitHub**: [リポジトリ](https://github.com/dodopayments/dodopayments-typescript)で問題を開く

## コントリビューション

貢献を歓迎します！[コントリビューションガイドライン](https://github.com/dodopayments/dodopayments-typescript/blob/main/CONTRIBUTING.md)を確認して始めてください。