Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

ID of the external calendar provider. Find this with the [`listProviders()`](#list-providers) function.

providerId

string

ID of the schedule to connect with the external calendar account.

scheduleId

Email address for the external calendar account.

email

Password for the external calendar account.

password

Connects to an external calendar by directly providing the external calendar account credentials.


Once a connection is successfully created, use [`listEvents()`](#list-events) to obtain an up-to-date list of events in the connected external calendars.

> **Note:**
> Use [`listProviders()`](#list-providers) to find out whether to connect to a particular provider using this method or [`connectByOAuth()`](#connect-by-o-auth).

import {externalCalendars} from 'wix-bookings.v2';

async function connectByCredentials(providerId, scheduleId, email, password) {
    const {connection} =
        await externalCalendars.connectByCredentials(providerId, scheduleId, email, password)
    return connection
}

Connect with an external calendar by credentials  

connectByCredentials

ConnectByCredentialsResponse

URL to redirect the user to after they authorize access to the external calendar account.

If the connection is successfully established, the user is redirected to this URL with a query parameter `connectionId` containing the new connection ID.
If the attempt to connect fails, the user is redirected to this URL with a query parameter `error` containing the error type.

redirectUrl

options

ConnectByOAuthOptions

Connects to an external calendar using the OAuth authorization protocol.


The authorization flow should take place as follows:

1. Call the function with the appropriate parameters.
2. Redirect the user to the URL received in the response.
3. The user authorizes access.
4. The user is redirected to the URL you provide in the `redirectUrl` parameter, with a query parameter `connectionId` containing the new connection ID.

If the attempt to connect fails, the user is still redirected to the URL you provide in the `redirectUrl` parameter,
but with a query parameter `error` containing one of the following values:

- `reject`: The user rejected the authorization request.
- `unsupported`: Connecting to the user's external account type is not supported by the provider.
- `internal`: An error unrelated to the client or the request that prevents the server from fulfilling the request.

Once a connection is successfully created, use [`listEvents()`](#list-events) to obtain an up-to-date list of events in the connected external calendars.

> **Note:**
> Use [`listProviders()`](#list-providers) to find out whether to connect to a particular provider using this endpoint or [`connectByCredentials()`](#connect-by-credentials).

import {externalCalendars} from 'wix-bookings.v2';

async function connectByOAuth(providerId, scheduleId, redirectUrl) {
    const {oauthUrl} =
        await externalCalendars.connectByOAuth(providerId, scheduleId, redirectUrl)
    return oauthUrl
}

Connect with an external calendar by OAuth  

connectByOAuth

ConnectByOAuthResponse

ID of the external calendar connection to disconnect.

connectionId

Disconnects from an external calendar.


When an external calendar is disconnected, the external calendar connection's `status` is changed to `DISCONNECTED`.

After disconnecting, [`listEvents()`](#list-events) no longer returns events from the disconnected external calendar.
Exported Wix calendar sessions are deleted from the external calendar.

import {externalCalendars} from 'wix-bookings.v2';

async function disconnect(connectionId) {
    const {connection: updatedConnection} =
        await externalCalendars.disconnect(connectionId)
    return updatedConnection
}

Disconnect an external calendar connection  

disconnect

DisconnectResponse

Retrieves an external calendar connection by ID.


The external calendar connection contains details of the connection between a Wix site's calendar and calendars hosted by an external provider.

The `syncConfig` property contains configuration details for importing events from an external calendar, exporting events to an external calendar, or both.

import {externalCalendars} from 'wix-bookings.v2';

async function getConnection(connectionId) {
    const {connection} = await externalCalendars.getConnection(connectionId)
    return connection
}

Get an external calendar connection by ID 

getConnection

GetConnectionResponse

ID of the external calendar connection to list calendars for.

Retrieves a list of calendars belonging to the connected external calendar account.


> **Note:**
> Before using this function, establish a connection with an external calendar using [`connectByCredentials()`](#connect-by-credentials) or [`connectByOAuth()`](#connect-by-o-auth).

import {externalCalendars} from 'wix-bookings.v2';

async function listCalendars(connectionId) {
    const {calendars} = await externalCalendars.listCalendars(connectionId)
    return calendars
}

List calendars belonging to an external calendar account  

listCalendars

ListCalendarsResponse

ListConnectionsOptions

Retrieves a list of external calendar connections.


Each external calendar connections contain details of a connection between a Wix site's calendar and calendars hosted by an external provider.

The `syncConfig` property of each connection contains configuration details for importing events from an external calendar, exporting events to an external calendar, or both.

import {externalCalendars} from 'wix-bookings.v2';

async function listConnections() {
    const {connections} = await externalCalendars.listConnections()
    return connections
}

List all connections 

import {externalCalendars} from 'wix-bookings.v2';

async function listConnections(scheduleId) {
    const options = {
        scheduleId
    }
    const {connections} = await externalCalendars.listConnections(options)
    return connections
}

List connections by schedule ID  

listConnections

ListConnectionsResponse

ListEventsOptions

Retrieves a list of events from all connected external calendars, based on the provided filtering and paging.


Use List Events to retrieve an aggregated list of events in the connected external calendars for a specified time range, sorted by start date.

> **Note:**
> Before using this function, establish a connection with an external calendar using [`connectByCredentials()`](#connect-by-credentials) or [`connectByOAuth()`](#connect-by-o-auth).

import {externalCalendars} from 'wix-bookings.v2';

async function listEvents() {
    const options = {
        from: '2023-01-01T00:00:00Z',
        to: '2023-01-07T00:00:00Z'
    }
    const {events} = await externalCalendars.listEvents(options)
    return events
}

List all events within a time range  

import {externalCalendars} from 'wix-bookings.v2';

async function listScheduleEvents(from, to) {
    const options = {
        from,
        to,
        scheduleId: 'b936298d-18a6-4ae8-8e9f-10bf49314c95'
    }
    const {events: eventsOfSchedule} = await externalCalendars.listEvents(options)
    return eventsOfSchedule
}

List events connected to a specified schedule  

import {externalCalendars} from 'wix-bookings.v2';

async function listEventsWithPI(from, to) {
    const options = {
        from,
        to,
        fieldsets: ['OWN_PI']
    }
    const {events: eventsWithPI} = await externalCalendars.listEvents(options)
    return eventsWithPI
}

List events including personal information  

listEvents

ListEventsResponse

Retrieves a list of the external calendar providers for which the site supports integration.


The list of external calendar providers includes:

+ External calendar providers that are supported by default, such as Google, Apple, and Microsoft.
+ External calenders for which the site owner has enabled integration by installing an app.

For each external calendar provider, the list contains information about supported connection methods and features.
For each provider, check `features.connectMethods` to find out whether to use [`connectByCredentials()`](#connect-by-credentials) or [`connectByOAuth()`](#connect-by-o-auth) to establish a connection.

import {externalCalendars} from 'wix-bookings.v2';

async function listProviders() {
    const {providers} = await externalCalendars.listProviders()
    return providers
}

List the supported external calendar providers 

listProviders

ListProvidersResponse

ID of the external calendar connection to update.

syncConfig

ConnectionSyncConfig

UpdateSyncConfigOptions

Updates the specified external calendar connection's sync configuration.


Use Update Sync Config to update a connection's `syncConfig` property.
The `syncConfig` property contains settings for enabling, configuring, or disabling functionality, including:

+ Importing events from one or more specified calendars in the connected external calendar account. If this is enabled, use [`listEvents()`](#list-events) to retrieve a list of events from the external calendar.
+ Exporting events from the Wix site's calendar to an external calendar.

To see an external calendar connection's existing sync configuration, use [`getConnection()`](#get-connection) or [`listConnections()`](#list-connections) and see the `syncConfig` property.

> **Note:**
> Supported functionality depends on the provider. Use [`listProviders()`](#list-providers) to see details about providers' supported features.

import {externalCalendars} from 'wix-bookings.v2';

async function updateSyncConfig(connectionId) {
    const syncConfig = {
        listEventFromCalendars: {
            enabled: true,
            calendars: {
                calendars: [
                    {
                        id: 'a68yu6lp6584z66zorp19z1ab'
                    },
                    {
                        id: '4xve0tohyhnrlzy3lp4zf7b07'
                    }
                ]
            }
        }
    }
    const {connection: updatedConnection} =
        await externalCalendars.updateSyncConfig(connectionId, syncConfig)
    return updatedConnection
}

Update connection to list events from specific external account calendars  

import {externalCalendars} from 'wix-bookings.v2';

async function updateSyncConfig(connectionId) {
    const syncConfig = {
        syncToCalendar: {
            enabled: true,
            dedicatedCalendar: {}
        }
    }
    const {connection: updatedConnection} =
        await externalCalendars.updateSyncConfig(connectionId, syncConfig)
    return updatedConnection
}

Update connection to sync events to a new dedicated external account calendar  

updateSyncConfig

UpdateSyncConfigResponse

---
title: Introduction
---

# About the External Calendars API


&nbsp;

<div style="background-color: #FEF1D1; padding: 18px 24px; border-radius: 6px; border: 1px solid #FDB10C; box-sizing: border-box; display: inline-block">
  <b>Developer Preview</b>
    <br/>
    <span>APIs in <a href="https://www.wix.com/velo/reference/api-overview/developer-preview">Developer Preview</a> are subject to change and are not intended for use in production.<br/><a href="mailto:velo-preview-feedback@wix.com">Send us</a> your suggestions for improving this API. Your feedback is valuable to us.</span>
</div>

&nbsp;


The External Calendars API enables you to connect and sync a Wix site with external calendars.

With External Calendars, you can:

+ Establish a connection between a Wix site and an external calendar account.
+ Import events to a Wix site from a connected external calendar.
+ Export events from a Wix site's calendar to a connected external calendar.
+ Retrieve information about calendars belonging to an external calendar account.
+ Retrieve information about support for external calendar providers. 

The External Calendars API provides built-in support for Google, Microsoft, and Apple calendars. Integration with additional external calendars can be enabled by installing a calendar integration app from the Wix App Market.

## Before you begin

It’s important to note the following points before starting to code:

+ External calendar providers have different requirements for authentication. Use [`listProviders()`](#listProviders) to find out whether to connect with a provider using [`connectByOAuth()`](#connectByOAuth) or [`connectByCredentials()`](#connectByCredentials).
+ A connection’s `syncConfig` property contains settings for the external calendar connection, including whether importing and/or exporting of calendar events is enabled.
* Only site collaborators with [Bookings roles](https://support.wix.com/en/article/roles-permissions-overview) can book or edit their bookings. You can override the permissions with the [`elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.


## Terminology

+ **External calendar**: A calender hosted by a third-party calendar service.
+ **External calendar provider**: The third-party service providing an external calendar. For example: Google, Apple, or Microsoft.
+ **External calendar connection**: A linkage established between a Wix site’s calendar and one or more external calendars, to enable importing and/or exporting calendar events.
+ **Event**: A single session or recurring session instance that appears in a specific block of time in a calendar, such as an appointment or class.
+ **Schedule**: Collection of all sessions that belong to the same class, course, appointment, or resource in a Wix site's calendar.

To use the External Calendars API, import `{ externalCalendars }` from the `wix-bookings.v2` module:

```javascript
import { externalCalendars } from 'wix-bookings.v2';
```

velo-deps_wix-bookings.v2_external-calendars

Calendar

Display name of the external calendar.
For example, "Primary" or "Birthdays".

name

CalendarType

Calendars

calendars

connection

Connection

URL of the external calendar authorization page to redirect the user to.

oauthUrl

ConnectMethod

ID of the Wix App the external calendar connection belongs to.

appId

calendarType

Reason for the error, if `status` is `ERROR`.

+ `TOKEN_REVOKED`: External calendar access token revoked.
+ `EXTERNAL_CALENDAR_CREATION_FAILED`: External calendar creation failed.
+ `EXTERNAL_CALENDAR_DELETED`: External calendar was deleted.

errorReason

ErrorReason

Email address associated with the external calendar account. Empty until sync is completed successfully.

externalAccountEmail

ID of the schedule connected to the external calendar.

Connection status.

+ `CONNECTED`: A connection has been established with the external calendar.
+ `SYNC_IN_PROGRESS`: A sync is in progress.
+ `SYNCED`: External calendar sync complete.
+ `DISCONNECTED`: External calendar has been disconnected.
+ `ERROR`: An error occurred when syncing with the external calendar.

status

Status

Sync configuration. Contains settings for enabling, configuring, or disabling functionality, including:

+ Importing events from one or more specified calendars in the connected external calendar account.
+ Exporting events from the Wix site's calendar to an external calendar.

ID of the Wix user the external calendar connection belongs to.

userId

Configuration for importing events from external calendars.
If enabled, use the [`listEvents()`](#list-events) function to retrieve a list of events from external calendars.

listEventFromCalendars

ConnectionSyncConfigListEventFromCalendars

Configuration for exporting calendars from the Wix site's calendar to a connected external calendar.

syncToCalendar

ConnectionSyncConfigSyncToCalendar

Import events from a list of specified external calendars.

**Note**: The list can include the primary calendar.

Import events only from the primary external calendar. Enable this by passing an empty object.

**Note**: Not all external calendar providers designate a primary calendar.

primaryCalendar

Whether to enable importing events from external calendars through this connection.

enabled

boolean

Sync to a dedicated external calendar. Enable this by passing an empty object.

dedicatedCalendar

Sync to the primary external calendar. Enable this by passing an empty object.

Whether to enable exporting events to an external calendars through this connection.

CursorPaging

Pointer to the next or previous page in the list of results.

You can get the relevant cursor token
from the `pagingMetadata` object in the previous call's response.
Not relevant for the first request.

cursor

limit

number

CursorPagingMetadata

Number of items returned in the response.

count

cursors

Cursors

Indicates if there are more results after the current page.
If `true`, another page of results can be retrieved.
If `false`, this is the last page.

hasNext

Cursor pointing to next page in the list of results.

DedicatedCalendar

Event

Whether the event is an all-day event.

Default: `false`

allDay

calendarName

End date and time of the event (exclusive), formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt).

ID of the schedule connected to the external calendar the event belongs to.

ID of the Wix user the schedule belongs to.
For example, the ID of the staff member (resource) who owns the schedule.

scheduleOwnerId

Name of the Wix user the schedule belongs to.
For example, the name of the staff member (resource) who owns the schedule.

scheduleOwnerName

Start date and time of the event (inclusive), formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt).

start

title

HeadersEntry

value

List of calendars belonging to the external calendar account.

Whether to return a partial list of connections if details can't be retrieved for some connections.

Default: `false`

partialFailure

Schedule IDs to filter by. If provided, only connections between external calendars and the specified schedules is returned.

Default: Returns all connections.

scheduleIds

connections

List of provider IDs for connections for which retrieval failed. Returned only if `partialFailure` parameter is `true` in the request.

failedProviderIds

ListEventFromCalendars

Whether to include only all-day events in the returned list.
If `true`, only all-day events are returned.
If `false`, only events with a specified time are returned.

Default: All events are returned.

cursorPaging

Predefined sets of fields to return.
- `NO_PI`: Returns event objects without personal information.
- `OWN_PI`: Returns complete event objects, including personal information.

Default: `NO_PI`

fieldsets

Date and time from which to retrieve events,
formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt).
Required, unless `cursorPaging.cursor` is provided.

Events which start before the `from` time and end after it are included in the returned list.

from

Whether to return a partial list of events if details can't be retrieved for some connections.

Default: `false`

Schedule IDs to filter by. If provided, the returned list includes only events belonging to external calendars connected to the specified schedules.
Maximum of 100 schedule IDs per request.

Date and time until which to retrieve events,
formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt).
Required, unless `cursorPaging.cursor` is provided.

Events which start before the `to` time and end after it are included in the returned list.

Wix user IDs to filter by. If provided, the returned list includes only events belonging to external calendars connected to schedules belonging to the specified Wix users.
Maximum of 100 Wix user IDs per request.

userIds

List of external calendar events matching the filters.

events

List of provider IDs for connections for which retrieval of events failed. Returned only if `partialFailure` parameter is `true` in the request.

pagingMetadata

providers

OAuthCompletedOptions

body

headers

method

pathParams

queryParams

rawPath

rawQuery

PathParametersEntry

PrimaryCalendar

Provider

Features the external calendar provider supports.

features

ProviderFeatures

Supported connection methods.

For providers supporting `OAUTH`, connect with the [`connectByOAuth()`](#connect-by-o-auth) function.
For providers supporting `CREDENTIALS`, connect with the [`connectByCredentials()`](#connect-by-credentials) function.

connectMethods

Whether events can be imported from external calendars to the Wix calendar.

+ `NOT_SUPPORTED`: Importing events from the external calendar is not supported.
+ `PRIMARY_CALENDAR_ONLY`: Events can be imported only from an external calendar designated as primary.
+ `SPECIFIC_CALENDARS`: Events can be imported from specific external calendars. Use [`listCalendars()`](#list-calendars) to get a list of calendars for a connected external calendar account.

Whether Wix calendar sessions can be exported to the external calendar.

+ `NOT_SUPPORTED`: Exporting events to an external calendar is not supported.
+ `PRIMARY_CALENDAR_ONLY`: Events can only be exported only to an external calendar designated as primary.
+ `SPECIFIC_CALENDARS`: Events can be exported to specific external calendars. Use [`listCalendars()`](#list-calendars) to get a list of calendars for a connected external calendar account.
+ `DEDICATED_CALENDAR`: Events can be exported to a newly created, dedicated external calendar in the connected external calendar account.

listConnections( )

Permission Scopes