About the Locations API

With Locations, site owners can define multiple physical locations for their business. This allows them to set individual opening hours for each location.

The Locations API allows your app to:

  • List existing locations
  • Create, update, and archive locations
  • Set a default location that is reflected in the site properties

Read more about how site owners can manage their location specific bookings. You can also read more about how to retrieve the site properties.

Terminology

  • Default location: Location reflected in the site properties. This location is used on invoices.
  • Type: Describes whether a location is an office, reception, branch or the headquarters.
  • Status: Indicates whether a location is ACTIVE or INACTIVE.
  • Business Schedule: Describes the location's regular and exceptional opening hours.
    • Period: Regular, weekly recurring opening hours of the location.
    • Special Hour Period: Exception to the location's regular hours. The location can be either open or closed during the Special Hour Period.

Limitations

  • The Wix Bookings API doesn't support the businessSchedule object.
  • You can't delete a location. Instead, you can archive a location using the Archive Location endpoint.
  • You can't archive the default location.
  • Archived locations can't be unarchived.
  • The Update Location endpoint replaces a location. Currently, you can't partially update a location.
  • Currently, the location type is just informational and doesn't affect a location's functionality.
  • The status INACTIVE isn't currently supported.
Was this helpful?
Yes
No

Sample use cases & flows: Locations

This article shares a possible use case for your app, as well as an example flow that supports it. You're certainly not limited to this use case, but it can be a helpful jumping off point as you plan your app's implementation.

Set Up a New Main Business Location

Your app can help the site owners create a new business location, set it as default, and update the opening hours for a location.

  1. Call the Create Location endpoint.

  2. Set the new location as default via the Set Default Location endpoint.

  3. List all existing locations by calling the List Locations endpoint.

    Note: Make sure to extract the relevant locations’ IDs from the response and save it for future calls.

  4. Update a location's opening hours via the Update Location endpoint.

    Note: Currently, it isn't possible to partially update a location. Therefore, you'll need to pass the full location object in the body of the call.

Was this helpful?
Yes
No

Location Object

Attributes
idstringRead-onlyformat GUID
Location ID.

namestringmaxLength 150
Location name.

descriptionstringmaxLength 500
Location description.

defaultbooleanRead-only
Whether this is the default location. There can only be one default location per site. The default location can't be archived.

statusstring
2 supported values:
ACTIVEINACTIVE
Location status. Defaults to ACTIVE. Note: Archiving a location doesn't affect the location's status. INACTIVE is currently not supported.

locationTypestring
5 supported values:
UNKNOWNBRANCHOFFICESRECEPTIONHEADQUARTERS
Location type. Note: Currently not supported.

faxstring
Fax number.

timeZonestring
Timezone in America/New_York format.

emailstring
Email address.

phonestring
Phone number.

addressobject
Address.

businessScheduleobject
Business schedule. Array of weekly recurring time periods when the location is open for business. Limited to 100 time periods. Note: Not supported by Wix Bookings.

revisionobject
Revision number, which increments by 1 each time the location is updated. To prevent conflicting changes, the existing revision must be used when updating a location.

archivedbooleanRead-only
Whether the location is archived. Archived locations can't be updated. Note: Archiving a location doesn't affect its status.
Was this helpful?
Yes
No

GetList Locations

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 locations, given the provided filters, sorting, and paging.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read bookings calendar - including participants
Read Locations
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
GET
https://www.wixapis.com/locations/v1/locations

Was this helpful?
Yes
No

PostCreate Location

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 location.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Locations
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/locations/v1/locations

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

GetGet Location

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 location.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read bookings calendar - including participants
Read Locations
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
GET
https://www.wixapis.com/locations/v1/locations/{id}

Was this helpful?
Yes
No

PutUpdate Location

Developer Preview

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

Replaces a location.

Note: Currently, it isn't possible to partially update a location. Therefore, you'll need to pass the full location object in the body of the call.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Locations
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
PUT
https://www.wixapis.com/locations/v1/locations/{location.id}

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

PostQuery Locations

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 locations, given the provided filters, sorting, and paging.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read bookings calendar - including participants
Read Locations
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/locations/v1/locations/query

Was this helpful?
Yes
No

PostArchive Location

Developer Preview

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

Archives a location.

Notes:

  • Changes the archived boolean of a location to true.
  • You can't change a location's status using this endpoint.
  • Archived locations can't be updated.
  • Currently, it isn't possible to unarchive locations.
  • The default location can't be archived.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Locations
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/locations/v1/locations/{id}/archive

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

Location Created

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
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.locations.v1.location.

slugstring
Event name. Expected created.

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.

createdEventobject
Event information.
Was this helpful?
Yes
No

Location 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.

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.locations.v1.location.

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.

updatedEventobject
Event information.
Was this helpful?
Yes
No

Set Default Location

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
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.locations.v1.location.

slugstring
Event name. Expected set_default_location.

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.

actionEventobject
Event information.
Was this helpful?
Yes
No

Location Archive Status

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
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.locations.v1.location.

slugstring
Event name. Expected archive_status.

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.

actionEventobject
Event information.
Was this helpful?
Yes
No