fastify-xplaid

transactions.sync(accessToken, options?)

Incrementally sync added, modified, and removed transactions using a cursor.

transactions.sync(accessToken, options?)

Preferred method for transaction sync. Uses a cursor-based approach to return only changes (added, modified, removed) since the last sync. Call repeatedly with the returned nextCursor until hasMore is false.

Signature

fastify.xplaid.transactions.sync(
  accessToken: string,
  options?: {
    cursor?: string
    count?: number
    accountIds?: string[]
  }
): Promise<{
  added: Transaction[]
  modified: Transaction[]
  removed: RemovedTransaction[]
  nextCursor: string
  hasMore: boolean
  requestId: string
}>

Params

Name	Type	Required	Default	Description
`accessToken`	`string`	Yes	—	The Item's access token
`options.cursor`	`string`	No	—	Cursor from previous sync; omit for first sync
`options.count`	`number`	No	—	Max transactions per page (capped at 500)
`options.accountIds`	`string[]`	No	—	Filter to specific account IDs

Returns

Field	Description
`added`	New transactions since last cursor
`modified`	Updated transactions
`removed`	Transactions that were removed (contains `transaction_id` only)
`nextCursor`	Cursor for the next sync call
`hasMore`	`true` if more pages remain; continue syncing

Throws

Error: [xPlaid] accessToken is required and must be a non-empty string
Plaid API error with .plaidError and .statusCode

Examples

Full cursor-based sync loop

async function syncAllTransactions(accessToken, savedCursor) {
  let cursor = savedCursor || undefined;
  let added = [], modified = [], removed = [];

  do {
    const response = await fastify.xplaid.transactions.sync(accessToken, { cursor });
    added = added.concat(response.added);
    modified = modified.concat(response.modified);
    removed = removed.concat(response.removed);
    cursor = response.nextCursor;
    if (!response.hasMore) break;
  } while (true);

  return { added, modified, removed, nextCursor: cursor };
}

Webhook-triggered incremental sync

fastify.post("/webhooks/plaid", async (request) => {
  if (request.body.webhook_type === "TRANSACTIONS" &&
      request.body.webhook_code === "SYNC_UPDATES_AVAILABLE") {

    const item = await db.plaidItem.findUnique({
      where: { itemId: request.body.item_id }
    });

    const result = await fastify.xplaid.transactions.sync(item.accessToken, {
      cursor: item.cursor,
    });

    await db.plaidItem.update({
      where: { id: item.id },
      data: { cursor: result.nextCursor },
    });
  }
  return { ok: true };
});

AI Context

package: "@xenterprises/fastify-xplaid"
method: fastify.xplaid.transactions.sync(accessToken, options?)
use-when: Incremental transaction sync using a cursor — recommended over transactions.get for keeping transaction data up to date
params: accessToken (required), cursor (optional, from previous sync), count
returns: { added, modified, removed, nextCursor, hasMore }

Edit this pageorReport an issue

transactions.refresh(accessToken)

Force-refresh transaction data for a Plaid Item.

webhooks.getVerificationKey(keyId)

Retrieve the JWK used to validate Plaid webhook payload signatures.