3. Backfill Existing Data

What Backfill Does

Backfill copies your existing Stripe data into BillStack's isolated team schema. This includes:

• Customers — all customer records from Stripe
• Products — all products (active and archived)
• Prices — all prices attached to products
• Subscriptions — all subscription records
• Invoices — invoice history
• Charges — payment records

After backfill, BillStack's database mirrors your Stripe state. Going forward, webhooks keep it in sync automatically.

Trigger a Full Backfill

Dashboard UI

1. Navigate to Team Settings > Stripe Connection
2. Click Sync Data / Backfill
3. Wait for the sync to complete (progress shown in the UI)

API

curl -X POST https://your-billstack.com/api/billstack/teams/{teamId}/stripe/backfill \
  -H "Content-Type: application/json" \
  -H "Cookie: <session-cookie>"

Response:

{
  "success": true,
  "message": "Backfill started",
  "syncStatus": "syncing",
  "result": {
    "customer": { "synced": 1250 },
    "product": { "synced": 15 },
    "price": { "synced": 42 },
    "subscription": { "synced": 890 },
    "invoice": { "synced": 3200 },
    "charge": { "synced": 4100 }
  }
}

Selective Backfill

You can sync only specific object types or filter by creation date:

curl -X POST https://your-billstack.com/api/billstack/teams/{teamId}/stripe/backfill \
  -H "Content-Type: application/json" \
  -H "Cookie: <session-cookie>" \
  -d '{
    "objects": ["customer", "product", "price", "subscription"],
    "createdAfter": "2025-01-01T00:00:00Z"
  }'

Assigning Customers to Projects

After backfill, your Stripe data lives in the team schema but customers are not yet assigned to projects. You need to assign them:

1. Create a project in the BillStack dashboard for each SaaS product
2. Create customers via the BillStack API — this creates BillStack-scoped customer records linked to Stripe customers:

curl -X POST \
  https://your-billstack.com/api/billstack/teams/{teamId}/projects/{projectId}/customers \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "existing-customer@example.com",
    "name": "Jane Doe"
  }'

If a Stripe customer with that email already exists, BillStack links to the existing Stripe customer. If not, it creates a new one in Stripe with project_id metadata.

Monitoring Sync Status

Check the current sync state:

curl https://your-billstack.com/api/billstack/teams/{teamId}/stripe/status \
  -H "Cookie: <session-cookie>"

The syncStatus field shows:

• pending — sync not started
• syncing — backfill in progress
• ready — all data synced
• error — something went wrong (check logs)

Idempotency

Backfill is safe to run multiple times. The stripe-sync-engine uses upserts — running it again will update existing records and add any new ones from Stripe. It will not create duplicates.

Next Step

With your data in BillStack, replace your Stripe SDK calls with BillStack API calls.