Plaid Transaction Sync

Implement the sync loop. Always loop until has_more is false:

import { PlaidApi } from "plaid";

async function syncTransactions(
  client: PlaidApi,
  accessToken: string,
  cursor: string | undefined
) {
  const allAdded: Transaction[] = [];
  const allModified: Transaction[] = [];
  const allRemoved: RemovedTransaction[] = [];

  let hasMore = true;
  let nextCursor = cursor ?? "";

  while (hasMore) {
    const response = await client.transactionsSync({
      access_token: accessToken,
      cursor: nextCursor,
      count: 500, // max per page
    });

    allAdded.push(...response.data.added);
    allModified.push(...response.data.modified);
    allRemoved.push(...response.data.removed);

    hasMore = response.data.has_more;
    nextCursor = response.data.next_cursor;
  }

  return { added: allAdded, modified: allModified, removed: allRemoved, cursor: nextCursor };
}

Persist the cursor. After processing all pages, save next_cursor to your database. On the next sync call, pass it back. If the cursor is lost, pass an empty string to get a full history replay.

// Save after successful processing
await db.items.update({
  where: { item_id: itemId },
  data: { transaction_cursor: nextCursor },
});

Apply changes to your local store:

// INSERT new transactions
for (const txn of added) {
  await db.transactions.upsert({
    where: { plaid_transaction_id: txn.transaction_id },
    create: {
      plaid_transaction_id: txn.transaction_id,
      amount: txn.amount,
      date: txn.date,
      name: txn.name,
      merchant_name: txn.merchant_name,
      category: txn.personal_finance_category?.primary,
      detailed_category: txn.personal_finance_category?.detailed,
      pending: txn.pending,
    },
    update: { /* same fields for modified */ },
  });
}

// DELETE removed transactions
for (const removed of allRemoved) {
  await db.transactions.delete({
    where: { plaid_transaction_id: removed.transaction_id },
  });
}

Handle pending transactions. Plaid sends pending transactions that later resolve to posted. The posted version has a different transaction_id. Use pending_transaction_id on the posted transaction to link them:

if (txn.pending_transaction_id) {
  await db.transactions.delete({
    where: { plaid_transaction_id: txn.pending_transaction_id },
  });
}

Trigger syncs via webhooks. Don't poll on a timer. Listen for SYNC_UPDATES_AVAILABLE webhooks:

// In your webhook handler
if (webhookCode === "SYNC_UPDATES_AVAILABLE") {
  const item = await db.items.findUnique({ where: { item_id: itemId } });
  await syncTransactions(client, item.access_token, item.transaction_cursor);
}