@supabase/stripe-sync-engine v0.38.1

Stripe Sync Engine

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

Features

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

Installation

npm install @supabase/stripe-sync-engine stripe
# or
pnpm add @supabase/stripe-sync-engine stripe
# or
yarn add @supabase/stripe-sync-engine stripe

Usage

import { StripeSync } from '@supabase/stripe-sync-engine'

const sync = new StripeSync({
  databaseUrl: 'postgres://user:pass@host:port/db',
  stripeSecretKey: 'sk_test_...',
  stripeWebhookSecret: 'whsec_...',
  // logger: <a pino logger>
})

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

Configuration

Database Schema

The library will create and manage a stripe schema in your Postgres 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:

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:

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:

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.