Guide

Incremental sync

Transactions and bills change after they first appear: a pending payment books, a category is assigned, a bill is approved and paid. The updatedAfter filter lets you pick up exactly those changes.

The pattern

1. Backfill once. Page through GET /transactions (and GET /bills) with the date range you care about.
2. Remember a watermark. After each run, store the largest updatedAt you saw.
3. Poll with updatedAfter. On the next run pass the watermark (minus a small overlap) as updatedAfter. You get every row created or modified since — and nothing else.
4. Upsert by id. Ids are stable for the life of a row, so applying the same page twice is harmless.

# First run: everything since the start of the year
curl "https://api.paygoro.com/v1/transactions?dateFrom=2026-01-01&limit=100" \
  -H "Authorization: Bearer $PAYGORO_API_KEY"

# Every later run: only what changed since the newest updatedAt you stored,
# minus a one-minute overlap
curl "https://api.paygoro.com/v1/transactions?updatedAfter=2026-08-30T09:14:00Z&limit=100" \
  -H "Authorization: Bearer $PAYGORO_API_KEY"

What can change on a row

• Transactions — status moves from pending to booked (or rejected/canceled); category is set by rules, by Paygoro's enrichment, or by a person, and can be corrected later; merchantName fills in once enrichment runs.
• Bills — status walks the approval and payment lifecycle, extracted fields are corrected by hand, matchedTransactionId and paidAt appear once the payment settles.

Practical advice

• Overlap the watermark by a minute. Rows updated in the same second as your previous run are then never missed.
• Poll every 15 minutes or so. Bank data reaches Paygoro on the banks' schedule, typically a few times a day; polling more often mostly spends your rate limit.
• Don't filter by status while syncing. A transaction that leaves the status you filtered on would then vanish from your feed without a trace.
• Treat deletions as absence. v1 has no tombstones; rows are effectively never deleted, but if you need to be certain, a periodic full re-read of a bounded date range is the check.