About the Schedule Time Frames API

The Schedule Time Frames API allows you to keep track of when schedules start and end.

With the Schedule Time Frames API, you can:

  • Retrieve schedule time frames.
  • Track in real-time when a schedule time frame is updated.

For example, Wix Bookings uses the Schedule Time Frames API to determine when courses start and end.

For more in-depth scheduling management, see:

Before you begin

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

  • You can't update a schedule time frame. You can retrieve it and get notified in real-time when it's modified.

Terminology

  • Schedule time frame: Defines the first and last event dates within a schedule and indicates whether any events recur indefinitely.
  • Recurring event: Event that repeats based on a pattern defined by a recurrence rule. For example, weekly yoga classes or regular staff working hours. Recurring events can either end on a specified date or continue indefinitely. Learn more about recurring events.
Did this help?

Schedule Time Frame Object


Information about the start and end dates of the first and last events that belong to a schedule and whether any events follow an unlimited repetition pattern.

Properties
idstringRead-onlyformat GUID

ID of the schedule to which the time frame belongs.


statusstringRead-only

Information about the presence of recurring events within the schedule.

Supported values:

  • NONE: No events are scheduled within the schedule.
  • FINITE: All recurring events within the schedule have a defined end date, or there are no recurring events.
  • INFINITE: At least one recurring event within the schedule has no end date, meaning it follows an unlimited repetition pattern.

firstEventStartDateFirstEventStartDateRead-only

Start date of the first event within the schedule. Identical to event.start.localDate. Available only if status is set to FINITE or INFINITE.


lastEventEndDateLastEventEndDateRead-only

End date of the last event belonging to the schedule. Identical to event.end.localDate. Available only if status is set to FINITE.


adjustedFirstEventStartDateAdjustedFirstEventStartDateRead-only

Start date of the first event belonging to the schedule, adjusted to timeZone of the site properties or the timeZone specified in the request. Identical to event.adjustedStart.localDate.


adjustedLastEventEndDateAdjustedLastEventEndDateRead-only

End date of the last event belonging to the schedule, adjusted to timeZone of the site properties or the timeZone specified in the request. Identical to event.adjustedEnd.localDate.


revisionintegerRead-onlyformat int64

Revision number, which increments by 1 each time the schedule time frame is updated.

ScheduleTimeFrame
JSON
{ "id": "05279386-2859-49d6-9727-0096ad74e014", "status": "FINITE", "firstEventStartDate": { "localDate": "2024-09-24T16:30:00", "timeZone": "Europe/Dublin", "utcDate": "2024-09-24T15:30:00Z" }, "lastEventEndDate": { "localDate": "2024-11-27T17:00:00", "timeZone": "Europe/Dublin", "utcDate": "2024-11-27T17:00:00Z" }, "adjustedFirstEventStartDate": { "localDate": "2024-09-24T16:30:00", "timeZone": "Europe/Dublin" }, "adjustedLastEventEndDate": { "localDate": "2024-11-27T17:00:00", "timeZone": "Europe/Dublin" }, "revision": "15" }
Did this help?

GET

Get Schedule Time Frame


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 schedule time frame by schedule ID.

Permissions
Manage Bookings - all permissions
Read Bookings - all read permissions
Manage Bookings
Read Bookings - Public Data
Read Bookings - Including Participants
Read Bookings Calendar Availability
Read bookings calendar - including participants
Read Bookings Calendar
Manage Calendars
Read Calendar - Including PI
Read Calendar
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/calendar/v3/schedules/timeframe/{id}

Path Params
idstringRequired

Schedule ID for which to retrieve the schedule time frame.

Query Params
timeZonestring

Time zone for adjusting the times of the returned schedule time frame.

Default: timeZone of the site properties

Response Object
scheduleTimeFrameScheduleTimeFrame

Retrieved schedule time frame.

