Sync with Your Database

Sync your Dodo Payments data to your own database for analytics, reporting, and integrations. The sync engine automatically replicates payments, customers, subscriptions, and licenses to MongoDB, PostgreSQL, MySQL, or ClickHouse.

Package: dodo-sync on npm | Source: GitHub

What Can You Sync?

Choose any combination of these entities:

Payments

All payment transactions, including one-time payments, refunds, and status updates.

Customers

Customer profiles, contact information, and metadata.

Subscriptions

Subscription data, billing cycles, and status changes.

Licenses

License keys, activations, and status updates.

Specify which entities to sync using the scopes parameter. Each run fetches every record in the selected scopes and writes it by ID, so existing rows are updated in place instead of duplicated. In MongoDB, license keys are stored by subscription ID, so a subscription with several license keys keeps only one of them.

Database Support

Dodo Sync supports MongoDB, PostgreSQL, MySQL, and ClickHouse. Support for Snowflake and other databases, ETL pipelines, and realtime sync is in development. To contribute a new database integration, submit a pull request to the GitHub repository.

Getting Started

Use Dodo Sync via the CLI for quick setup or programmatically in your code for integration into your application. Both methods provide the same functionality.

Using the CLI

Install the CLI globally to run it from anywhere:

npm install -g dodo-sync

bun add -g dodo-sync

Running the CLI

The CLI supports two modes: interactive for guided setup, and manual for direct configuration. Interactive mode: Run without arguments to start the setup wizard.

dodo-sync

Manual mode: Pass arguments directly to skip the wizard.

dodo-sync -i [interval] -d [database] -u [database_uri] --scopes [scopes] --api-key [api_key] --env [environment]

Examples:

# 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

number

required

Sync interval in seconds. The CLI runs continuously at this interval. For a one-time sync, use .run() in your code.

string

required

Database type: "mongodb", "postgres", "mysql", or "clickhouse".

string

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

string

required

Comma-separated list of entities to sync: licences, payments, customers, subscriptions. Example: "payments,customers".

string

required

Your Dodo Payments API key from Developer → API Keys. Use a key from the same mode as --env.

string

required

Environment: "live_mode" or "test_mode".

number

Rate limit in requests per second. Controls how fast the sync engine makes API requests. Defaults to 10; values of 100 or more turn off throttling.

Using in Your Code

Integrate the sync feature directly into your application. Install it as a dependency:

npm install dodo-sync

bun add dodo-sync

Automatic Sync (Interval-based)

Run the sync continuously at regular intervals:

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();

The interval option is required when using .start(). The sync runs continuously at the specified interval until the process stops.

Manual Sync

Trigger sync operations on-demand, such as from a cron job or API endpoint:

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();

The interval option is not required for manual sync. Call .run() whenever you need to sync.

PostgreSQL Example

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

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

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

string

required

Database type: "mongodb", "postgres", "mysql", or "clickhouse".

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

string[]

required

Array of entities to sync: "licences", "payments", "customers", "subscriptions". Include any combination.

object

required

Dodo Payments API configuration. See the TypeScript SDK types for complete options.Required properties:

bearerToken: Your Dodo Payments API key
environment: "test_mode" or "live_mode"

number

Time in seconds between automatic syncs. Required for .start(), optional for .run().

number

Rate limit in requests per second. Defaults to 10; values of 100 or more turn off throttling.

Important Information

MongoDB: A database named dodopayments_sync is automatically created on your server. This database name is fixed and cannot be changed.PostgreSQL: Tables (Subscriptions, Payments, Licenses, Customers) are created in the database specified in your connection URI. Data is stored as JSONB.MySQL: Tables (Subscriptions, Payments, Licenses, Customers) are created in the database specified in your connection URI. Data is stored as JSON.ClickHouse: Tables (Subscriptions, Payments, Licenses, Customers) are created using the ReplacingMergeTree engine. When querying, use the FINAL keyword to ensure deduplicated results.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

What Can You Sync?

Payments

Customers

Subscriptions

Licenses

Database Support

Getting Started

Using the CLI

Running the CLI

CLI Arguments

Using in Your Code

Automatic Sync (Interval-based)

Manual Sync

PostgreSQL Example

MySQL Example

ClickHouse Example

Constructor Options

Important Information

Additional Resources

GitHub Repository

npm Package

​What Can You Sync?

Payments

Customers

Subscriptions

Licenses

​Database Support

​Getting Started

​Using the CLI

​Running the CLI

​CLI Arguments

​Using in Your Code

​Automatic Sync (Interval-based)

​Manual Sync

​PostgreSQL Example

​MySQL Example

​ClickHouse Example

​Constructor Options

​Important Information

​Additional Resources

GitHub Repository

npm Package

What Can You Sync?

Database Support

Getting Started

Using the CLI

Running the CLI

CLI Arguments

Using in Your Code

Automatic Sync (Interval-based)

Manual Sync

PostgreSQL Example

MySQL Example

ClickHouse Example

Constructor Options

Important Information

Additional Resources