Skip to content

README.md

Latest commit

 

History

History
100 lines (72 loc) · 7.04 KB

README.md

File metadata and controls

100 lines (72 loc) · 7.04 KB

Stripe Sync Engine

GitHub License NPM Version

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

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

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). ent_ is not supported at the moment.

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.