Get Schedule Time Frame
Request
cURL
curl -X GET \ 'https://www.wixapis.com/calendar/v3/schedules/timeframe/05279386-2859-49d6-9727-0096ad74e014' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "scheduleTimeFrame": { "id": "05279386-2859-49d6-9727-0096ad74e014", "status": "FINITE", "firstEventStartDate": { "localDate": "2024-09-24T16:30:00", "timeZone": "Europe/Dublin", "utcDate": "2024-09-24T15:30:00Z" }, "lastEventEndDate": { "localDate": "2024-11-27T17:00:00", "timeZone": "Europe/Dublin", "utcDate": "2024-11-27T17:00:00Z" }, "adjustedFirstEventStartDate": { "localDate": "2024-09-24T16:30:00", "timeZone": "Europe/Dublin" }, "adjustedLastEventEndDate": { "localDate": "2024-11-27T17:00:00", "timeZone": "Europe/Dublin" }, "revision": "15" } }
Did this help?

GET

List Schedule Time Frames


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 schedule time frames by schedule IDs.

Sorted by schedule ID in ascending order.

Permissions
Manage Bookings - all permissions
Read Bookings - all read permissions
Manage Bookings
Read Bookings - Public Data
Read Bookings - Including Participants
Read Bookings Calendar Availability
Read bookings calendar - including participants
Read Bookings Calendar
Manage Calendars
Read Calendar - Including PI
Read Calendar
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/calendar/v3/schedules/timeframe

Query Params
idsArray <string>Required

IDs of the schedules for which to retrieve schedule time frames.

Min: 1 schedule ID Max: 100 schedule IDs


timeZonestring

Time zone for adjusting the times of the returned schedule time frames.

Default: timeZone of the site properties

Response Object
scheduleTimeFramesArray <ScheduleTimeFrame>

Retrieved schedule time frames.

List Schedule Time Frames
Request
cURL
curl -X GET \ 'https://www.wixapis.com/calendar/v3/schedules/timeframe?ids=bac52132-220a-4361-8bd4-2a884af45eb6&ids=ea54fba1-8bad-4d1a-992a-a0fc772c6b46' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "scheduleTimeFrames": [ { "id": "bac52132-220a-4361-8bd4-2a884af45eb6", "status": "INFINITE", "firstEventStartDate": { "localDate": "2024-10-07T17:00:00", "timeZone": "Europe/Dublin", "utcDate": "2024-10-07T16:00:00Z" }, "adjustedFirstEventStartDate": { "localDate": "2024-10-07T17:00:00", "timeZone": "Europe/Dublin" }, "revision": "4" }, { "id": "ea54fba1-8bad-4d1a-992a-a0fc772c6b46", "status": "INFINITE", "firstEventStartDate": { "localDate": "2024-10-07T16:00:00", "timeZone": "Europe/Dublin", "utcDate": "2024-10-07T15:00:00Z" }, "adjustedFirstEventStartDate": { "localDate": "2024-10-07T16:00:00", "timeZone": "Europe/Dublin" }, "revision": "4" } ] }
Did this help?

Schedule Time Frame Updated


Developer Preview

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's time frame is updated, indicating a new first or last event or a change in the recurrence period, such as an extension or reduction.

Permissions
Manage Bookings - all permissions
Read Bookings - all read permissions
Manage Bookings
Read Bookings - Public Data
Read Bookings - Including Participants
Read Bookings Calendar Availability
Read bookings calendar - including participants
Read Bookings Calendar
Manage Calendars
Read Calendar - Including PI
Read Calendar
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.calendar.v3.schedule_time_frame.


slugstring

Event name. Expected updated.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


updatedEventUpdatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.calendar.v3.schedule_time_frame_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 } } }

ScheduleTimeFrameUpdated
JSON
{ "id": "11d69e2d-6eb2-4a47-9373-b61d0ab45ff1", "entityFqdn": "wix.calendar.v3.schedule_time_frame", "slug": "updated", "entityId": "66dffe8b-9215-4439-9b5c-50d9fb03bffc", "updatedEvent": { "currentEntity": { "id": "66dffe8b-9215-4439-9b5c-50d9fb03bffc", "status": "INFINITE", "firstEventStartDate": { "localDate": "2024-09-30T10:00:00", "timeZone": "America/Cayman", "utcDate": "2024-09-30T15:00:00Z" }, "revision": "2" } }, "eventTime": "2024-09-25T17:17:01.850049818Z", "triggeredByAnonymizeRequest": false, "entityEventSequence": "2" }
Did this help?