Query Syntax: Filters, Sorting, Fields and Paging.

Filters

The filter section allows you to retrieve a specified subset of the available data.

The filter section is a single JSON object with the following rules:

Equality
Use the following format to specify an equality condition:

Copy
1
{
2
"query": {
3
"filter":{
4
"<field>":"<value>"}
5
}
6
}
7
}

Operators
Use operators in the following format:

Copy
1
{
2
"query": {
3
"filter":{
4
"<field>": {"<operator>":"<value>"},
5
...
6
}
7
}
8
}

For example, the following query will match all entities that have status set to "CREATED" or "UPDATED":

Copy
1
{
2
"query": {
3
"filter":{"status": {"$in": ["CREATED", "UPDATED"]}
4
}
5
}
6
}

Each endpoint supports a subset of the following operators. See the specific endpoint's reference documentation for a list of supported operators.

  • Comparison
    • $eq - Matches values that are equal to a specified value.
    • $ne - Matches all values that are not equal to a specified value.
    • $lt - Matches values that are less than a specified value.
    • $lte - Matches values that are less than or equal to a specified value.
    • $gt - Matches values that are greater than a specified value.
    • $gte - Matches values that are greater than or equal to a specified value.
    • $in - Matches any of the values specified in an array.
    • $hasSome - Matches an array that contains at least one of the specified values.
    • $hasAll - Matches an array that contains all of the specified values.
    • $startsWith - Matches strings that start with a specified value. Case insensitive.
    • $endsWith - Matches strings that end with the specified value. Case insensitive.
    • $contains - Matches strings that contain the specified value. Case insensitive.
  • Logical
    • $and - Joins query clauses with a logical AND, and returns all documents that match the conditions of all clauses.
    • $not - Inverts the effect of a query expression and returns documents that do not match the query expression.
    • $or - Joins query clauses with a logical OR, and returns all documents that match the conditions of at least one of the clauses.
  • Element
    • $exists - Matches objects that have the specified field.
  • Array
    • $hasSome - Matches an array that contains at least one element specified in the query.
    • $hasAll - Matches arrays that contain all elements specified in the query

Sample Queries
The following example shows a compound query that returns all entities where status is "NEW" and either Quantity is less than 30 or itemName starts with the character P:

Copy
1
{
2
"query": {
3
"filter":{
4
"status": "NEW",
5
"$or": [{"Quantity": {"$lt": 30}}, {"itemName": {"$startsWith": "P"}}]
6
}
7
}
8
}

The following example queries entities where the field tags value is an array with exactly two elements, "red" and "blank", in the specified order:

Copy
1
{
2
"query": {
3
"filter":{ "tags": ["red", "blank"] }
4
}
5
}

The following example queries for all entities where tags is an array that contains the string "red" as one of its elements, or that tags is the string "red":

Copy
1
{
2
"query": {
3
"filter":{"tags": "red" }
4
}
5
}

The following query matches entities that do not contain the item field, or where the item field has no value:

Copy
1
{
2
"query": {
3
"filter":{"item": {"$exists": false } }
4
}
5
}

Sort

The sort section is an array of field names and sort direction. If the direction is not specified, it will be sorted in ascending order:

Copy
1
{
2
"query": {
3
"sort": [{"fieldName":"sortField1"},{"fieldName":"sortField2","order":"DESC"}]
4
}
5
}

Paging

The paging section describes the size of the data set to return, and how many items to skip. For example, the following will return items 41-60. In other words, page number 3,with each page being 20 items:

Copy
1
{
2
"query": {
3
"paging": { "limit": 20, "offset": 40 }
4
}
5
}

Fields

The fields section is an array of field names and paths to return. Subsets of sub-objects can be returned by using dot notation. The following example returns firstName from name sub-object and the entire address object

Copy
1
{
2
"query": {
3
"fields": ["name.firstName", "address"]
4
}
5
}

Fieldsets

An API may provide named projections to save its clients from specifying the names of the fields in common use-cases. For example, Contacts includes a fieldset named common that contains only first name, last name, email, and phone number. If both fieldset and fields sections are specified, the returned items will include the fields specified in the fields array and those defined in the fieldset.

