Get to know our frameworks

Select an app template built on your preferred framework.

Build apps on our native app editor. Use drag and drop elements, Velo code and Wix APIs to develop custom features.

Streamline your app development process with the Wix CLI. Get a familiar developer experience with minimal setup and configuration.

Take full control over your app's tech stack, deployment, and hosting.

App templates

Wix Blocks templates

Wix CLI templates

Self-hosted templates

Kickstart your app development with templates built on your preferred Wix developer tool. Browse templates for practical foundation and get to know the Wix ecosystem.

Wix App Templates for Developers

This example apps can be used as a starting point for building your own app, for concrete examples of how to use Wix framework, or for inspiration.

Choose a template.<0 />Build an app.

Browse by:

How to build it step by step:

This template is built with:

Read how this template was built, step by step.

How we built this template

Deployment instructions:

Choose a package manager and run the command in your terminal.

Copy command

Before you get started, make sure you have the following:

Prerequisite steps

Get started with Wix CLI

Begin by setting up your Next.js project with your preferred hosting platform.

Select your hosting service

Start the deployment flow and set up your template repo on Netlify. After you finish set up, come back here and add your Netlify custom domain.

Copy the code from our Git repo to deploy your app on any platform that supports Next.js.

Start the deployment flow and set up your template repo on Vercel. After you finish set up, come back here and add your Vercel generated URL.

Add the base URL and give your app a name.

App details

Go to the app dashboard and test your app to ensure a smooth integration within the Wix ecosystem. <0>Learn more about app checks and testing</0>

Define your environment

Terminal

Related templates

Note

Warning

Your app name will be used as the namespace suffix.

Name your app to generate a namespace. This lets you refer to your app in code later on.

Go Headless

Build Apps

Client

API Preview

Ricos

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.

updateSyncConfig( )