Skip to content

With TypeScript

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

1
2
3
4
5
npm install @supabase/stripe-sync-engine stripe
# or
pnpm add @supabase/stripe-sync-engine stripe
# or
yarn add @supabase/stripe-sync-engine stripe

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import { StripeSync } from '@supabase/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: <a pino 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)
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 the PostgreSQL connection pool. Supports options like connectionString, max, and keepAlive.
maxPostgresConnections number Deprecated: Use poolConfig.max instead to configure the maximum number of PostgreSQL connections.
logger Logger Logger instance (pino)

Example poolConfig

1
2
3
4
5
6
7
const config = {
  poolConfig: {
    connectionString: 'postgresql://user:password@localhost:5432/mydb',
    max: 20, // Maximum number of connections
    keepAlive: true, // Keep connections alive
  },
}

For more details, refer to the Node-Postgres Pool API documentation.

SSL CA Certificate in Base64 Format

1
2
3
4
5
6
7
8
const config = {
  poolConfig: {
    // optional SSL configuration
    ssl: {
      ca: Buffer.from(process.env.SSL_CA_CERT).toString('utf-8'),
    },
  },
}

Note: Replace <base64-encoded-ca> with your actual base64-encoded certificate (development only) or the environment variable containing it (recommended for production).

Generating Base64 from CA Certificate

To generate a base64-encoded CA certificate, follow these steps:

  1. Obtain the CA certificate file (e.g., prod-ca-2021.crt).
  2. Use the following command on Unix-based systems:
1
base64 -i prod-ca-2021.crt -o CA.base64
  1. Open the CA.base64 file and copy its contents.
  2. Use the base64 string in your configuration or environment variables.

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

Migrations

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

1
2
3
import { runMigrations } from '@supabase/stripe-sync-engine'

await runMigrations({ databaseUrl: 'postgres://...' })

Backfilling and Syncing Data

Syncing a Single Entity

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

1
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).

Backfilling Data

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

1
2
3
4
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.