Copy
1
{
2
"query": {
3
"fieldset": ["common"]
4
}
5
}

Query Response

The response for a query request should be an object with the following structure:

Copy
1
{
2
"result-object": [...], //Array of the result object
3
"pagingMetadata": {
4
"count": 33, // Number of items in the result-object array
5
"offset": 3, // Offset of the first item in the result-object array
6
"total": 36 // Total number of result-objects that match the specified filters.
7
}
8
9
}
Was this helpful?
Yes
No

Patch Endpoints and Field Masks in Update Requests

When updating a resource, the Resources API uses PATCH endpoints and field masks. A PATCH endpoint means that only the fields specified in the request will be updated. Alternatively, a field mask explicitly lists the fields to update, regardless of which fields are specified in the request. You must use a field mask if you want to clear the value from a field.

The example below uses a field mask.

  • The value of the phone field is updated
  • The value of the email field is cleared.
  • The name field is not updated as it is not included in the field mask.
Copy
1
{
2
"resource": {
3
"name": "John Smith",
4
"phone": "5553456"
5
},
6
"fieldMask": {
7
"paths": ["phone","email"]
8
}
9
}
Was this helpful?
Yes
No

Resource Object

Properties
idstringRead-onlyformat GUID

Resource ID.


namestringmaxLength 1200

Resource name.


emailstringmaxLength 500

Resource email address.


phonestringmaxLength 500

Resource phone number.


descriptionstringmaxLength 500

Resource description.


tagstringmaxLength 500

Deprecated. Please use tags.


tagsstringmaxLength 200

Resource tags. Tags are used to identify, group, and filter the different types of resources. For example, 'staff' or 'room'.


imagesArray <Image>

Resource images.


schedulesArray <Schedule>

Deprecated. Please use scheduleIds. List of the schedules owned by this resource. Min size 1.


scheduleIdsstringRead-onlyformat GUID

List of IDs of schedules owned by this resource.


statusstringRead-only
4 enum supported values:
UNDEFINEDCREATEDDELETEDUPDATED

Resource status.


wixUserIdstringRead-onlyformat GUID

Wix user ID, if the resource is associated with the Wix user. A staff member resource can be associated with a Wix user via assignment of a permissions role in the business manager.

Was this helpful?
Yes
No

GetList Resources

Developer Preview

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

Deprecation Notice

This endpoint has been replaced with Query Resource and will be removed on March 31, 2022. If your app uses this endpoint, we recommend updating your code as soon as possible.

Retrieves a list of the resources according to the provided filters and paging. Resources that are in a resource group (i.e. the group_id property contains an ID) are excluded from the result for backwards compatibility.

This query is optional. If no query is provided than all non-deleted resources are returned.

PropertyIs supported
filtersupports resource.id, resource.tag, resource.status
pagingsupported
fieldssupported
fieldsetsnot supported
sortnot supported

Permissions This endpoint requires the Read Bookings Calendar, Read Bookings - Public Data, Read Bookings - Including Participants or Manage Bookings permission scope.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Bookings - Public Data
Read bookings calendar - including participants
Read Bookings Calendar
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/_api/bookings/v1/resources

Was this helpful?
Yes
No

PostCreate Resource

Developer Preview

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

Creates a resource.

Bookings resources are created with a schedule. The schedule and its sessions determine the resource's availability. Note that the schedule must contain a start date in the availability.start property. For resources that are available during the business's default hours, add the business's schedule as a linked schedule in the resource's schedule. For resources that have their own hours, create sessions with type "WORKING_HOURS" using the resource's schedule. You can use both individual and recurring sessions to define resource availability. You cannot use availability constraints for resource schedules.

Use the following steps to create resources:

  • Create the resource using including schedule information.
  • If the resource uses the default business hours, get the business resource's schedule ID and include it in the scheduleInfo.availability.linkedSchedules array in the in the schedule parameters.
  • If the resource has its own custom working hours, create sessions of type "WORKING_HOURS". Use the scheduleId of the new resource when creating the sessions. These session can be single sessions or recurring sessions. You can have both business hours and custom hours for the same resource schedule.

