migrating-to-checkpoints

To migrate Nango TypeScript syncs to checkpoint-based progress, define a flat checkpoint schema and update execution loops to call getCheckpoint, batchSave, and saveCheckpoint after every page. This replaces legacy lastSyncDate usage with durable, restartable progress tracking.

You need to call saveCheckpoint inside paginate loops after every batchSave operation to ensure sync progress is durable. This checkpoint-based progress model guarantees that if a sync is interrupted, it resumes exactly where the last checkpoint was saved.

The clearCheckpoint method should only be called after a full-refresh sync completes entirely. Using clearCheckpoint prematurely during a checkpointed full refresh will delete the progress state and prevent the Nango sync from resuming correctly if interrupted.

You test Nango syncs using checkpoint dry runs by executing the sync with the --checkpoint flag. This simulates real progress windows and validates that your getCheckpoint and saveCheckpoint calls are correctly structured across batchSave operations.

Yes, checkpoint schemas work with zero YAML TypeScript syncs in Nango. You define the flat checkpoint object structure directly in your createSync implementation, then manage it using getCheckpoint and saveCheckpoint throughout the execution loop.

Checkpointed incremental syncs fail to handle deletions correctly if legacy deletion logic is not adjusted for the new progress model. You must update deletion handling to align with checkpoint boundaries so that records removed between sync runs are processed accurately.