How to Write an Apple Calendar Support Status FAQ (PM Templates & Architecture)

If your B2B SaaS product offers Google Calendar and Microsoft Outlook integration but stops short of Apple Calendar, your support team is fielding the same angry ticket every week: "Why doesn't your app sync with my iCloud calendar?"

As we've noted when discussing how to build integrations your B2B sales team actually asks for, product managers at B2B SaaS companies constantly find themselves caught between sales teams demanding Apple Calendar support to close enterprise deals, and engineering teams outright refusing to build it. The search query "create an faq / product page: apple calendar support status" usually comes from a place of sheer exhaustion. You need a way to explain to your users why connecting their Apple Calendar is delayed, requires bizarre workarounds, or is entirely missing from your platform.

This guide gives senior PMs a comprehensive breakdown of the architectural realities of Apple Calendar integration, explains why it is so difficult to build natively, and provides copy-and-paste templates for your support documentation to manage customer expectations without making your engineering team look incompetent.

Why Apple Calendar Support Is the Elephant in the SaaS Roadmap

Calendar integration is a baseline expectation for any modern B2B SaaS product touching scheduling, CRM, ATS, or project management. If your software books meetings, users expect their availability to sync automatically.

Apple Calendar support is the most frequently requested calendar integration that B2B SaaS teams keep punting on. It is not laziness. It is a rational engineering trade-off that nobody bothers to explain to customers, which is exactly why your support queue keeps growing.

Here is the uncomfortable math. According to Dataintelo's Calendar Applications Market Research Report, Google Calendar and Microsoft Outlook together capture roughly 63% of the global digital calendar market. Consequently, engineering teams build REST API integrations for Google and Microsoft first.

However, ECAL's consumer research puts the proportion of adults who depend primarily on a digital calendar at around 70%. That means most of your users live inside Google or Microsoft, a meaningful minority lives inside iCloud, and almost none of them care that Apple's calendar stack is a 20-year-old protocol stitched together with XML and app-specific passwords.

For a Senior PM, the political problem is worse than the engineering one. Sales hears "Apple Calendar" in three out of every ten enterprise demos. The executives and founders using Apple devices are often the economic buyers of your software. When the CEO cannot sync their iPad calendar to your SaaS platform, the sales deal stalls. Engineering looks at the CalDAV spec, sees PROPFIND verbs and namespaced XML, and quietly moves the ticket to the backlog. Support, meanwhile, has no documented answer to give the customer beyond "it's on our roadmap."

The fix is not to ship Apple Calendar tomorrow. The fix is to ship a public FAQ page that turns "it's on our roadmap" into a credible, technically honest stance—and to pair it with at least one workaround the user can act on today.

Overview: Apple Calendar Constraints and Tradeoffs

Before you commit engineering resources, put the Apple Calendar problem on one page. Here is the short version of every constraint you will hit, and the four ways teams typically respond.

The constraints in one glance:

• No REST API. iCloud exposes CalDAV (RFC 4791) only. XML request bodies, custom HTTP verbs, .ics payloads embedded inside XML responses.
• No OAuth. Users generate 16-character app-specific passwords manually. Two-factor auth must be enabled first.
• No webhooks. Change detection is sync-collection reports plus polling. Expect 15 to 60 minute lag under realistic polling budgets.
• Silent credential expiry. If a user rotates their Apple ID password, every app-specific password is revoked immediately. You find out on the next 401.
• Unreliable free/busy. iCloud's CalDAV free/busy implementation is partial. Availability checks that work on Google will return incomplete data on iCloud.
• Undocumented rate limits. Empirically around 1 request per second per account, but Apple has never published limits.

The tradeoff matrix:

Pick the row that matches your revenue exposure. If Apple Calendar support is blocking six-figure deals, native or unified is your only credible answer. If it's a long tail of consumer requests, the workarounds below are enough.

The same decision framework applies when teams need to sync Google and Outlook calendars into a single product surface: pick one primary provider per user, and treat everything else (iCloud, secondary work accounts, ICS subscriptions) as read-only feeds into that primary. That pattern keeps your write path simple and your conflict resolution logic sane.

The Technical Reality: CalDAV vs REST APIs

Before you can write the FAQ, you and your support team need to share the same mental model. When your users ask why Apple Calendar is missing, they assume connecting a calendar is a standardized process. It is not. Explaining the delay requires understanding the fundamental architectural differences between modern calendar APIs and Apple's infrastructure.

Google and Microsoft Give You a Modern REST API

Google Calendar and Microsoft Graph both expose modern, developer-friendly interfaces:

• JSON-over-HTTPS REST endpoints: They accept JSON payloads and return predictable JSON responses.
• OAuth 2.0: Support for standard refresh tokens and granular scopes.
• Webhooks: Google's watch channels and Microsoft Graph subscriptions allow for near real-time change notifications.
• Standard Tooling: Documented rate limits, batch endpoints, and SDKs in every major language.

A junior engineer can read the docs on Monday and ship a working integration by Friday.

Apple Gives You CalDAV Over iCloud