Notes:

  • A resource can have one schedule only.
  • You can have up to 135 active resources and an additional 135 deleted resources.
  • The businessLocation.businessSchedule object in the schedule.location object is not supported.

Permissions: This endpoint requires the Manage Bookings permission scope.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/_api/bookings/v1/resources

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostQuery Resources

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 resources according to the specified filters and paging.

The query parameter is optional. If no query is provided then all non-deleted resources are returned. Resources that are in a resource group (i.e. the group_id property contains an ID) are excluded from the result for backwards compatibility unless the include_resources_with_groups request field is set to true.

PropertyIs supported
filtersupported fields: resource.id, resource.tags, resource.status
pagingsupported
fieldssupported
fieldsetsnot supported
sortnot supported

Notes:

  • The following objects in the query parameter are not supported for this query:
    • sort
    • fieldsets

Permissions This endpoint requires the Read Bookings Calendar, Read Bookings - Public Data, Read Bookings - Including Participants or Manage Bookings permission scope.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Bookings - Public Data
Read bookings calendar - including participants
Read Bookings Calendar
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/_api/bookings/v1/resources/query

Was this helpful?
Yes
No

PatchUpdate Resource

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 a resource.

Use this endpoint to update all resource information except for the resource's schedule. To update a resource's schedule use the Update Schedule endpoint.

Notes:

  • When updating a resource you cannot change the system tags used by the Wix Bookings app. Tags used by the app have the values "business" and "staff".
  • When updating a resource's schedule you cannot change the resource tag used by the Wix Bookings app. Tags used by the app have the values "INDIVIDUAL""GROUP", and "COURSE”.
  • The businessLocation.businessSchedule object in the schedule.location object is not supported.

Permissions: This endpoint requires the Manage Bookings permission scope.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/_api/bookings/v1/resources/{resource.id}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PatchUpdate Schedule

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 a resource's schedule

To update a resource's schedule to remove business hours and add custom hours:

  • Update the resource's schedule to remove the business's scheduleId from the availability.linkedSchedules array.
  • Create a set of recurring sessions of type "WORKING_HOURS" to define the resource's new hours.

To update a resource's schedule to add default business hours, and keep or remove custom hours:

  • Update the resource's schedule to add the business resource's scheduleId to the availability.linkedSchedules array.
  • If you want to remove the custom sessions, delete the resource's sessions of type "WORKING_HOURS". You do not have to delete exiting custom sessions. Custom session that are not deleted will continue to be included in availability calculations and can still be booked.

Notes:

  • A resource can have one schedule only.
  • A resource can have both default business hours and custom hours in its schedule.
  • When updating a resource's schedule you cannot change the system tags used by the Wix Bookings app. Tags used by the app have the values "INDIVIDUAL""GROUP", and "COURSE”.
  • The businessLocation.businessSchedule object in the schedule.location object is not supported.

Permissions: This endpoint requires the Manage Bookings permission scope.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/_api/bookings/v1/resources/{resourceId}/updateSchedule

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

DeleteDelete Resource

Developer Preview

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

Deletes a resource.

Deleting a resource updates its status to "DELETED".

You cannot delete a resource if it has booked sessions.

Notes:

  • The Bookings app creates a resource with "business" in name and tag values. This resource is used for the business's schedule and working hours and cannot be deleted.
  • You can have up to 135 active resources and an additional 135 deleted resources.

Permissions: This endpoint requires the Manage Bookings permission scope.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/_api/bookings/v1/resources/{id}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

Resource Notification

Developer Preview

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

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
resourceobject

Updated resource entity. 'resource.schedules' is deprecated and will not be returned. Please use 'resource.scheduleIds' instead.


eventstring
5 enum supported values:
UNDEFINEDUpdatedDeletedCreatedSchedule_Updated

Event type.

Was this helpful?
Yes
No