Google Ads Sync

Overview

TODO match with bank payout

Implementation

  • Core sync logic: src/lib/server/google-ads-sync.ts
  • API endpoints: src/routes/api/sync/google-ads/

More details

Primary source: Google Ads SearchStream API (DAILY granularity)

  • Accurate: 99.4% match with bank payment
  • Available almost immediately (1days delay)
  • Dates input for fetch: dates interval
  • When data becomes available, how many days may the source adjust them: 30days (Claude told me, conservative)

Invoice corrections (InvoiceService API — MONTHLY granularity)

  • For each completed month, the sync fetches the Google Ads invoice via InvoiceService.ListInvoices()
  • The invoice includes: taxes, adjustments (invalid traffic credits/refunds), regulatory costs (DST, operating charges), and export charges — none of which are in campaign cost_micros
  • A correction ratio is calculated: invoice_total / invoice_subtotal
  • This ratio is applied proportionally to each day's campaign spend, so the daily costs match the actual billed amount
  • Invoice-corrected records get data_accuracy = 100 (vs 95 for raw campaign data), so they won't be overwritten by a subsequent sync without invoice data
  • Invoices are available ~7 business days after month end; recent months use a 1-hour cache TTL to retry until the invoice appears
  • Requires a billing setup (fetched via GAQL, cached permanently)

How sync works

<!-- The sync can be triggered any time. So it needs to be idempotent,
can handle situations when it's wasn't run for a long period of time,
and also don't do anything if already ran today.

Note the date ranges are always inclusive. -->


if ( lastSyncDate < today ):
  fetchData ( range: {start: (lastSyncDate + 1day) - 30days, end: today} )
  <!-- Processes in monthly chunks for resumability -->
  <!-- For each completed month: try to fetch invoice, apply correction ratio -->
How the accuracy was measured + ground truth data for testing
  • Google Ads invoiced net cost - 1 May 2024 - 31. Jan 2026
    • inoiced net costs - 96810 € (intentionally not using the bank data, because the payments there are very not precise, because Google uses buffer to keep some spare cash in the Google account. And we assume that google will always bill eventually the invoiced amount. Nothing less, nothing more)
    • reported by this finboard - 97375 €
    • Discrepancy is because some invalid traffic and taxes are adjusted during the invoicing