Apple has no first-party REST API for iCloud Calendar. There is no https://api.icloud.com/calendar/v1/events endpoint. Instead, third-party apps must speak CalDAV, an extension of WebDAV defined in RFC 4791. That means:

• XML request and response bodies: You do not get JSON. You parse <C:calendar-data> blocks containing iCalendar (.ics) payloads, which is a second nested string format you also have to parse and manipulate.
• Non-standard HTTP verbs: Instead of standard REST verbs (GET, POST, PATCH), CalDAV requires custom HTTP methods like PROPFIND, REPORT, and MKCALENDAR. Most HTTP client libraries handle these, but proxies, WAFs, and load balancers in your customers' networks frequently drop them.
• No webhooks: CalDAV uses sync-collection reports and ETags for change detection, which forces constant polling. There is no push notification equivalent to Google's watch channels.

To understand the engineering friction, look at a standard request to fetch events.

Here is how your system asks Google for events (JSON/REST):

GET /calendars/primary/events?timeMin=2026-01-01T00:00:00Z&timeMax=2026-01-31T23:59:59Z
Authorization: Bearer {token}

Here is how your system must ask Apple for events (XML/CalDAV):

REPORT /caldav/v2/user/events/ HTTP/1.1
Depth: 1
Content-Type: application/xml; charset=utf-8
 
<?xml version="1.0" encoding="utf-8" ?>
<c:calendar-query xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
    <d:prop>
        <d:getetag />
        <c:calendar-data />
    </d:prop>
    <c:filter>
        <c:comp-filter name="VCALENDAR">
            <c:comp-filter name="VEVENT">
                <c:time-range start="20260101T000000Z" end="20260131T235959Z" />
            </c:comp-filter>
        </c:comp-filter>
    </c:filter>
</c:calendar-query>

Your engineering team has to build an entirely separate XML parsing engine, handle .ics string manipulation inside the XML responses, and maintain a completely distinct codebase just for this one provider. For a deeper dive into this pain point, see our guide on why schema normalization is the hardest problem in SaaS integrations.

The App-Specific Password Nightmare

The protocol is only half the problem. The authentication flow is what truly destroys the user experience. Apple does not support standard OAuth 2.0 for third-party calendar access.

With Google and Microsoft, users click "Connect," log in via a familiar popup, grant permissions, and are redirected back to your app.

Per Apple's own security model, users have to log into appleid.apple.com, navigate to the Sign-In and Security section, and manually generate a 16-character app-specific password for each app that needs iCloud access. Two-factor authentication must be enabled first.

sequenceDiagram
    participant User
    participant SaaS as Your SaaS
    participant Apple as Apple Security UI
    
    User->>SaaS: Click "Connect Apple Calendar"
    SaaS-->>User: Show instructions to leave app
    User->>Apple: Navigate to appleid.apple.com
    Apple-->>User: Require 2FA verification
    User->>Apple: Navigate to App-Specific Passwords<br>and generate new password
    Apple-->>User: Display 16-character string
    User->>SaaS: Paste string into SaaS UI
    SaaS->>Apple: Authenticate via CalDAV Basic Auth

From a product perspective, this is brutal:

• Your onboarding flow goes from one click ("Connect Google") to a highly disjointed, six-step screenshot walkthrough.
• You cannot scope permissions. The app-specific password grants access to whatever the user's Apple ID can reach.
• Users routinely paste the password incorrectly.
• If the user changes their primary Apple ID password, the app-specific password is automatically revoked, breaking the integration silently. There is no programmatic way to detect that the credential has expired until the next CalDAV request returns a 401.

flowchart LR
    A[Your SaaS App] -->|OAuth 2.0 + JSON| B[Google Calendar API]
    A -->|OAuth 2.0 + JSON| C[Microsoft Graph]
    A -->|App-Specific Password<br>CalDAV + XML + PROPFIND| D[iCloud Calendar]
    style D fill:#ffe0e0,stroke:#cc0000

How to Structure Your Apple Calendar Support Status FAQ

When writing your public-facing support documentation, you must balance technical accuracy with user empathy. A good Apple Calendar FAQ does three things: it sets honest expectations, it explains the why in customer-friendly language, and it gives the user an immediate next step.

Here is the structure I recommend:

1. State the current support status in one sentence: Do not bury this. Buyers searching " [your product] Apple Calendar integration" want a yes/no in the first paragraph.
2. Explain the technical reason in plain English: This is where most FAQs fail. They either say nothing ("we're working on it") or get too defensive. Aim for one short paragraph that respects the reader's intelligence.
3. List the supported workarounds with realistic limitations: Do not over-promise. Spell out the lag, the one-way nature, and any features that will not work.
4. Link to the roadmap and a feedback channel: Give enterprise buyers a way to upvote the request. This converts a support ticket into a product signal.
5. Add an internal-only support macro: Your CS team should have a Zendesk or Intercom macro that pastes the FAQ link plus a personalized line. This is what actually cuts ticket volume.

Copy-and-Paste Support Templates

Here are three copy-and-paste templates you can adapt for your help center, depending on your product's current roadmap.

Template 1: The "Not Supported" Stance

