Stripe Sync Engine


A TypeScript library to synchronize Stripe data into a PostgreSQL database, designed for use in Node.js backends and serverless environments.

Features

- Sync Stripe objects (customers, invoices, products, etc.) to your PostgreSQL database.
- Handles Stripe webhooks for real-time updates.
- Supports backfilling and entity revalidation.

Installation

``sh
npm install stripe-sync-engine stripe


or

pnpm add stripe-sync-engine stripe

or

yarn add stripe-sync-engine stripe

or

bun add stripe-sync-engine stripe
`

For Deno, leverage npm specifiers:

`ts
import { StripeSync } from 'npm:stripe-sync-engine@latest'
`

Usage

`ts
import { StripeSync } from 'stripe-sync-engine'

const sync = new StripeSync({
poolConfig: {
connectionString: 'postgres://user:pass@host:port/db',
max: 10, // Maximum number of connections
},
stripeSecretKey: 'sk_test_...',
stripeWebhookSecret: 'whsec_...',
// logger:
})

// Example: process a Stripe webhook
await sync.processWebhook(payload, signature)
`

Configuration

| Option | Type | Description |
| ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| databaseUrl | string | Deprecated: Use poolConfig with a connection string instead. |
| schema | string | Database schema name (default: stripe) |
| tablePrefix | string | Optional prefix for all table names. An underscore is auto-appended if not present. Example: 'billing' results in billing_products, billing_customers, etc. (default: empty string) |
| stripeSecretKey | string | Stripe secret key |
| stripeWebhookSecret | string | Stripe webhook signing secret |
| stripeApiVersion | string | Stripe API version (default: 2020-08-27) |
| autoExpandLists | boolean | Fetch all list items from Stripe (not just the default 10) |
| backfillRelatedEntities | boolean | Ensure related entities are present for foreign key integrity |
| revalidateObjectsViaStripeApi | Array | Always fetch latest entity from Stripe instead of trusting webhook payload, possible values: charge, credit_note, customer, dispute, invoice, payment_intent, payment_method, plan, price, product, refund, review, radar.early_fraud_warning, setup_intent, subscription, subscription_schedule, tax_id |
| poolConfig | object | Configuration for PostgreSQL connection pooling. Supports options like connectionString, max, and keepAlive. For more details, refer to the Node-Postgres Pool API documentation. |
| maxPostgresConnections | number | Deprecated: Use poolConfig.max instead to configure the maximum number of PostgreSQL connections. |
| logger | Logger | Logger instance (pino) |

Database Schema

The library will create and manage a stripe schema in your PostgreSQL database, with tables for all supported Stripe objects (products, customers, invoices, etc.).

$3

Migrations are included in the db/migrations directory. You can run them using the provided runMigrations function:

`ts
import { runMigrations } from 'stripe-sync-engine'

await runMigrations({
databaseUrl: 'postgres://...',
schema: 'stripe', // optional, defaults to 'stripe'
tablePrefix: 'billing', // optional, prefixes all tables (e.g., billing_products)
migrationTableName: 'stripe_migrations', // optional, defaults to 'stripe_migrations'
})
`

$3

| Option | Type | Description |
| -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| databaseUrl | string | PostgreSQL connection string |
| schema | string | Database schema name (default: stripe) |
| tablePrefix | string | Optional prefix for all table names. An underscore is auto-appended if not present. (default: empty string) |
| migrationTableName | string | Name of the table used to track migrations (default: stripe_migrations) |
| ssl | object | SSL connection options |
| logger | Logger | Logger instance (pino) |

Backfilling and Syncing Data

$3

You can sync or update a single Stripe entity by its ID using the syncSingleEntity method:

`ts
await sync.syncSingleEntity('cus_12345')
`

The entity type is detected automatically based on the Stripe ID prefix (e.g., cus_ for customer, prod_ for product). ent_ is not supported at the moment.

$3

To backfill Stripe data (e.g., all products created after a certain date), use the syncBackfill method:

`ts
await sync.syncBackfill({
object: 'product',
created: { gte: 1643872333 }, // Unix timestamp
})
`

- object can be one of: all, charge, customer, dispute, invoice, payment_method, payment_intent, plan, price, product, setup_intent, subscription.
- created is a Stripe RangeQueryParam and supports gt, gte, lt, lte.

> Note:
> For large Stripe accounts (more than 10,000 objects), it is recommended to write a script that loops through each day and sets the created date filters to the start and end of day. This avoids timeouts and memory issues when syncing large datasets.

Development

- Lint the project with pnpm lint (Biome).
- Format source files with pnpm format`.