The Resources API is an integral part of the Wix Bookings app, designed to manage and interact with various types of resources that can be booked by customers. These resources could include meeting rooms, equipment, event spaces, or any other assets that require scheduling and availability management.
The Resources API provides functionality to manage resources, including creating, updating, deleting, and querying resources.
It’s important to note the following points before starting to code:
For a comprehensive glossary of Wix Bookings terms, see Terminology.
This article presents possible use cases that your app could support, along with sample flows to implement each use case. These examples can serve as a helpful starting point as you plan your app's functionality.
You could create a resource that's bookable only at a specific location.
To create a bookable resource:
Use Query Resource Types to retrieve the ID of the resource type.
Use Query Locations to retrieve the ID of the business location.
Use Create Resource to create the resource by providing a name, the ID of the resource type and the ID of the business location.
If the resource type of the created resource is not yet associated to the relevant services then perform the following steps:
Use Query Services to retrieve the IDs of the relevant services that are not yet associated to the resource type. You can check this by inspecting the serviceResources.resourceType
fields of the service. If this field does not contain the ID of the resource type then the service is not yet associated to the type.
Use Update Service to associate each service to the resource type by providing the ID of the service and the ID of the resource type. To do so add an entry to the serviceResources
array of which the resourceType.id
field is set to the ID of the resource type.
This article outlines error messages that might be issued when calling endpoints of the Resources API.
The Create Resource and Bulk Create Resource endpoints might issue the following error messages:
HTTP status | Error code | Error message | Troubleshooting |
---|---|---|---|
INVALID_ARGUMENT (400) | RESOURCE_LOCATION_ID_IS_REQUIRED | locationId is a required field of locationOptions.specificLocationOptions.businessLocations | Make sure that each element in the businessLocations array contains a non-empty ID. |
INVALID_ARGUMENT (400) | RESOURCE_SPECIFIC_LOCATION_OPTIONS_NOT_ALLOWED | specificLocationOptions of locationOptions cannot be set if availableInAllLocations is true | Make sure that a resource is specified to be available at all locations by setting availableInAllLocations to true or at specific locations only by setting specificLocationOptions . |
INVALID_ARGUMENT (400) | RESOURCE_SPECIFIC_LOCATION_OPTIONS_MUST_BE_SET | specificLocationOptions of locationOptions must be set if availableInAllLocations is false or empty | If the resource is not available at any location, then supply the specificLocationOptions field to specify the locations the resource is available. |
INVALID_ARGUMENT (400) | RESOURCE_AVAILABLE_IN_BUSINESS_LOCATION_MUST_BE_TRUE | available_in_business_locations in locationOptions.specificLocationOptions must be set to true | When availableInAllLocations is false or empty then available_in_business_locations must be set to true . |
INVALID_ARGUMENT (400) | RESOURCE_WORKING_HOURS_NOT_SUPPORTED_IN_BULK_REQUEST | workingHoursSchedules is currently not supported in bulk requests | At this time it is not possible to include a resource with working hour schedules in a call to Bulk Create Resources. |
The Update Resource endpoint might issue the following error messages:
HTTP status | Error code | Error message | Troubleshooting |
---|---|---|---|
INVALID_ARGUMENT (400) | RESOURCE_NAME_IS_REQUIRED | 'name' is a required field of Resource | When updating the name of the resource make sure that the new name is not empty. |
INVALID_ARGUMENT (400) | RESOURCE_LOCATION_ID_IS_REQUIRED | locationId is a required field of locationOptions.specificLocationOptions.businessLocations | Make sure that each element in the businessLocations array contains a non-empty value. |
INVALID_ARGUMENT (400) | RESOURCE_SPECIFIC_LOCATION_OPTIONS_NOT_ALLOWED | specificLocationOptions of locationOptions cannot be set if availableInAllLocations is true | Make sure that a resource is specified to be available at all locations by setting availableInAllLocations to true or at specific locations only by setting specificLocationOptions . |
INVALID_ARGUMENT (400) | RESOURCE_SPECIFIC_LOCATION_OPTIONS_MUST_BE_SET | specificLocationOptions of locationOptions must be set if availableInAllLocations is false or empty | If the resource is not available at any location, then supply the specificLocationOptions field to specify the locations the resource is available. |
INVALID_ARGUMENT (400) | RESOURCE_AVAILABLE_IN_BUSINESS_LOCATION_MUST_BE_TRUE | available_in_business_locations in locationOptions.specificLocationOptions must be set to true | When availableInAllLocations is false or empty then available_in_business_locations must be set to true . |
INVALID_ARGUMENT (400) | RESOURCE_WORKING_HOURS_SCHEDULE_ID_IS_REQUIRED | scheduleId is a required field of workingHoursSchedules.values | When updating the working hour schedules of a resource make sure that scheduleId has a non-empty value. |
INVALID_ARGUMENT (400) | RESOURCE_WORKING_HOURS_SHARED_IS_REQUIRED | shared is a required field of workingHoursSchedules.values | When updating the working hour schedules of a resource make sure that shared has a non-empty value. |
INVALID_ARGUMENT (400) | RESOURCE_TYPE_IS_IMMUTABLE | type is an immutable field and can therefore not be modified | The type field of a resource cannot be updated. |
Query endpoints allow you to filter and sort results based on resource properties. This article covers field support for filtering and sorting.
Specify the filter
object in the following format:
{
"filter": {
"fieldName": {
"$eq": "value"
}
}
}
The following table shows field support for filters and sorting for the Resource object:
Field | Supported Filters | Sortable |
---|---|---|
id | $eq , $ne , $exists , $in , $nin , $startsWith | Sortable |
name | $eq , $ne , $exists , $in , $nin , $isEmpty | |
typeId | $eq , $ne , $exists , $in , $nin , $startsWith , $isEmpty | Sortable |
locationOptions.availableInAllLocations | $eq , $ne , $exists , $in , $nin | Sortable |
locationOptions.specificLocationOptions.availableInBusinessLocations | $eq , $ne , $exists , $in , $nin | Sortable |
locationOptions.specificLocationOptions.businessLocations.locationId | $eq , $ne , $isEmpty , $hasAll , $hasSome | Sortable |
eventsSchedule.scheduleId | $eq , $ne , $exists , $in , $nin , $startsWith | Sortable |
Results are sorted by the id
field in ascending order by default.
To sort by a different field, use the sort
object in the following format:
{
"sort": [
{
"fieldName": "typeId",
"order": "DESC"
}
]
}
Related content:
A resource represents an entity that can be scheduled for use, such as a room or a staff member. The availability of a resource is tracked to ensure that it can be allocated at a requested time slot and to prevent double bookings. Read more about resources in this article.
Resource ID.
Revision number, which increments by 1 each time the resource is updated. To prevent conflicting changes, the current revision must be passed when updating the resource.
Represents the time in YYYY-MM-DDThh:mm:ss.sssZ
format this resource was created.
Represents the time in YYYY-MM-DDThh:mm:ss.sssZ
format this resource was last updated.
Name of the resource.
ID of the resource type.
Once a type has been set it can't be modified. You can create a resource without specifying a type. However, such resources cannot be booked.
Schedule details that specify the working hours and locations of this resource.
Resources without this field are available 24/7 at the locations specified in the field locationOptions
.
When both workingHoursSchedules
and locationOptions
are set then workingHoursSchedules
takes precedence.
Location details that specify where this resource is available.
This schedule contains the sessions in which this resource has been booked.
Extensions enabling users to save custom data related to the resource.
{
"resource": {
"id": "ffedf9dc-932d-439f-b1f4-e42b2a5a8bb5",
"revision": "1",
"createdDate": "2024-11-22T13:36:47.104Z",
"updatedDate": "2024-11-22T13:36:47.104Z",
"name": "Meeting room with conference system",
"typeId": "dd7790c7-f3ac-4821-accb-52ed385fd932",
"locationOptions": {
"availableInAllLocations": false,
"specificLocationOptions": {
"availableInBusinessLocations": true,
"businessLocations": [
{
"locationId": "1295e5ff-ecb3-41bc-8b6f-7345792e5ec0"
}
]
}
},
"eventsSchedule": {
"scheduleId": "e263b1ca-a1e9-45bf-a39c-044e97c63500"
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a new resource.
A new events schedule is automatically created specific to this resource. This schedule will contain information on when the resource is booked in order to prevent double bookings. See Schedules API for more information.
locationOptions
, then the service will create this field and set
availableInAllLocations
in this structure to true
.locationOptions.specificLocationOptions.businessLocations
field, then the field locationOptions.specificLocationOptions.availableInBusinessLocations
must be set
to true
.You can only call this method when authenticated as a Wix app or Wix user identity.
Resource to create.
The created resource.
This is a minimal example of creating a resource. By default this resource is available in all locations. Only when the type
field is provided can the resource be used for bookings.
curl -X POST \
'https://www.wixapis.com/bookings/v2/resources' \
-H 'Authorization: <AUTH>' \
-d '{
"resource": {
"name": "Some name"
}
}'
{
"resource": {
"id": "77c7a7d1-0045-47eb-bef7-f1bcac5f68e1",
"revision": "1",
"createdDate": "2024-11-22T13:28:29.869Z",
"updatedDate": "2024-11-22T13:28:29.869Z",
"name": "Some name",
"locationOptions": {
"availableInAllLocations": true
},
"eventsSchedule": {
"scheduleId": "c0091359-7007-4288-be59-dccade075472"
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates multiple resources.
You can only call this method when authenticated as a Wix app or Wix user identity.
Resources to create.
Whether to include the created resources in the response. Default: false
The result of each resource creation.
Create statistics.
curl -X POST \
'https://www.wixapis.com/bookings/v2/bulk/resources/create' \
-H 'Authorization: <AUTH>' \
-d '{
"resources": [
{
"name": "Small meeting room",
"typeId": "dd7790c7-f3ac-4821-accb-52ed385fd932",
"location_options": {
"specific_location_options": {
"business_locations": [
{
"location_id": "808dfb00-0a74-4e70-bb3b-f96ff6ba1246"
}
],
"available_in_business_locations": true
}
}
}
],
"return_entity": "true"
}'
{
"results": [
{
"itemMetadata": {
"id": "ef5f8d3d-9269-490c-a067-a3d226fcb5d8",
"originalIndex": 0,
"success": true
},
"item": {
"id": "ef5f8d3d-9269-490c-a067-a3d226fcb5d8",
"revision": "1",
"createdDate": "2024-11-22T14:02:34.993Z",
"updatedDate": "2024-11-22T14:02:34.993Z",
"name": "Small meeting room",
"typeId": "dd7790c7-f3ac-4821-accb-52ed385fd932",
"locationOptions": {
"availableInAllLocations": false,
"specificLocationOptions": {
"availableInBusinessLocations": true,
"businessLocations": [
{
"locationId": "808dfb00-0a74-4e70-bb3b-f96ff6ba1246"
}
]
}
},
"eventsSchedule": {
"scheduleId": "ee500718-7ce3-478a-89fb-1d839a37e324"
}
}
}
],
"bulkActionMetadata": {
"totalSuccesses": 1,
"totalFailures": 0,
"undetailedFailures": 0
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a resource by ID.
ID of the resource to retrieve.
The retrieved resource.
curl -X GET \
'https://www.wixapis.com/bookings/v2/resources/ffedf9dc-932d-439f-b1f4-e42b2a5a8bb5' \
-H 'Authorization: <AUTH>'
{
"resource": {
"id": "ffedf9dc-932d-439f-b1f4-e42b2a5a8bb5",
"revision": "1",
"createdDate": "2024-11-22T13:36:47.104Z",
"updatedDate": "2024-11-22T13:36:47.104Z",
"name": "Meeting room with conference system",
"typeId": "dd7790c7-f3ac-4821-accb-52ed385fd932",
"locationOptions": {
"availableInAllLocations": false,
"specificLocationOptions": {
"availableInBusinessLocations": true,
"businessLocations": [
{
"locationId": "1295e5ff-ecb3-41bc-8b6f-7345792e5ec0"
}
]
}
},
"eventsSchedule": {
"scheduleId": "e263b1ca-a1e9-45bf-a39c-044e97c63500"
}
}
}
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.
Also cancels the associated events schedule and any working hours schedule that isn’t shared among multiple resources.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the resource to delete.
curl -X DELETE \
'https://www.wixapis.com/bookings/v2/resources/ffedf9dc-932d-439f-b1f4-e42b2a5a8bb5' \
-H 'Authorization: <AUTH>'
{}
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.
Each time the resource is updated, revision
increments by 1. You must include the current revision of the resource when updating it.
This ensures you're working with the latest service information and prevents unintended overwrites.
You can only call this method when authenticated as a Wix app or Wix user identity.
Resource ID.
Resource to be updated, may be partial.
The updated resource.
To update a resource the fields id
and revision
are required. Partial updates are supported.
curl -X PATCH \
'https://www.wixapis.com/bookings/v2/resources/77c7a7d1-0045-47eb-bef7-f1bcac5f68e1' \
-H 'Authorization: <AUTH>' \
-d '{
"resource": {
"id": "77c7a7d1-0045-47eb-bef7-f1bcac5f68e1",
"revision": "1",
"name": "Updated name"
}
}'
{
"resource": {
"id": "77c7a7d1-0045-47eb-bef7-f1bcac5f68e1",
"revision": "2",
"createdDate": "2024-11-22T13:28:29.869Z",
"updatedDate": "2024-11-22T15:08:44.446Z",
"name": "Updated name",
"locationOptions": {
"availableInAllLocations": true
},
"eventsSchedule": {
"scheduleId": "c0091359-7007-4288-be59-dccade075472"
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Deletes multiple resources.
You can only call this method when authenticated as a Wix app or Wix user identity.
The IDs of the resources to delete.
The result of each resource removal.
Delete statistics.
Title: Delete multiple resources.
curl -X POST \
'https://www.wixapis.com/bookings/v2/bulk/resources/delete' \
-H 'Authorization: <AUTH>' \
-d '{
"ids": [
"133b8ace-64c9-45c7-bb7e-e667f29a4e8c",
"3cb4338c-3792-44ba-9259-c73c86b0cd89"
]
}'
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Query resources using WQL - Wix Query Language.
For field support for filters and sorting, see Resources: Filtering and Sorting.
WQL expression.
The retrieved Resources.
Paging metadata
Query resources, filtering by resource type and providing a limit to the number of results returned.
curl -X POST \
'https://www.wixapis.com/bookings/v2/resources/query' \
-H 'Authorization: <AUTH>' \
-d '{
"query": {
"filter": {
"type": {
"$eq": "dd7790c7-f3ac-4821-accb-52ed385fd932"
}
},
"cursorPaging": {
"cursor": null,
"limit": 100
}
}
}'
{
"resources": [
{
"id": "ef5f8d3d-9269-490c-a067-a3d226fcb5d8",
"revision": "1",
"createdDate": "2024-11-22T14:02:34.993Z",
"updatedDate": "2024-11-22T14:02:34.993Z",
"name": "Small meeting room",
"typeId": "dd7790c7-f3ac-4821-accb-52ed385fd932",
"locationOptions": {
"availableInAllLocations": false,
"specificLocationOptions": {
"availableInBusinessLocations": true,
"businessLocations": [
{
"locationId": "808dfb00-0a74-4e70-bb3b-f96ff6ba1246"
}
]
}
},
"eventsSchedule": {
"scheduleId": "ee500718-7ce3-478a-89fb-1d839a37e324"
}
},
{
"resource": {
"id": "ffedf9dc-932d-439f-b1f4-e42b2a5a8bb5",
"revision": "1",
"createdDate": "2024-11-22T13:36:47.104Z",
"updatedDate": "2024-11-22T13:36:47.104Z",
"name": "Meeting room with conference system",
"typeId": "dd7790c7-f3ac-4821-accb-52ed385fd932",
"locationOptions": {
"availableInAllLocations": false,
"specificLocationOptions": {
"availableInBusinessLocations": true,
"businessLocations": [
{
"locationId": "1295e5ff-ecb3-41bc-8b6f-7345792e5ec0"
}
]
}
},
"eventsSchedule": {
"scheduleId": "e263b1ca-a1e9-45bf-a39c-044e97c63500"
}
}
}
],
"pagingMetadata": {
"count": 2,
"cursors": {},
"hasNext": false
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Counts resources according to given criteria.
Use WQL filter to define the criteria.
Filter to apply on resources to count.
The number of resources matching the given filter.
curl -X POST \
'https://www.wixapis.com/bookings/v2/resources/count' \
-H 'Authorization: <AUTH>' \
-d '{}'
{
"count": 4
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered for each resource that is created.
This event has the same structure as Resource Created.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.bookings.resources.v2.resource
.
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.bookings.resources.v2.resource_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": "02c1a7da-18fb-4e5e-b32f-49a19fd722a7",
"entityFqdn": "wix.bookings.resources.v2.resource",
"slug": "created",
"entityId": "40435ea0-f5d3-448b-977a-2e3e365075e0",
"createdEvent": {
"entity": {
"id": "40435ea0-f5d3-448b-977a-2e3e365075e0",
"revision": "1",
"createdDate": "2024-11-25T15:45:16.540Z",
"updatedDate": "2024-11-25T15:45:16.540Z",
"name": "Room 1",
"typeId": "dd7790c7-f3ac-4821-accb-52ed385fd932",
"locationOptions": {
"availableInAllLocations": false,
"specificLocationOptions": {
"availableInBusinessLocations": true,
"businessLocations": [
{
"locationId": "7a02a881-9711-489a-9a37-eef331acff8e"
}
]
}
},
"eventsSchedule": {
"scheduleId": "354e9dbc-4005-4019-85c6-2c0dcdae198b"
}
}
},
"eventTime": "2024-11-25T15:45:16.671040653Z",
"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 for reach resource that is deleted.
This event has the same structure as Resource Deleted.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.bookings.resources.v2.resource
.
Event name. Expected deleted
.
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.bookings.resources.v2.resource_deleted",
"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": "11ac4dce-969c-42e2-a031-fbea25dde2f9",
"entityFqdn": "wix.bookings.resources.v2.resource",
"slug": "deleted",
"entityId": "40435ea0-f5d3-448b-977a-2e3e365075e0",
"deletedEvent": {
"movedToTrash": true
},
"eventTime": "2024-11-25T16:00:06.736054548Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "12"
}
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 resource is updated.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.bookings.resources.v2.resource
.
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.bookings.resources.v2.resource_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": "6be1f920-3773-4b33-a3da-c36f29e5245f",
"entityFqdn": "wix.bookings.resources.v2.resource",
"slug": "updated",
"entityId": "40435ea0-f5d3-448b-977a-2e3e365075e0",
"updatedEvent": {
"currentEntity": {
"id": "40435ea0-f5d3-448b-977a-2e3e365075e0",
"revision": "2",
"createdDate": "2024-11-25T15:45:16.540Z",
"updatedDate": "2024-11-25T15:53:54.620Z",
"name": "Room 2nd floor",
"typeId": "dd7790c7-f3ac-4821-accb-52ed385fd932",
"locationOptions": {
"availableInAllLocations": false,
"specificLocationOptions": {
"availableInBusinessLocations": true,
"businessLocations": [
{
"locationId": "7a02a881-9711-489a-9a37-eef331acff8e"
}
]
}
},
"eventsSchedule": {
"scheduleId": "354e9dbc-4005-4019-85c6-2c0dcdae198b"
}
}
},
"eventTime": "2024-11-25T15:53:54.736149543Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "2"
}