Use this template if you have zero plans to build Apple Calendar support and need a definitive answer to close support tickets.

Title: Why can't I connect my Apple / iCloud Calendar?

Body: Currently, [Your Product Name] supports direct integrations with Google Calendar and Microsoft Outlook. We do not offer native support for Apple Calendar (iCloud) at this time.

Why isn't it supported? Apple does not provide a modern REST API for iCloud Calendar. Integrating with it requires CalDAV, an older XML-based protocol, plus a manually generated "app-specific password" from each user's Apple ID account. Because this process creates a difficult setup experience and frequently disconnects when users update their Apple ID credentials, we have prioritized Google Calendar and Outlook, which cover roughly 63% of business calendar users and offer a more reliable real-time sync experience.

Workarounds: If you use Apple Calendar on your Mac or iPhone, you can sync your iCloud calendar into a free Google Calendar account, and connect that Google account to [Your Product Name]. See our guide on syncing Apple Calendar to Google below.

Template 2: The "App-Specific Password Required" Stance

Use this template if your engineering team built the CalDAV integration, and you need to guide users through the painful authentication process.

Title: How to Connect Your Apple Calendar (App-Specific Password Required)

Body: You can connect your Apple Calendar to [Your Product Name] to sync your availability. Because Apple does not support standard one-click login for third-party apps, you will need to generate a temporary password specifically for our application.

Step-by-Step Setup:

1. Log in to appleid.apple.com using your Apple ID.
2. Navigate to the Sign-In and Security section and select App-Specific Passwords.
3. Click Generate an app-specific password.
4. Name the password " [Your Product Name] Sync" so you remember what it is for.
5. Copy the 16-character password provided by Apple.
6. Return to [Your Product Name], enter your iCloud email address, and paste the 16-character password into the connection screen.

Template 3: The "Read-Only / ICS" Stance

Use this template if you only support one-way ingestion of calendar events via public links.

Title: How to View Your Apple Calendar in [Your Product Name]

Body: You can view your Apple Calendar events inside [Your Product Name] by subscribing to your iCloud calendar via a public link. Please note that this is a read-only connection. Events created in [Your Product Name] will not push back to your Apple Calendar.

How to sync:

