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

# Sync with your Database

> Automatically sync your Dodo Payments data to your own database for analytics, reporting, and integrations.

Dodo Payments provides a built-in database sync feature that automatically synchronizes your payment data with your own database. You can sync **payments**, **customers**, **subscriptions**, and **licenses** to maintain a local copy of your data for analytics, reporting, or integration with other systems.

<Info>
  **Implementation**: Available via [npm package](https://www.npmjs.com/package/dodo-sync) | **Source Code**: [GitHub](https://github.com/dodopayments/dodo-sync)
</Info>

## What Can You Sync?

Our database sync feature supports synchronizing the following Dodo Payments entities to your database:

<CardGroup cols={2}>
  <Card title="Payments" icon="credit-card">
    Sync all payment transactions, including one-time payments, refunds, and payment status updates.
  </Card>

  <Card title="Customers" icon="users">
    Keep your customer data in sync, including customer profiles, contact information, and metadata.
  </Card>

  <Card title="Subscriptions" icon="repeat">
    Synchronize subscription data, including active subscriptions, billing cycles, and subscription status changes.
  </Card>

  <Card title="Licenses" icon="key">
    Sync license information, including license keys, activations, and license status updates.
  </Card>
</CardGroup>

You can sync any combination of these entities by specifying them in the `scopes` parameter. All sync operations are incremental and only transfer new or updated records for optimal performance.

## Database Support

We currently support **MongoDB**, **PostgreSQL**, **MySQL**, and **ClickHouse**.

We are actively working on expanding support for:

* **Databases**: Snowflake and others.
* **Pipelines**: ETL pipelines, Realtime sync.

<Tip>
  We're continuously expanding database support. If you'd like to contribute a new database integration, please submit a Pull Request to our [GitHub repository](https://github.com/dodopayments/dodo-sync).
</Tip>

## Getting Started

You can use our database sync feature via the **CLI** or programmatically in your **code**. Both methods provide the same functionality—choose the one that best fits your workflow.

### Using the CLI

The CLI tool provides a quick way to set up and run database synchronization. Install it globally to use it from anywhere in your terminal:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g dodo-sync
  ```

  ```bash bun theme={null}
  bun add -g dodo-sync
  ```
</CodeGroup>

#### Running the CLI

The CLI supports two modes: **Interactive Mode** for guided setup, and **Manual Mode** for direct configuration.

**Interactive Mode**: Simply run the command without arguments to start the interactive setup wizard.

```bash theme={null}
dodo-sync
```

**Manual Mode**: Pass arguments directly to skip the wizard.

```bash theme={null}
dodo-sync -i [interval] -d [database] -u [database_uri] --scopes [scopes] --api-key [api_key] --env [environment]
```

**Examples:**

```bash theme={null}
# MongoDB
dodo-sync -i 600 -d mongodb -u mongodb://mymongodb.url --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# PostgreSQL
dodo-sync -i 600 -d postgres -u postgresql://user:password@localhost:5432/mydb --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# MySQL
dodo-sync -i 600 -d mysql -u mysql://user:password@localhost:3306/mydb --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# ClickHouse
dodo-sync -i 600 -d clickhouse -u http://localhost:8123 --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode
```

#### CLI Arguments

<ParamField path="--interval" type="number" alias="-i">
  Sync interval in seconds. Determines how frequently the sync operation runs. If not provided, the sync will run once and exit.
</ParamField>

<ParamField path="--database" type="string" alias="-d" required>
  Database type to use. Supported values: `"mongodb"`, `"postgres"`, `"mysql"`, or `"clickhouse"`.
</ParamField>

<ParamField path="--database-uri" type="string" alias="-u" required>
  Connection URI for your database:

  * **MongoDB**: `mongodb://localhost:27017` or `mongodb+srv://user:pass@cluster.mongodb.net/`
  * **PostgreSQL**: `postgresql://user:password@localhost:5432/mydb`
  * **MySQL**: `mysql://user:password@localhost:3306/mydb`
  * **ClickHouse**: `http://localhost:8123`
</ParamField>

<ParamField path="--scopes" type="string" required>
  Comma-separated list of data entities to sync. Available scopes: `licences`, `payments`, `customers`, `subscriptions`. Example: `"payments,customers"`.
</ParamField>

<ParamField path="--api-key" type="string" required>
  Your Dodo Payments API key. Should start with `dp_live_` for live mode or `dp_test_` for test mode.
</ParamField>

<ParamField path="--env" type="string" required>
  Environment target. Must be either `"live_mode"` or `"test_mode"`. This determines which Dodo Payments environment to sync from.
</ParamField>

<ParamField path="--rate-limit" type="number" alias="--rl">
  Rate limit in requests per second. Controls how fast the sync engine makes API requests to avoid overwhelming the Dodo Payments API.
</ParamField>

### Using in Your Code

For programmatic control, integrate the sync feature directly into your application. Install it as a dependency in your project:

<CodeGroup>
  ```bash npm theme={null}
  npm install dodo-sync
  ```

  ```bash bun theme={null}
  bun add dodo-sync
  ```
</CodeGroup>

#### Automatic Sync (Interval-based)

Use automatic sync when you want the sync to run continuously at regular intervals:

```typescript theme={null}
import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60, // Sync every 60 seconds
  database: 'mongodb',
  databaseURI: process.env.MONGODB_URI, // e.g., 'mongodb://localhost:27017'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode' // or 'live_mode'
  }
});

// Initialize connection
await syncDodoPayments.init();

// Start the sync loop
syncDodoPayments.start();
```

<Tip>
  The `interval` option is required when using `.start()` for automatic syncing. The sync will run continuously at the specified interval until the process is stopped.
</Tip>

#### Manual Sync

Use manual sync when you want to trigger sync operations on-demand (e.g., from a cron job or API endpoint):

```typescript theme={null}
import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  database: 'mongodb',
  databaseURI: process.env.MONGODB_URI,
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

// Initialize connection
await syncDodoPayments.init();

// Trigger a single sync operation
await syncDodoPayments.run();
```

<Tip>
  When using manual sync, the `interval` option is not required. You can call `.run()` whenever you need to perform a sync operation.
</Tip>

#### PostgreSQL Example

Here's how to use `dodo-sync` with PostgreSQL:

```typescript theme={null}
import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'postgres',
  databaseURI: process.env.POSTGRES_URI, // e.g., 'postgresql://user:password@localhost:5432/mydb'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();
```

#### MySQL Example

Here's how to use `dodo-sync` with MySQL:

```typescript theme={null}
import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'mysql',
  databaseURI: process.env.MYSQL_URI, // e.g., 'mysql://user:password@localhost:3306/mydb'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();
```

#### ClickHouse Example

Here's how to use `dodo-sync` with ClickHouse:

```typescript theme={null}
import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'clickhouse',
  databaseURI: process.env.CLICKHOUSE_URI, // e.g., 'http://localhost:8123'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();
```

#### Constructor Options

<ParamField body="database" type="string" required>
  Name of the database to use. Supported values: `"mongodb"`, `"postgres"`, `"mysql"`, or `"clickhouse"`.
</ParamField>

<ParamField body="databaseURI" type="string" required>
  Connection string for your database:

  * **MongoDB**: `mongodb://localhost:27017` or `mongodb+srv://...`
  * **PostgreSQL**: `postgresql://user:password@localhost:5432/mydb`
  * **MySQL**: `mysql://user:password@localhost:3306/mydb`
  * **ClickHouse**: `http://localhost:8123`
</ParamField>

<ParamField body="scopes" type="string[]" required>
  Array of entities to sync. Available options: `"licences"`, `"payments"`, `"customers"`, `"subscriptions"`. You can include any combination of these.
</ParamField>

<ParamField body="dodoPaymentsOptions" type="object" required>
  Dodo Payments API configuration for authentication and environment selection. See the [TypeScript SDK types](https://github.com/dodopayments/dodopayments-typescript/blob/main/src/client.ts) for complete options.

  **Required properties:**

  * `bearerToken`: Your Dodo Payments API key
  * `environment`: Either `"test_mode"` or `"live_mode"`
</ParamField>

<ParamField body="interval" type="number">
  Time in seconds between automatic syncs. Required when using `.start()` for automatic syncing. Optional when using `.run()` for manual syncing.
</ParamField>

<ParamField body="rateLimit" type="number">
  Number of requests per second. Controls how fast the sync engine makes API requests to avoid overwhelming the Dodo Payments API.
</ParamField>

## Important Information

<Warning>
  **MongoDB**: A database named `dodopayments_sync` will be automatically created on your database server. All sync data will be stored there. This database name is currently fixed and cannot be changed.

  **PostgreSQL**: Tables (`Subscriptions`, `Payments`, `Licenses`, `Customers`) will be created in the database specified in your connection URI. Data is stored as JSONB.

  **MySQL**: Tables (`Subscriptions`, `Payments`, `Licenses`, `Customers`) will be created in the database specified in your connection URI. Data is stored as JSON.

  **ClickHouse**: Tables (`Subscriptions`, `Payments`, `Licenses`, `Customers`) will be created using the ReplacingMergeTree engine. When querying, use the `FINAL` keyword to ensure deduplicated results.
</Warning>

<Info>
  The sync engine tracks changes and only syncs new or updated records, making subsequent syncs efficient even with large datasets.
</Info>

## Additional Resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodo-sync">
    View source code, report issues, or contribute improvements
  </Card>

  <Card title="npm Package" icon="box-open" href="https://www.npmjs.com/package/dodo-sync">
    View package details and installation instructions
  </Card>
</CardGroup>