About Locations

With the Locations API, Wix users can define multiple physical locations for their business. This allows them to set individual opening hours for each location.

The Locations API allows you to:

Learn more about how Wix users can manage their location-specific bookings.

Use cases

Before you begin

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

  • Locations can't be deleted. Instead, you can archive a location using Archive Location. Archiving is permanent; archived locations can't be unarchived.
  • The default location can't be archived.
  • The Update Location method completely overrides an existing 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 INACTIVE location status isn't currently supported.
  • The Wix Bookings API doesn't support the businessSchedule object.

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 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.
Did this help?

Setup

@wix/business-tools

To use the Locations API, install the @wix/business-tools package using npm or Yarn:

Copy

or

Copy

Then import { locations } from @wix/business-tools:

Copy
Did this help?

Sample use cases & flows: Locations

This article shares a possible use case for your implementation, 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 implementation.

Set Up a New Main Business Location

You can help Wix users create a new business location, set it as default, and update the opening hours for a location.

  1. Call Create Location.

  2. Set the new location as default by calling Set Default Location.

  3. List all existing locations by calling List Locations.

    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 by calling Update Location.

    Note: Currently, it isn't possible to partially update a location. Therefore, you'll need to specify the full location object when making the call.

Did this help?

addTypeToLocation( )

Developer Preview

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

Adds a location type to the specified location.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Locations
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
_idstringRequired

ID of the location where the type will be added.

locationTypeLocationTypeRequired

Location type to add.

Returns
Return Type:Promise<AddTypeToLocationResponse>
JavaScript
Errors
400Invalid Argument

There is 1 error with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

archiveLocation( )

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.
  • The default location can't be archived.
Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Locations
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
_idstringRequired

ID of the location to archive.

Returns
Return Type:Promise<ArchiveLocationResponse>
JavaScript
Errors
400Invalid Argument

There is 1 error with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

createLocation( )

Creates a location.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Locations
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
locationLocationRequired

Location to create.

Returns
Return Type:Promise<Location>
JavaScript
Errors
400Invalid Argument

There is 1 error with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

getLocation( )

Retrieves a location.

Permissions
Manage Bookings Services and Settings
Manage Bookings
Manage Calendars
Manage Events
Access Verticals by Automations
Set Up Automations
Manage Bookings - all permissions
Read Bookings - all read permissions
Read Bookings - Including Participants
Read bookings calendar - including participants
Manage Locations
Manage Portfolio
Manage Restaurants - all permissions
Read Locations
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
_idstringRequired

ID of the location to retrieve.

Returns
Return Type:Promise<Location>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

listLocations( )

Retrieves locations, given the specified filters, sorting, and paging.

Permissions
Manage Bookings Services and Settings
Manage Bookings
Manage Calendars
Manage Events
Access Verticals by Automations
Set Up Automations
Manage Bookings - all permissions
Read Bookings - all read permissions
Read Bookings - Including Participants
Read bookings calendar - including participants
Manage Locations
Manage Portfolio
Manage Restaurants - all permissions
Read Locations
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsListLocationsOptions

Options to use when retrieving a list of locations.

Returns
Return Type:Promise<ListLocationsResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?