Provider options

The shared event shape covers what every calendar has in common, and the order a booking came from isn't one of those things. For anything provider-specific, like tagging a Google event with its order id or setting Outlook's categories, pass providerOptions and read providerMetadata. Both are keyed by provider id.

import { createEvent } from '@cal-sdk/core';
import { google } from '@cal-sdk/google';

const calendar = google({ accessToken });

const { event } = await createEvent({
  calendar,
  event: {
    title: 'Order 42 handover',
    start: { dateTime: '2026-11-09T15:00:00Z', timeZone: 'UTC' },
    end: { dateTime: '2026-11-09T15:30:00Z', timeZone: 'UTC' },
  },
  providerOptions: {
    google: {
      guestsCanModify: true,
      extendedProperties: { private: { orderId: '42' } },
    },
  },
});

event.providerMetadata?.google?.extendedProperties?.private?.orderId; // '42'

Typed by the providerCopy Anchor Link

The types follow the provider you pass as calendar, so your editor knows which options exist. A typo, an option the provider doesn't take for this function, or another provider's key is a type error:

await createEvent({
  calendar, // google(...)
  event: input,
  providerOptions: {
    // Type error: Google has no `guestsCanModfy` option.
    google: { guestsCanModfy: true },
  },
});

Providers check options at runtime too, because options don't always come from code TypeScript has seen. A wrong value, such as a string where Google wants a boolean, throws InvalidArgumentError before any request. An unknown key is dropped with an unsupported warning rather than failing the call.

Often you don't know the provider at compile time, because a function returns Google or Outlook depending on what the user connected. When the provider type is a union like that, each provider's key is allowed, and at runtime each provider reads only its own:

await createEvent({
  calendar, // GoogleCalendarProvider | MicrosoftCalendarProvider
  event,
  providerOptions: {
    google: { guestsCanModify: true },
    microsoft: { importance: 'high' },
  },
});

Options by providerCopy Anchor Link

CalDAV, Zoom, ICS and the mock take no options.

Metadata by providerCopy Anchor Link

Each provider page explains its options.