Stripe Sync Engine - Complete Guide

You are an expert in stripe-sync-engine. This skill covers setup, migrations, webhooks, backfill, and querying in one place.

1. Installation

npm install stripe-sync-engine stripe pg

2. Environment Variables

DATABASE_URL=postgresql://user:password@host:5432/database STRIPE_SECRET_KEY=sk_live_... STRIPE_WEBHOOK_SECRET=whsec_...

3. Create StripeSync Utility

// lib/stripeSync.ts import { StripeSync } from "stripe-sync-engine";

export const stripeSync = new StripeSync({ stripe: { apiKey: process.env.STRIPE_SECRET_KEY! }, webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!, databaseUrl: process.env.DATABASE_URL!, });

4. Run Migrations

// scripts/run-migrations.ts import { stripeSync } from "../lib/stripeSync";

async function main() { await stripeSync.runMigrations(); console.log("Migrations complete"); process.exit(0); } main();

npx tsx scripts/run-migrations.ts

5. Webhook Handler

Next.js App Router:

// app/api/webhooks/stripe/route.ts import { NextResponse } from "next/server"; import { stripeSync } from "@/lib/stripeSync";

export async function POST(request: Request) { const signature = request.headers.get("stripe-signature") ?? undefined; const payload = Buffer.from(await request.arrayBuffer());

await stripeSync.processWebhook(payload, signature); return NextResponse.json({ received: true }); }

Hono:

app.post("/webhooks/stripe", async (c) => { const signature = c.req.header("stripe-signature"); const payload = await c.req.text();

await stripeSync.processWebhook(payload, signature); return c.json({ received: true }); });

6. Backfill Historical Data

// Backfill all data types await stripeSync.syncBackfill();

// Backfill specific types await stripeSync.syncBackfill({ objectTypes: ["customer", "subscription", "invoice"], });

// Backfill with date range await stripeSync.syncBackfill({ created: { gte: Math.floor(Date.now() / 1000) - 30 * 24 * 60 * 60 }, });

// Sync single entity await stripeSync.syncSingleEntity("cus_ABC123");

7. Query Synced Data

Tables available:

• stripe.customers , stripe.products , stripe.prices

• stripe.subscriptions , stripe.subscription_items

• stripe.invoices , stripe.invoice_line_items

• stripe.charges , stripe.payment_intents , stripe.payment_methods

• stripe.coupons , stripe.disputes , stripe.setup_intents

Example queries:

-- Active subscriptions SELECT c.email, s.status, p.name as product FROM stripe.subscriptions s JOIN stripe.customers c ON s.customer_id = c.id JOIN stripe.prices pr ON s.items->0->>'price_id' = pr.id JOIN stripe.products p ON pr.product_id = p.id WHERE s.status = 'active';

-- Monthly revenue SELECT DATE_TRUNC('month', created) as month, SUM(amount_paid) / 100.0 as revenue FROM stripe.invoices WHERE status = 'paid' GROUP BY 1 ORDER BY 1;

8. Local Testing

Terminal 1: Start your server

npm run dev

Terminal 2: Forward Stripe events

stripe listen --forward-to localhost:3000/api/webhooks/stripe

Terminal 3: Trigger test events

stripe trigger customer.created stripe trigger invoice.payment_succeeded

Quick Troubleshooting

Issue Solution

Signature failed Use raw body (Buffer), not parsed JSON

Connection error Check DATABASE_URL format and SSL settings

Data not syncing Run migrations first, check schema exists

Edge runtime error Add export const runtime = 'nodejs'