1. Open the Calendar app on your Mac or log into iCloud.com.
2. Click the broadcast icon next to the calendar you want to share.
3. Check the box for Public Calendar.
4. Copy the provided URL (it will start with webcal://).
5. Paste this URL into the Calendar Settings page in [Your Product Name].

Note on Sync Delays: Apple controls how frequently external applications can fetch updates from public calendar links. Changes made on your iPhone may take up to 15-60 minutes to reflect in [Your Product Name].

Workaround 1: Sync Apple Calendar to Google Calendar First

If you refuse to build CalDAV, the most common workaround is instructing users to route their Apple events through Google. This solves 80% of customer requests, and it reuses the same OAuth 2.0 integration you already ship for teams that need to sync Google and Outlook calendars in a single product surface. This is highly relevant for PMs writing how to integrate multiple calendar services.

How it works architecturally: Apple Calendar can subscribe to a Google Calendar account natively on iOS and macOS, and any events the user creates in Apple Calendar can be written into a Google account they own. The user adds Google as an account under Settings > Calendar > Accounts on iOS. Your SaaS then authenticates with Google via standard OAuth 2.0 and reads the events.

Step-by-Step User Instructions (Ship This as a Help Center Article)

Copy this directly into your docs. It works for both iOS and macOS users.

On iPhone or iPad:

1. Open Settings > Calendar > Accounts > Add Account.
2. Select Google and sign in with the Google account you want to use as your unified calendar.
3. Toggle Calendars on. Leave Mail, Contacts, and Notes off unless you want those synced too.
4. Back in Settings > Calendar, set Default Calendar to your Google account. All new events created in the Apple Calendar app will now be written to Google.
5. Open the Calendar app and tap Calendars at the bottom. Confirm your Google calendar is visible and checked.
6. Return to [Your Product Name] and connect your Google account via the standard "Connect Google Calendar" button.

On macOS:

1. Open System Settings > Internet Accounts > Add Account > Google.
2. Sign in and enable Calendars.
3. Open the Calendar app, then Calendar > Settings > Accounts, and set your Google account as the default.
4. Move any existing iCloud events to the Google calendar by dragging them in the sidebar.

Architect Guidance

If you are the engineer supporting this flow, three things determine whether it works reliably in production:

• Detect the routing at connection time. When a user connects Google, log which calendars are backed by iCloud subscriptions vs. native Google calendars. Google exposes the source via the calendarList endpoint's summary and id fields. This tells your CS team whether a "Google" connection is actually a routed iCloud calendar behind the scenes.
• Set expectations for two-way writes. Events created in [Your Product Name] land in Google, and Google mirrors them back to Apple Calendar on the user's device via native sync. Round-trip time is typically under a minute but is not guaranteed.
• Do not rely on this for enterprise-managed devices. MDM policies (Jamf, Intune, Kandji, Workspace ONE) frequently restrict which account types can be added on managed iPhones and iPads. If your customer's IT policy blocks personal Google accounts, this workaround is a dead end.

Propagation Delay Expectations

Publish these numbers in your help center so users do not file tickets asking why their event is not visible instantly:

Enterprise MDM Caveats

Before you recommend this workaround to enterprise customers, verify:

• Account restrictions. Corporate MDM profiles often allow only the managed corporate Google or Microsoft account and block personal Google account addition on the device.
• Data residency policies. Some regulated customers (finance, healthcare, EU public sector) cannot route calendar data through a personal Google account without violating their DPA.
• Managed Apple ID limitations. Managed Apple IDs used in Apple Business Manager have restricted iCloud features. If your customer uses Managed Apple IDs, iCloud Calendar may not federate to Google at all.
• Zero-trust / conditional access. Some tenants enforce Conditional Access on the Google Workspace side that blocks OAuth grants from unrecognized device postures. Confirm your OAuth consent screen is on the customer's allowlist before you demo the flow.

Architectural advantages:

• You use your existing Google Calendar integration. No new code.
• You inherit Google's webhooks, OAuth, and rate limits, which are all well-documented.
• Free/busy queries work because Google exposes them as a REST endpoint.

The brutal honesty you must include: You must warn users about propagation delays. While syncing from an iOS device to Google usually takes under a minute, there can be delays. Furthermore, events created in iCloud-only calendars (Family, Work account calendars not linked to Google) will not sync. Some enterprise MDM policies may also block users from adding personal Google accounts to their work devices.

Workaround 2: Read-Only ICS Subscription Sync

The second workaround is read-only and exists for users who cannot or will not route through Google. If your application only needs to display a user's schedule—without needing to write events back or perform real-time availability checks—you can build an ICS ingestion engine.

How it works architecturally: Your backend accepts a webcal:// or https:// link pointing to an .ics file published by iCloud. You run a cron job that periodically fetches the file, parses the iCalendar format, and updates your internal database.

sequenceDiagram
    participant User
    participant iCloud
    participant YourApp
    User->>iCloud: Create event in Apple Calendar
    iCloud->>iCloud: Publish to .ics URL
    Note over YourApp: Polls every 15 min
    YourApp->>iCloud: GET https://p01-calendars.icloud.com/.../home.ics
    iCloud-->>YourApp: VCALENDAR payload
    YourApp->>YourApp: Parse iCalendar, normalize to internal schema
    YourApp-->>User: Event visible in [Product]

Implementation Pattern

Below is a production-ready ingestion pattern. Adapt the language and queue technology to your stack.

1. Ingest and normalize the webcal URL. Users paste a webcal:// URL from the Apple Calendar share sheet. Rewrite it to https:// before storing. The two schemes point to the same content, but almost every HTTP client rejects webcal:// directly.

2. Schedule polling with jitter. A single cron interval across all users creates a thundering herd against Apple's edge servers. Hash the calendar ID into a 15-minute window so fetches spread evenly across the cycle.

3. Fetch with conditional requests. Apple's .ics endpoints return ETag and Last-Modified headers. Send If-None-Match on every request. When Apple returns 304 Not Modified, skip parsing entirely and update only the "last checked" timestamp. This cuts CPU and bandwidth by 80% or more on stable calendars.

4. Parse with a maintained iCalendar library. Do not write your own. Use ical.js (JavaScript/TypeScript), icalendar (Python), or biweekly (Java). Roll-your-own parsers break on the first EXDATE with a comma-separated list or the first VTIMEZONE with a custom RRULE.

5. Diff and upsert. Compare parsed VEVENT UIDs against your database. Insert new events, update changed ones by comparing DTSTAMP, and soft-delete anything missing from the latest payload. Do not hard-delete on the first missing pass. Apple occasionally returns partial payloads during publish operations, and hard-deleting on transient truncation will make the user's calendar flap.

6. Handle failures explicitly. Distinguish between transient failures (5xx, timeouts, DNS blips -> retry with exponential backoff) and permanent failures (404, Public Calendar unchecked -> surface a disconnect banner in your product within 24 hours).

Recommended Cron Schedule

Whatever interval you pick, make it configurable per tenant. Enterprise customers with slow-moving executive calendars are happy with hourly; sales teams need 5-minute polling.

Parsing Pitfalls

The pitfalls that will hit you in production, in rough order of frequency:

• Recurring event exceptions. A VEVENT with RECURRENCE-ID overrides a specific instance of a series. Parsers that treat every VEVENT as independent will produce duplicate events at the overridden time.
• All-day events. iCloud emits DTSTART;VALUE=DATE:20260315 (no time, no timezone). Storing this as a DATETIME in your database with an implicit UTC offset produces off-by-one-day bugs for anyone east of London.
• VTIMEZONE with post-2038 rules. Some parsers hardcode the Unix epoch ceiling and fall back to UTC for DST transitions after January 2038. Your users will not notice today. They will when the calendar drifts silently in 12 years.
• Character encoding. iCloud occasionally emits non-UTF-8 characters in event titles (Latin-1 mojibake from imported Outlook events). Decode defensively and never assume UTF-8.
• Line folding. iCalendar wraps long lines at 75 octets with a CRLF-plus-space continuation. Naive line splitters corrupt long descriptions and URLs.
• Multiple VCALENDAR blocks per file. A single .ics URL may contain multiple VCALENDAR blocks. Iterate all of them, do not stop after the first END:VCALENDAR.
• Silent revocation. If the user unchecks "Public Calendar" in Apple's settings, the URL returns 404 immediately. Your only signal is the HTTP response code, so alert on it aggressively.

The brutal honesty you must include: This is where SaaS products lose trust. Apple's own clients fetch external .ics subscriptions on their own cadence, often hourly. If you set the customer's expectation at "every 15 minutes," make sure your polling job actually delivers that. Be explicit that changes made on the Apple side may take that long to appear in your product. Furthermore, if the user ever unchecks "Public Calendar" in their Apple settings, the link breaks immediately, and your sync fails silently until the user complains.

When to Build CalDAV Yourself: A Cost vs Benefit Checklist

Every twelve months, someone on your engineering team will ask "should we just build the CalDAV client and be done with it?" Answer that question with a checklist, not a gut call.

Build CalDAV yourself if all of these are true:

• Apple Calendar has been in your top 5 requested integrations for two consecutive quarters.
• At least one enterprise deal above your median ACV has stalled specifically on Apple Calendar support in the last six months.
• Your product does not have adequate coverage from the Google-routing workaround (users need to sync iCloud-only calendars like Family, or corporate-managed Apple accounts, or Managed Apple IDs).
• You have a senior backend engineer with 6 to 12 weeks of unbroken capacity, plus 10 to 15% ongoing maintenance load thereafter.
• Your compliance posture requires that iCloud data never touches a third-party vendor.
• Your product needs write access (create, update, delete), not just read.

Do not build CalDAV yourself if any of these are true:

• The workarounds (Google routing or ICS subscription) cover more than 80% of your customer requests.
• Your engineering team has fewer than 15 backend engineers total. Ongoing maintenance will eat a rotating on-call slot.
• You already use a unified API for other integrations, and Apple Calendar is available as a connector.
• You cannot commit to shipping the connection UX (app-specific password walkthrough, revocation handling, error recovery) at the same quality bar as Google Calendar.
• Your product roadmap has any feature within the next quarter that would push CalDAV work below the priority line anyway.

Rough cost estimate for a native build:

If the checklist points to "buy," the pass-through unified API route in the next section keeps optionality open. You get Apple Calendar today and can migrate to a native build later without changing your product's API surface.

Recommended Implementation Patterns for a Unified Calendar API

Once you have chosen your integration approach - direct build, workaround, or unified API - a few implementation patterns separate calendar integrations that hold up in production from the ones that generate PagerDuty alerts. These apply whether you are calling Google Calendar directly, using Cal.com's API, or routing everything through a unified layer.

1. Idempotent writes. Every calendar create or update should carry a client-generated idempotency key. If your service retries an event creation after a network blip, an idempotent write prevents duplicate meetings on the user's calendar. Google and Microsoft both accept deduplication via extended properties or transaction IDs on the request.

2. Separate identity from provider tokens. Store the user's connection ID (Truto calls this integrated_account_id) as the primary key for the linked calendar, and the provider tokens as encrypted secondary data. When the user reconnects, you rotate tokens without breaking foreign keys elsewhere in your product.

3. Change detection with a fallback. Webhooks fail. Google's push channels expire. Microsoft Graph subscriptions time out. Always run a low-frequency polling job as a safety net - even a 12-hour reconciliation sweep will catch missed webhook events before customers notice.

4. Circuit breakers per provider. When Apple CalDAV goes down (it does), your entire calendar surface should not degrade. Wrap each provider client in a circuit breaker that fails open with a cached last-known-good response for read operations and a queued write for mutations.

5. Normalize once, translate late. Ingest events into your internal schema on the read path, but keep the original provider payload as a JSON blob for the first 30 days. When a customer reports a bug, you can replay the exact payload rather than reverse-engineering the mapping.

6. Explicit timezone contracts at the API boundary. Never accept a dateTime without an accompanying IANA timezone from your own product's clients. Store the two fields separately. This one rule prevents the majority of DST-related bugs (more on that below).

How to Solve the Apple Calendar Problem Without Writing a CalDAV Client

If the workarounds are not enough and your enterprise pipeline keeps stalling on "native Apple Calendar support," the build-versus-buy decision becomes real. Writing a production CalDAV client takes a senior engineer six to twelve weeks, and that is before you handle app-specific password onboarding UX, ETag-based incremental sync, and the inevitable edge cases (recurring events, time zone drift, all-day events, attendee responses).

If you absolutely must support Apple Calendar natively, the standard playbook in 2026 is to use a pass-through unified API that normalizes CalDAV into REST.

By routing calendar requests through a unified API platform like Truto, your engineering team only writes code against one standardized JSON schema. Truto exposes Apple Calendar through the exact same /calendar/events endpoint as Google Calendar and Outlook. The CalDAV XML, the app-specific password flow, and the iCalendar parsing happen on Truto's side. Your product sees a single normalized event object:

{
  "id": "evt_8f3a...",
  "provider": "apple_calendar",
  "title": "Q4 review",
  "start": { "dateTime": "2026-05-22T14:00:00Z" },
  "end":   { "dateTime": "2026-05-22T15:00:00Z" },
  "attendees": [
    { "email": "pm@acme.com", "response": "accepted" }
  ],
  "location": "Zoom",
  "recurrence": "RRULE:FREQ=WEEKLY;BYDAY=FR"
}

Because Truto's architecture is real-time pass-through, you are not storing iCloud event data on a third-party server. We translate the request in memory and pass the results directly to your application. This matters deeply for enterprise security reviews.

A factual note on infrastructure and limits: Keep in mind that whether you build this yourself or use a unified API, you are still bound by the realities of third-party infrastructure. A pass-through call to iCloud over CalDAV is slower than a Google API call (expect 300 to 800 ms round trips). Furthermore, rate limits remain the caller's problem. When an upstream API returns an HTTP 429 (Too Many Requests), Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec and passes that error directly to the caller. You are still responsible for implementing your own exponential backoff and retry logic. Unified APIs remove the protocol translation burden, but they do not magically grant infinite API quota.

For a deeper architectural comparison of pass-through versus sync-and-store calendar APIs, see our unified calendar API guide.

Unified Calendar API: Provider Feature Parity Matrix

If you are evaluating a unified calendar API for B2B SaaS products - whether that is Truto, a sync-and-cache vendor like Nylas or Cronofy, or an in-house abstraction over Google, Microsoft Graph, Calendly, and Cal.com - the first question procurement and engineering will ask is: which providers are actually supported, and at what depth?

Not every calendar provider exposes the same capabilities. A unified API can normalize the schema, but it cannot invent features the upstream provider does not have. Here is the current feature parity matrix for Truto's Unified Calendar API, expanded to include recurring rule support and observed rate-limit ceilings.

Per-Provider Caveats and Operational Considerations

The table gives you the quick answer for a procurement checklist. Here are the caveats your engineering team needs to know before they commit to a provider in production.

Google Calendar: Google's push notification channels have expiration rules. The channel can expire, and if your renewal job fails, you silently stop receiving updates. Truto manages channel lifecycle and renewal automatically, but be aware that Google's push model is "webhooks plus periodic resync" under the hood - not a fire-and-forget subscription. Operationally, watch for two failure modes: (1) domain-wide delegation misconfigurations on Workspace tenants that produce 403s only for specific users, and (2) shared calendar ACL changes that revoke write access without invalidating the OAuth token.

Microsoft Outlook (Microsoft Graph): Graph change notification subscriptions for calendar resources expire on a tight schedule - roughly every 3 days. Truto handles renewal automatically. One common gotcha for enterprise customers: hybrid Exchange environments (on-premise Exchange syncing to Microsoft 365) can introduce propagation delays that look like missing events. If your customer runs hybrid Exchange, expect edge cases around recurring event exceptions and free/busy accuracy. Also watch for Conditional Access policies revoking refresh tokens overnight - the failure mode looks identical to a user manually disconnecting.

Calendly: Calendly maps to the Unified Calendar API for Events, Availability, and Event Types, and supports webhooks for booking lifecycle events like invitee.created and invitee.canceled. It is a scheduling platform, not a general-purpose calendar - so concepts like "list all calendars" or "calendar-level CRUD" do not apply the same way they do for Google or Outlook. If your product needs to write arbitrary events (not just bookings), pair Calendly with the user's underlying Google or Microsoft account rather than treating Calendly as the calendar of record.

Cal.com: Cal.com uses API key-based authentication rather than OAuth. Truto stores and injects the key automatically, but your users will need to generate and provide their Cal.com API key during onboarding. Cal.com's API v2 covers Schedules, Event Types, Teams, and Bookings cleanly, but change detection relies on polling - there is no first-class webhook surface for calendar events comparable to Calendly's booking webhooks. If you are self-hosting Cal.com, your rate limits are effectively whatever your infrastructure supports; on the managed offering, expect standard per-key quotas.

Apple Calendar / iCloud: This is the hardest provider in the matrix. iCloud's CalDAV protocol lacks OAuth entirely - users must generate app-specific passwords via appleid.apple.com. There are no webhooks or push notifications, so polling is the only change detection path. Free/busy queries are unreliable or absent on iCloud's CalDAV implementation, and recurring event handling has known gaps. Truto can build a custom CalDAV integration on request, but it carries all the tradeoffs described earlier in this guide. Your users will have a noticeably worse connection experience than Google or Outlook.

Operational Considerations Across Providers

Regardless of provider, three operational patterns will save you incident time:

• Alert on webhook silence. If your Google push channel or Microsoft Graph subscription stops delivering events for longer than the polling fallback window, page someone. A silent webhook is worse than a failing one.
• Log token refresh outcomes per provider. Track refresh success and failure rates per provider per tenant. A 5% spike in Microsoft refresh failures usually means a Conditional Access policy change on the customer's tenant, not a bug in your code.
• Surface disconnected accounts to users within 24 hours. When an app-specific password gets revoked or a Google refresh token expires, tell the user in-product. Silent disconnects are the #1 driver of "calendar sync is broken" tickets.

How to Request New Connectors or Prioritize Apple/iCloud

If the provider you need is not in the table above, or if you need Apple Calendar support and want to skip the six-to-twelve-week CalDAV build, here is how the process works with Truto:

• New connectors are typically live within days. Truto treats every connector as declarative configuration, not custom code. If the upstream API exists and is documented, a new integration can ship in days rather than months.
• Apple/iCloud is available as a custom integration. Because CalDAV carries the tradeoffs outlined above (no OAuth, no webhooks, unreliable free/busy), Truto builds iCloud integrations on a per-customer basis so the implementation matches your specific requirements - read-only vs. read/write, polling interval, error handling for revoked app-specific passwords.
• Request process: The fastest path is a 30-minute architecture call where you walk through your calendar use cases, required providers, and compliance constraints. Truto's engineering team will confirm scope, timeline, and any provider-level limitations before you commit.

Migration Checklist: Moving From Sync-and-Cache to Pass-Through

Teams evaluating a unified calendar API for B2B SaaS products often start with a sync-and-cache vendor and later reconsider once cache staleness, compliance overhead, or per-user pricing hits scale. Whether you are moving to Truto or building the pass-through model in-house, the migration follows the same steps. Below is a checklist you can run against your codebase before you flip production traffic.

1. Audit your cached fields

List every calendar field your product currently reads from the vendor's cache: event ID, start/end, attendees, response status, description, location, extended properties, conference data, provider-specific IDs. Flag any field that only exists in the vendor's normalized schema (not in Google, Microsoft, Calendly, Cal.com, or Apple's raw payloads). Those are cache-only enrichments that you will need to re-derive at runtime under a pass-through model.

2. Map legacy IDs to unified IDs

Sync-and-cache vendors mint their own event IDs and store the upstream provider ID as a secondary field. Pass-through APIs typically expose the upstream provider ID directly, sometimes with a stable unified ID as an alias. Build a mapping table before cutover:

legacy_event_id  →  provider_native_id  →  unified_id

Keep this table for at least one billing cycle so historical references (audit logs, email notifications, deep links in customer inboxes) still resolve after cutover.

3. Reconcile stale data

Sync-and-cache products almost always contain stale records: users who revoked access weeks ago, events that were deleted upstream but never purged, attendee response statuses that never got updated after the last webhook delivery failure. Run a reconciliation pass against the live upstream provider before flipping traffic. Anything the provider does not return is stale by definition and should be soft-deleted from your side.

4. Re-authenticate users where required

OAuth refresh tokens issued to a sync-and-cache vendor cannot be handed to a pass-through platform - the token is scoped to the original client ID. Users will need to reconnect their calendars. Minimize disruption by:

• Running dual-write for two weeks: keep the old vendor connected as read-only, connect the new pass-through platform in parallel, and show users a subtle "reconnect for faster sync" banner rather than a hard block.
• Batching reconnect prompts by cohort. Prioritize highest-value accounts first so your CS team can hand-hold them if anything breaks.
• Preserving user preferences (default calendar, notification settings, sync scope) in your own database so they survive the reconnect flow.

5. Rewire webhooks and change detection

Sync-and-cache vendors emit their own webhook events (event.created, event.updated) after they receive the upstream change. Pass-through platforms forward the provider's native change notifications, normalized into a consistent shape. If your handlers depend on the vendor's exact event payload, update the schema mapping before you switch webhook URLs. Send a synthetic event through both pipelines and diff the outputs to confirm parity before cutting over.

6. Update rate-limit and retry logic

A pass-through model exposes the upstream provider's rate limits directly. If you were previously insulated by the vendor's aggregate quota, you may hit provider limits sooner during heavy operations (initial calendar import, bulk event creation for a new customer, calendar-wide edits). Add exponential backoff with jitter and honor the ratelimit-reset header. Budget a 2x safety factor on any batch job you inherit from the cached model.

7. Purge the cache after verification

Once the pass-through path serves 100% of production traffic and you have at least seven days of clean logs, delete the cached event data from your old vendor and from any intermediate stores in your own infrastructure. Enterprise security teams will thank you at the next SOC 2 review, and you eliminate an entire class of data-freshness bugs.

Real-World Examples: Handling Recurring Events and Timezones

Two edge cases break more calendar integrations than any others: recurring event exceptions and timezone drift. Any unified calendar API you evaluate should have opinionated, tested behavior for both. Here is what "correct" looks like in practice.

Recurring Events With Exceptions

Suppose a user creates a weekly recurring event: "Team Standup, every Friday at 9:00 AM ET, indefinitely." Two weeks in, they move the third occurrence to 10:00 AM and cancel the fifth. The underlying data model looks like this:

{
  "id": "evt_master",
  "title": "Team Standup",
  "recurrence": "RRULE:FREQ=WEEKLY;BYDAY=FR",
  "start": {
    "dateTime": "2026-01-02T09:00:00",
    "timeZone": "America/New_York"
  }
}

Then two override entries hanging off the master:

[
  {
    "id": "evt_override_3",
    "recurringEventId": "evt_master",
    "originalStart": "2026-01-16T09:00:00",
    "start": { "dateTime": "2026-01-16T10:00:00", "timeZone": "America/New_York" }
  },
  {
    "id": "evt_override_5",
    "recurringEventId": "evt_master",
    "originalStart": "2026-01-30T09:00:00",
    "status": "cancelled"
  }
]

Google Calendar and Microsoft Graph both support this master-plus-exceptions pattern natively, but they expose it slightly differently. Google returns the series master plus separate instance overrides via events.instances. Microsoft returns the series master with exceptions referenced by seriesMasterId. Apple CalDAV bundles everything into one VEVENT block with EXDATE and RECURRENCE-ID properties inside the iCalendar payload. Calendly and Cal.com do not model recurrence natively at all - each booking is a single instance.

A unified calendar API should return the master event with an RRULE string plus a normalized exceptions array, regardless of provider. When your product edits the third occurrence, the unified layer translates that into a Google instance update, a Graph exception PATCH, or a CalDAV PUT on the modified VEVENT inside VCALENDAR.

Gotcha to test in production: editing "this event and all following" versus "this event only" produces different write paths on every provider.

• Google splits the RRULE into two series (ends the original with UNTIL, creates a new one starting from the edit point).
• Microsoft creates an exception plus modifies the series master's recurrence window.
• Apple modifies the RRULE end date on the master VEVENT and rewrites the entire VCALENDAR blob.

If your UI offers both "edit series" and "edit occurrence," write integration tests for both branches against every provider you support. This is the single most common source of "my recurring meeting disappeared" bug reports.

Timezone Handling and DST Transitions

Timezones are where naive calendar integrations lose data. Three patterns to handle explicitly:

1. Floating times (all-day events). "Alice's Birthday" has no timezone. It should render as the same date in Tokyo and Toronto. Store these with a date field, not dateTime - conflating the two produces 24-hour drift on international teams. Every provider distinguishes these; make sure your unified schema does too.

2. DST transitions on recurring events. A weekly meeting at "9:00 AM America/New_York" is at 14:00 UTC in winter and 13:00 UTC in summer. Store recurring event start times as local time plus a named IANA timezone, never as a fixed UTC offset. If you cache the UTC value at event creation and never recompute, the meeting will drift by an hour twice a year. This is the bug that quietly breaks European-American team standups every March and November.

3. Cross-timezone attendees. An event at 9:00 AM ET should render as 3:00 PM CET for a Berlin attendee. This is a rendering concern, not a storage concern. Store the organizer's local time and IANA zone, then convert on read for each viewer.

The correct on-the-wire representation:

{
  "start": {
    "dateTime": "2026-03-06T09:00:00",
    "timeZone": "America/New_York"
  }
}

Notice the absence of a Z or explicit UTC offset on dateTime. That is intentional - the timeZone field is the source of truth, and the wall-clock value gets resolved at render time. Any unified calendar API worth using will preserve this distinction round-trip.

Provider quirks that will bite you:

• Google Calendar treats the timeZone field as authoritative but also returns computed UTC values in the same payload. Trust the timezone field, not the UTC computation, when applying edits to recurring events.
• Microsoft Graph requires a Prefer: outlook.timezone="America/New_York" header on read requests, or it returns events converted to UTC by default, losing the organizer's original zone. Truto sets this header transparently.
• Apple CalDAV stores timezone data inline in the VCALENDAR payload as VTIMEZONE blocks. If your iCalendar parser skips VTIMEZONE, DST calculations for years past 2038 will silently break because the parser will fall back to a default zone.
• Cal.com stores event type default timezones on the schedule, not the booking, so a booking made "in the user's timezone" resolves against the schedule config at read time. Always fetch the schedule alongside the booking if you need to reason about local time.

Getting these right end-to-end is where a unified calendar API earns its keep. If your team is doing the mapping in-house against Google, Microsoft, Calendly, Cal.com, and Apple simultaneously, you will re-litigate every one of these edge cases per provider.

Your Next 30 Days

If you are a PM staring at an Apple Calendar feature request that has been open for nine months, here is the order of operations that actually moves the needle:

1. Publish the FAQ page this sprint: Even without native support, an honest, public page deflects tickets and signals technical maturity to enterprise buyers.
2. Ship Workaround 1 documentation: A how-to article with screenshots for Google-routed sync solves most user requests at zero engineering cost.
3. Instrument the demand: Add an "I need Apple Calendar" upvote button to the FAQ. Use the data to justify priority to engineering.
4. Evaluate build vs buy: Once upvotes cross your internal threshold, get a unified API demo before you green-light a six-month CalDAV project. For a structured argument you can take into the engineering review, see the PM's playbook for pitching integration tools to engineering.

Apple Calendar support does not have to be the integration that breaks your engineering team. CalDAV is not going anywhere, and Apple has shown no interest in shipping a REST API. Provide clear, honest FAQ documentation for the workarounds, and when the revenue justifies native support, abstract the CalDAV complexity away entirely.