The Schedules API allows you to manage collections of events. Schedules allow you to easily manage events that are linked to the same entity, such as a Bookings service or Bookings resource. You can also create schedules for custom entities beyond the Wix ecosystem. Schedules set default values for their events, ensuring consistency across all related events.
With the Schedules API, you can:
For more in-depth scheduling management, see:
It’s important to note the following points before starting to code:
CANCELLED
, you can't reactivate, update, or associate it with new events.MASTER
event to establish the recurrence pattern.CANCELLED
.Query endpoints allow you to filter and sort results based on service properties. This article covers field support for filtering and sorting.
The following table shows field support for filters
for the schedules
object in
Query Schedules:
Field | Supported Filters |
---|---|
id | $eq , $in |
externalId | $eq , $in |
appId | $eq , $in |
status | $eq , $in |
To learn about working with Query endpoints in general, see API Query Language.
A collection of events associated with a specific entity, such as a Bookings service, or Bookings resource. Schedules can also serve as templates for the events they manage, setting default values like a default location.
Schedule ID.
Schedule name.
Min: 1 character Max: 200 characters
Schedule status.
Supported values:
ACTIVE
: You can add events to the schedule or update its fields.CANCELLED
: You can't add events to the schedule or update its fields.Default: ACTIVE
Time zone the schedule is associated with in
IANA tz database format.
For example, America/New_York
.
Default: timeZone
specified in the business site properties.
Min: 1 character Max: 150 characters
Whether the schedule's timeZone
is automatically synced from
timeZone
of the business site properties.
Default: true
Default title
for events
that are added to the schedule.
Min: 1 character Max: 200 characters
Default location
for events
that are added to the schedule.
Default totalCapacity
for events
that are added to the schedule.
Min: 0
Default conferencingDetails
for events
that are added to the schedule.
Returned only if explicitly requested. For more details, see the permissions article.
ID of the app that's associated with the schedule. You can't update appId
.
If you want to create a schedule and ensure its associated events appear
in the Bookings calendar,
you must provide the Wix Bookings app ID
13d21c63-b5ec-5912-8397-c3a5ddb27a97
.
List of permissions associated with the schedule. Refer to the permissions article for more information.
Max: 1 permission
Extensions enabling applications or users to save custom data related to the schedule.
Revision number, which increments by 1 each time the schedule is updated. To prevent conflicting changes, the current revision must be passed when updating the schedule. Ignored when creating a schedule.
Date the schedule was created in YYYY-MM-DDThh:mm:ss.sssZ
format.
Date the schedule was last updated in YYYY-MM-DDThh:mm:ss.sssZ
format.
{
"id": "2bdfa45b-db0b-4eb6-9a27-f992131c4e2c",
"externalId": "3088c13d-5ed7-4a25-9c3a-13de32fd8a84",
"name": "Cooking Workshop",
"status": "ACTIVE",
"timeZone": "Europe/Dublin",
"businessTimeZoneEnabled": true,
"defaultTitle": "Cooking Workshop",
"defaultLocation": {
"type": "BUSINESS"
},
"defaultCapacity": 10,
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
"permissions": [],
"revision": "2",
"createdDate": "2024-10-06T10:46:53.377Z",
"updatedDate": "2024-10-06T10:47:12.581Z"
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a schedule.
ID of the schedule to retrieve.
Information about which fields containing personal data to return. Refer to the permissions article for more information.
Supported values:
PI_FIELDS
: Returns all fields with personal data. Your app must have Read Calendars - Including PI
or Manage Calendars
permission scope.OWN_PI_FIELDS
: Returns only fields containing your own personal data.Max: 1 field Default: No personal data is returned.
Retrieved schedule.
curl -X GET \
'https://www.wixapis.com/calendar/v3/schedules/37e01b7f-7137-4c06-bca5-02eb435c1503' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>'
{
"schedule": {
"id": "37e01b7f-7137-4c06-bca5-02eb435c1503",
"externalId": "38e25e56-d50f-42b4-a3b6-aa04c61dded1",
"name": "Full Body Strength",
"status": "ACTIVE",
"timeZone": "Europe/Dublin",
"businessTimeZoneEnabled": true,
"defaultTitle": "Full Body Strength",
"defaultLocation": {
"type": "BUSINESS"
},
"defaultCapacity": 50,
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
"permissions": [],
"revision": "1",
"createdDate": "2024-10-06T17:16:35.386Z",
"updatedDate": "2024-10-06T17:16:35.386Z"
}
}
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 schedules, given the provided paging and filtering.
By default only ACTIVE
schedules are returned, unless you provide a different
status
filter.
Currently, you can't sort the response.
Query schedules runs with these defaults, which you can override:
cursorPaging.limit
is 50
For field support for filters, see Schedules V3: Supported Filters.
To learn about working with Query endpoints, see API Query Language and Sorting and Paging.
Query containing filters and paging.
Information about which fields containing personal data to return. Refer to the permissions article for more information.
Supported values:
PI_FIELDS
: Returns all fields with personal data. Your app must have Read Calendars - Including PI
or Manage Calendars
permission scope.OWN_PI_FIELDS
: Returns only fields containing your own personal data.Max: 1 field Default: No personal data is returned.
Retrieved schedules matching the provided query.
Paging metadata.
curl -X POST \
'https://www.wixapis.com/calendar/v3/schedules/query' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>'
{
"schedules": [
{
"id": "132db383-1378-4903-820b-4eebf4242de2",
"externalId": "4187d1f3-38a2-4cfd-b8f1-6333cd012e33",
"name": "Hip Hop Groove",
"status": "ACTIVE",
"timeZone": "Europe/Dublin",
"businessTimeZoneEnabled": true,
"defaultTitle": "Hip Hop Groove",
"defaultLocation": {
"type": "BUSINESS"
},
"defaultCapacity": 50,
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
"permissions": [],
"revision": "1",
"createdDate": "2024-10-06T17:16:35.344Z",
"updatedDate": "2024-10-06T17:16:35.344Z"
},
{
"id": "37e01b7f-7137-4c06-bca5-02eb435c1503",
"externalId": "38e25e56-d50f-42b4-a3b6-aa04c61dded1",
"name": "Full Body Strength",
"status": "ACTIVE",
"timeZone": "Europe/Dublin",
"businessTimeZoneEnabled": true,
"defaultTitle": "Full Body Strength",
"defaultLocation": {
"type": "BUSINESS"
},
"defaultCapacity": 50,
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
"permissions": [],
"revision": "1",
"createdDate": "2024-10-06T17:16:35.386Z",
"updatedDate": "2024-10-06T17:16:35.386Z"
}
],
"pagingMetadata": {
"count": 2,
"hasNext": false
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a schedule.
If you want the schedule's events to appear in the
Bookings calendar,
you must set appId
to the ID of the Wix Bookings app by providing
{"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97"}
.
You can only call this method when authenticated as a Wix app or Wix user identity.
Schedule to create.
Idempotency key guaranteeing that you don't create the same schedule more than once.
Created schedule.
Creates a schedule with basic name and App ID info.
curl -X POST \
'https://www.wixapis.com/calendar/v3/schedules' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"schedule": {
"name": "Consulting 101",
"appId": "27ef4db2-6609-4629-905d-3ec39e9d90e0"
}
}'
{
"schedule": {
"id": "3040aefd-73c8-4e0e-9be1-2fb80a822f13",
"name": "Consulting 101",
"status": "ACTIVE",
"timeZone": "Europe/Dublin",
"businessTimeZoneEnabled": true,
"appId": "27ef4db2-6609-4629-905d-3ec39e9d90e0",
"permissions": [],
"revision": "1",
"createdDate": "2024-10-13T12:14:12.790Z",
"updatedDate": "2024-10-13T12:14:12.790Z"
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates a schedule.
Each time the schedule is updated,
revision
increments by 1.
The current revision
must be passed when updating the schedule.
This ensures you're working with the latest schedule
and prevents unintended overwrites.
You can only call this method when authenticated as a Wix app or Wix user identity.
Schedule ID.
Schedule to update.
Information about whether participants of the schedule's updated events are notified and the message they receive.
Updated schedule.
Updates the schedule’s default capacity.
curl -X PATCH \
'https://www.wixapis.com/calendar/v3/schedules/a96c3c31-c9fc-495d-b55b-40c694fe196c' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"schedule": {
"defaultCapacity": 40,
"revision": "1"
}
}'
{
"schedule": {
"id": "a96c3c31-c9fc-495d-b55b-40c694fe196c",
"externalId": "0cc230a0-9158-4c5e-a5da-9161bed0f6b1",
"name": "Pump It Up",
"status": "ACTIVE",
"timeZone": "Europe/Dublin",
"businessTimeZoneEnabled": true,
"defaultTitle": "Pump It Up",
"defaultLocation": {
"type": "BUSINESS"
},
"defaultCapacity": 40,
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
"permissions": [],
"revision": "2",
"createdDate": "2024-10-06T17:16:35.495Z",
"updatedDate": "2024-10-07T07:03:27.404Z"
}
}
There is 1 error with this status code:
See the entire list and learn more about Wix errors.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Sets a schedule's status
to CANCELLED
.
Also cancels future events belonging to the schedule.
Once a schedule is marked as CANCELLED
, you can't reactivate it, update it,
or assign new events.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the schedule to cancel.
Whether to preserve future events with participants.
Default: false
.
Information about whether participants of the schedule's updated events are notified and the message they receive.
Canceled schedule.
curl -X POST \
'https://www.wixapis.com/calendar/v3/schedules/3470efd4-bd31-4aab-b339-38cdce8e1bd2/cancel' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>'
{
"schedule": {
"id": "3470efd4-bd31-4aab-b339-38cdce8e1bd2",
"externalId": "c84d2eb2-925e-49d8-910a-280473629415",
"name": "Zumba",
"status": "CANCELLED",
"timeZone": "Europe/Dublin",
"businessTimeZoneEnabled": true,
"defaultTitle": "Zumba",
"defaultCapacity": 10,
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
"permissions": [],
"revision": "2",
"createdDate": "2024-10-07T06:51:20.019Z",
"updatedDate": "2024-10-07T06:53:43.510Z"
}
}
There is 1 error with this status code:
See the entire list and learn more about Wix errors.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a schedule is canceled.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.calendar.v3.schedule
.
Event name. Expected cancelled
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.calendar.v3.schedule_cancelled",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "eddd6994-cca5-4158-a954-7afb4dd4d126",
"entityFqdn": "wix.calendar.v3.schedule",
"slug": "cancelled",
"entityId": "c1c3c510-82e7-4480-80c2-e026c30a17cf",
"actionEvent": {
"body": {
"schedule": {
"id": "c1c3c510-82e7-4480-80c2-e026c30a17cf",
"externalId": "7522ffa9-6e47-48b9-83a4-23584502f28a",
"name": "Corporate Seminar",
"status": "CANCELLED",
"timeZone": "Europe/Dublin",
"businessTimeZoneEnabled": true,
"defaultTitle": "Corporate Seminar",
"defaultLocation": {
"type": "BUSINESS"
},
"defaultCapacity": 10,
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
"permissions": [],
"revision": "2",
"createdDate": "2024-10-14T08:26:55.961Z",
"updatedDate": "2024-10-14T08:32:32.937Z"
},
"preserveFutureEventsWithParticipants": false,
"participantNotification": {
"notifyParticipants": false,
"metadata": {}
}
}
},
"eventTime": "2024-10-14T08:32:32.958288376Z",
"triggeredByAnonymizeRequest": false
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a schedule is cloned.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.calendar.v3.schedule
.
Event name. Expected cloned
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.calendar.v3.schedule_cloned",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "95cac352-8d43-44c0-910c-452c1ae75208",
"entityFqdn": "wix.calendar.v3.schedule",
"slug": "cloned",
"entityId": "6d1381ca-53a4-473e-8039-0abeebc579f7",
"actionEvent": {
"body": {
"schedule": {
"id": "6d1381ca-53a4-473e-8039-0abeebc579f7",
"externalId": "4e6b8232-624c-415e-b785-5c2d7e2fe3ed",
"status": "ACTIVE",
"timeZone": "Europe/Dublin",
"businessTimeZoneEnabled": true,
"defaultTitle": "TRX WORKOUT",
"defaultLocation": {
"type": "BUSINESS"
},
"defaultCapacity": 1,
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
"permissions": [],
"revision": "1",
"createdDate": "2024-04-23T11:23:04.815Z",
"updatedDate": "2024-04-23T11:23:04.815Z"
},
"trigger": "SITE_CREATED_FROM_TEMPLATE",
"originalMetaSiteId": "580f9b40-bd3d-45fe-b4ea-9ea709b9be50"
}
},
"eventTime": "2024-10-14T12:35:37.460046258Z",
"triggeredByAnonymizeRequest": false
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a schedule is created.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.calendar.v3.schedule
.
Event name. Expected created
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.calendar.v3.schedule_created",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "4441efa2-59fb-4edf-bc81-706dab0d2e0d",
"entityFqdn": "wix.calendar.v3.schedule",
"slug": "created",
"entityId": "c1c3c510-82e7-4480-80c2-e026c30a17cf",
"createdEvent": {
"entity": {
"id": "c1c3c510-82e7-4480-80c2-e026c30a17cf",
"externalId": "7522ffa9-6e47-48b9-83a4-23584502f28a",
"name": "Corporate Seminar",
"status": "ACTIVE",
"timeZone": "Europe/Dublin",
"businessTimeZoneEnabled": true,
"defaultTitle": "Corporate Seminar",
"defaultLocation": {
"type": "BUSINESS"
},
"defaultCapacity": 10,
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
"permissions": [],
"revision": "1",
"createdDate": "2024-10-14T08:26:55.961Z",
"updatedDate": "2024-10-14T08:26:55.961Z"
}
},
"eventTime": "2024-10-14T08:26:55.966766166Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "1"
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a schedule is updated.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.calendar.v3.schedule
.
Event name. Expected updated
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.calendar.v3.schedule_updated",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "2649639b-7eb8-437d-804d-cb672efbed07",
"entityFqdn": "wix.calendar.v3.schedule",
"slug": "updated",
"entityId": "132db383-1378-4903-820b-4eebf4242de2",
"updatedEvent": {
"currentEntity": {
"id": "132db383-1378-4903-820b-4eebf4242de2",
"externalId": "4187d1f3-38a2-4cfd-b8f1-6333cd012e33",
"name": "Hip Hop Groove",
"status": "ACTIVE",
"timeZone": "Europe/Dublin",
"businessTimeZoneEnabled": true,
"defaultTitle": "Hip Hop Groove",
"defaultLocation": {
"type": "BUSINESS"
},
"defaultCapacity": 40,
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
"permissions": [],
"revision": "2",
"createdDate": "2024-10-06T17:16:35.344Z",
"updatedDate": "2024-10-14T08:24:15.788Z"
}
},
"eventTime": "2024-10-14T08:24:15.794401237Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "2"
}