Calendar API incremental synchronization uses a saved sync token to retrieve changes since a previous synchronization. It reduces repeated full downloads, but only when the client preserves the correct query and commits the returned state reliably. A page token and a sync token have different purposes.
Complete the initial full read
Run the intended list query and process every page. Google’s synchronization guide says nextSyncToken appears only on the final page of a paginated full sync. Store it with the corresponding collection and query configuration after processing that result.
Apply incremental changes
Use the saved value in syncToken on the next synchronization. Apply updated resources and deleted entries; Google includes deletions so the client can remove outdated local records. Keep the same permitted query parameters and review the collection’s restrictions.
If an incremental result is paginated, continue with the same original sync token and the returned page token until the new final sync token arrives. Do not mistake an intermediate page for a complete change batch.
Verify durable local state
Commit the processed changes and replacement token through a design that does not silently skip unfinished pages after a crash. Record enough non-sensitive operational evidence to distinguish successful completion from a partial read. Handle an invalidated token through the documented full-resync workflow rather than endlessly retrying it. Test updates, deletions, and interruption in a controlled environment. The completed mechanism should maintain the declared local mirror accurately; it is not evidence that unrelated calendars, unsupported query combinations, or unsaved local edits were synchronized merely because a token was present in one response.
References
- Synchronize resources efficiently | Google Calendar | Google for Developers
- Page through lists of resources | Google Calendar | Google for Developers
Reviewed against the linked official product guidance on November 4, 2026. Features, limits, screen labels, and access can vary by account, platform, region, and organization policy.