# Provider options (https://www.cal-sdk.com/docs/guides/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.

```ts
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 provider [#typed-by-the-provider]

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:

```ts
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:

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

## Options by provider [#options-by-provider]

| Provider    | Functions                                   | Options |
| ----------- | ------------------------------------------- | ------- |
| `google`    | `createEvent`, `updateEvent`                | `guestsCanModify`, `guestsCanInviteOthers`, `guestsCanSeeOtherGuests`, `extendedProperties` |
| `google`    | `listEvents`                                | `eventTypes` |
| `microsoft` | `createEvent`, `updateEvent`                | `showAs`, `importance`, `categories`, `transactionId` |
| `microsoft` | `syncEvents`                                | `timeMin`, `timeMax` |
| `calcom`    | `createEvent`                               | `eventTypeId`, `metadata`, `allowConflicts`, `allowBookingOutOfBounds` |
| `calcom`    | `updateEvent`                               | `reschedulingReason`, `allowConflicts`, `allowBookingOutOfBounds` |
| `calcom`    | `deleteEvent`                               | `cancellationReason` |
| `calendly`  | `createEvent`                               | `eventType` (required), `location` |
| `calendly`  | `deleteEvent`                               | `reason` |

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

## Metadata by provider [#metadata-by-provider]

| Provider    | `providerMetadata` on events |
| ----------- | ---------------------------- |
| `google`    | `iCalUID`, `eventType`, `extendedProperties` |
| `microsoft` | `showAs` (Outlook's own, such as `'oof'`), `importance`, `categories`, `iCalUId` |
| `calcom`    | `bookingId`, `eventTypeId`, `status`, `rescheduledFromUid`, `metadata` |
| `calendly`  | `uri`, `eventType` |
| `zoom`      | `uuid`, `occurrenceId` |

Each [provider page](/docs/providers) explains its options.