About the External Calendars API

The External Calendars API enables an app 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 List Providers to find out whether to connect with a provider using Connect By OAuth or Connect By Credentials.
  • A connection’s syncConfig property contains settings for the external calendar connection, including whether importing and/or exporting of calendar events is enabled.

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.
Was this helpful?
Yes
No

Sample Flows

This article shares a possible use case your implementation could support, as well as a sample flow. You're not limited to this use case, but it can be a helpful jumping off point for your planing.

Check which connection method to use for a provider

External calendar providers use different methods for authenticating a connection. Some use an OAuth flow, while others require a user’s credentials (email address and password). To check the appropriate connection method for a provider:

  1. Call the List Providers endpoint to retrieve details about all supported external calendar providers.
  2. The response contains an array with details about each external calendar provider. Find the provider you want to connect with.
  3. Save the id for the provider you want to connect with.
  4. Check the features.connectMethods array for the chosen provider. If the array contains OAUTH, you can connect by OAuth. If the array contains CREDENTIALS, you can connect by credentials.

Connect an external calendar by credentials

Before you can sync events with a Wix site user’s external calendar, you need to establish a connection with the external calendar. If the external provider supports connecting by credentials, create the connection as follows:

  1. Get the email address and password associated with the external calendar account from the user.
  2. If you don’t already have the ID of the external calendar provider you want to connect to, use List Providers to get it.
  3. Use List Schedules to get the ID for the schedule to connect the external calendar with.
  4. Call the Connect By Credentials endpoint with the details and credentials you’ve collected.
  5. The response includes a connection object with details of the new external calendar connection. If the connection was established successfully, the connection’s status is CONNECTED.
  6. Use Update Sync Config to configure the connection and enable importing and/or exporting events.

Connect an external calendar by OAuth

Before you can sync events with a Wix site user’s external calendar, you need to establish a connection with the external calendar. If the external provider supports connecting by OAuth, create the connection as follows:

  1. If you don’t already have the ID of the external calendar provider you want to connect to, use List Providers to get it.
  2. Use List Schedules to get the ID for the schedule to connect the external calendar with.
  3. Call the Connect By OAuth endpoint using the details you’ve collected. The redirectUrl parameter should include the URL the user is redirected to after authorizing access to their external calendar.
  4. The response includes a URL for the external calendar authorization page. Redirect the user to this page.
  5. The user authorizes access to their external calendar.
  6. The connection is now established. The user is redirected to the URL provided in redirectUrl, with the connection ID as a query parameter.
  7. Retrieve details about the newly established external calendar connection, including its ID, using the Get Connection endpoint.
  8. Use Update Sync Config to configure the connection and enable importing and/or exporting events.

Retrieve a list of events in connected external calendars

To retrieve an aggregated list of events in connected external calendars during a particular time range:

  1. Create a connection with each of the user’s external calendars, following the steps above.
  2. Use the List Events endpoint with the relevant start and end times to retrieve an aggregated list of events in all the user’s connected external calendars.
Was this helpful?
Yes
No

External Calendar Object

Was this helpful?
Yes
No

GetList Providers

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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 Connect By Credentials or Connect By OAuth to establish a connection.

Endpoint
GET
https://www.wixapis.com/bookings/v2/external-calendars/providers

Was this helpful?
Yes
No

GetGet Connection

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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.

Endpoint
GET
https://www.wixapis.com/bookings/v2/external-calendars/connections/{connectionId}

Was this helpful?
Yes
No

GetList Connections

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a list of external calendar connections.

Each external calendar connections contains 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.

Endpoint
GET
https://www.wixapis.com/bookings/v2/external-calendars/connections

Was this helpful?
Yes
No

PostConnect By O Auth

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Connects to an external calendar using the OAuth authorization protocol.

The authorization flow should take place as follows:

  1. Send a request to the endpoint 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 body 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 body 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 List Events to obtain an up-to-date list of events in the connected external calendars.

This endpoint validates that the specified schedule is owned by the Wix user connecting the calendar, or that the caller has the Manage External Calendars or Manage Business Calendar permission scope.

If the schedule's ownership changes, the connection to the external calendar is automatically disconnected.

Note: Use List Providers to find out whether to connect to a particular provider using this endpoint or Connect by Credentials.

Endpoint
POST
https://www.wixapis.com/bookings/v2/external-calendars/connections:connectByOAuth

Was this helpful?
Yes
No

PostConnect By Credentials

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

Once a connection is successfully created, use List Events to obtain an up-to-date list of events in the connected external calendars.

This endpoint validates that the specified schedule is owned by the Wix user connecting the calendar, or that the caller has the Manage External Calendars or Manage Business Calendar permission scope.

If the schedule's ownership changes, the connection to the external calendar is automatically disconnected.

Note: Use List Providers to find out whether to connect to a particular provider using this endpoint or Connect by OAuth.

Endpoint
POST
https://www.wixapis.com/bookings/v2/external-calendars/connections:connectByCredentials

Was this helpful?
Yes
No

GetList Calendars

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

Note: Before using this endpoint, establish a connection with an external calendar using Connect By Credentials or Connect By OAuth.

Endpoint
GET
https://www.wixapis.com/bookings/v2/external-calendars/connections/{connectionId}/calendars

Was this helpful?
Yes
No

PatchUpdate Sync Config

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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 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 Get Connection or List Connections and see the syncConfig property.

Note: Supported functionality depends on the provider. Use List Providers to see details about providers' supported features.

Endpoint
PATCH
https://www.wixapis.com/bookings/v2/external-calendars/connections/{connectionId}/sync-config

Was this helpful?
Yes
No

PostDisconnect

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Disconnects from an external calendar.

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

After disconnecting, List Events no longer returns events from the disconnected external calendar. Exported Wix calendar sessions are deleted from the external calendar.

Endpoint
POST
https://www.wixapis.com/bookings/v2/external-calendars/connections/{connectionId}/disconnect

Was this helpful?
Yes
No

GetList Events

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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 endpoint, establish a connection with an external calendar using Connect By Credentials or Connect By OAuth.

Endpoint
GET
https://www.wixapis.com/bookings/v2/external-calendars/events

Was this helpful?
Yes
No