Full sync

If your plugin was inactive for a while or a request got lost, a full sync brings the calendar back in line with your system. Recommended: on first connection and then once a day, for example by WP-Cron.

Steps

1. Start a sync

curl -X POST https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/syncs \
  -H "Authorization: Bearer $KS_KEY"

{ "sync_id": "sync_XXXXXXXXXXXXXXXX", "expires_at": "2026-11-03T15:02:11.000Z" }

A sync is valid for one hour.

2. Send every current event

Send every event that exists in your system by batch with the sync_id:

curl https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/events/batch \
  -H "Authorization: Bearer $KS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_id": "sync_XXXXXXXXXXXXXXXX",
    "operations": [
      { "method": "PUT", "external_id": "wp-1482", "event": { "title": "Sunset Yoga", "start": "2026-11-12T18:00:00" } },
      { "method": "PUT", "external_id": "wp-1490", "event": { "title": "Yin Yoga", "start": "2026-11-13T18:30:00" } }
    ]
  }'

Unchanged events cost nothing here: they are only marked as confirmed, not rewritten. The sync_id only exists on batch, not on the single PUT.

3. Complete the sync

curl -X POST https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/syncs/sync_XXXXXXXXXXXXXXXX/complete \
  -H "Authorization: Bearer $KS_KEY"

{ "sync_id": "sync_XXXXXXXXXXXXXXXX", "deleted": 3, "remaining": 42 }

This deletes every event that was not sent during the sync. Events you wrote outside the sync while it was running (for example a normal save on the website) are kept.

Protection against emptying a calendar

If completing would delete more than half of the events, the API refuses with 409 large_delete. A half-finished export should never empty a calendar with thousands of subscribers.

If the deletion is intended, confirm it:

curl -X POST https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/syncs/sync_XXXXXXXXXXXXXXXX/complete \
  -H "Authorization: Bearer $KS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "confirm_large_delete": true }'

Errors

Code	When
sync_not_found	The sync_id does not belong to this calendar.
sync_expired	The hour is over. Start a new sync.
sync_completed	The sync was already completed.
large_delete	More than half would be deleted.