About Locations

With the Locations API, 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 you to:

Get, list, and query existing locations.
Create, update, and archive locations.
Set a default location that is reflected in the site properties.

Learn more about how site owners can manage their location-specific bookings.

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.

Before you begin

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

The Wix Bookings API doesn't support the businessSchedule object.
You can't delete a location. Instead, you can archive a location using the archiveLocation() function.
You can't archive the default location.
Archived locations can't be unarchived.
The updateLocation() function replaces an existing location with a new 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

Setup

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

Copy

1npm install @wix/business-tools

Copy

1yarn add @wix/business-tools

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

Copy

1import { locations } from '@wix/business-tools'

Was this helpful?

Yes

archiveLocation( )

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.

The archiveLocation() function returns a Promise that resolves to the archived location.

The archiveLocation() function changes a location's archived property to true.

Notes:

A location's status isn't affected by this function.
An archived location can't be updated.
It's currently not possible to unarchive locations.
A default location can't be archived.

Permission Scopes

For app development, you must have one of the following permission scopes:

Learn more about permission scopes.

Copy

function archiveLocation(_id: string): Promise<ArchiveLocationResponse>

Method Parameters

_idstringRequired

ID of the location to archive.

Returns

Return Type:Promise<ArchiveLocationResponse>

Was this helpful?

Yes

createLocation( )

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.

The createLocation() function returns a Promise that resolves to the created location.

Permission Scopes

For app development, you must have one of the following permission scopes:

Learn more about permission scopes.

Copy

function createLocation(location: Location): Promise<Location>

Method Parameters

locationLocationRequired

Location to create.

Returns

Return Type:Promise<Location>

Was this helpful?

Yes

getLocation( )

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.

The getLocation() function returns a Promise that resolves to the retrieved location.

Permission Scopes

For app development, you must have one of the following permission scopes:

Learn more about permission scopes.

Copy

function getLocation(_id: string): Promise<Location>

Method Parameters

_idstringRequired

ID of the location to retrieve.

Returns

Return Type:Promise<Location>

Was this helpful?

Yes

listLocations( )

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

Retrieves a list of up to 1,000 locations, given the provided filters, sorting, and paging.

Permission Scopes

For app development, you must have one of the following permission scopes:

Learn more about permission scopes.

Copy

function listLocations(options: ListLocationsOptions): Promise<ListLocationsResponse>

Method Parameters

optionsListLocationsOptions

Options to use when retrieving a list of locations.

Returns

Return Type:Promise<ListLocationsResponse>

Was this helpful?

Yes

queryLocations( )

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 query to retrieve a list of locations.

The queryLocations() function builds a query to retrieve a list of up to 1,000 locations and returns a LocationsQueryBuilder object.

The returned object contains the query definition which is typically used to run the query using the find() function.

You can refine the query by chaining LocationsQueryBuilder functions onto the query. LocationsQueryBuilder functions enable you to sort, filter, and control the results that queryLocations() returns. The functions that are chained to queryLocations() are applied in the order they are called.

queryLocations() runs with the following LocationsQueryBuilder defaults that you can override:

skip: 0
limit: 50

The following QueryLocationsBuilder functions are supported for the queryLocations() function. For a full description of the Locations object, see the object returned for the items property in LocationsQueryResult.

PROPERTY	SUPPORTED FILTERS & SORTING
`_id`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`name`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`description`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`default`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`
`status`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`
`locationType`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`
`fax`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`timeZone`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`email`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`phone`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`address.country`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`address.subdivision`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`address.city`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`address.postalCode`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`address.streetAddress.number`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`address.streetAddress.name`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`address.streetAddress.apt`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`address.formattedAddress`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`address.hint`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`address.geocode.latitude`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`lt()`,`le()`,`gt()`,`ge()`
`address.geocode.longitude`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`lt()`,`le()`,`gt()`,`ge()`
`businessSchedule.periods.openDay`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`
`businessSchedule.periods.openTime`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`businessSchedule.periods.closeDay`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`
`businessSchedule.periods.closeTime`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`businessSchedule.specialHourPeriod.startDate`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`businessSchedule.specialHourPeriod.endDate`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`businessSchedule.specialHourPeriod.isClosed`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`
`businessSchedule.specialHourPeriod.comment`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`startsWith()`
`revision`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`,`lt()`,`le()`,`gt()`,`ge()`
`archived`	`eq()`,`ne()`,`exists()`,`in()`,`hasSome()`

Permission Scopes

For app development, you must have one of the following permission scopes:

Learn more about permission scopes.

Copy

function queryLocations(): LocationsQueryBuilder

Request

This method does not take any parameters

Returns

Return Type:LocationsQueryBuilder

Was this helpful?

Yes

setDefaultLocation( )

Developer Preview

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

Sets a new default location.

The setDefaultLocation() function returns a Promise that resolves to the new default location.

Notes:

There can be only one default location per site.
The setDefaultLocation() function changes the value of the default property of both the new and old default locations objects.
The default location can't be archived.

Permission Scopes

For app development, you must have one of the following permission scopes:

Learn more about permission scopes.

Copy

function setDefaultLocation(_id: string): Promise<SetDefaultLocationResponse>

Method Parameters

_idstringRequired

ID of the location to set as the default location.

Returns

Return Type:Promise<SetDefaultLocationResponse>

Was this helpful?

Yes

updateLocation( )

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

The updateLocation() function returns a Promise that resolves to the updated location.

Each time a location is updated, its revision increments by 1. The current revision must be passed when updating the comment. This ensures you're working with the latest location and prevents unintended overwrites.

Notes:

Currently, it isn't possible to partially update a location. You must pass the full location object in the location parameter.
Any fields which are not included in the location parameter will be overwritten to null.

Permission Scopes

For app development, you must have one of the following permission scopes:

Learn more about permission scopes.

Copy

function updateLocation(_id: string, location: UpdateLocation): Promise<Location>

Method Parameters

_idstringRequired

Location ID.

locationUpdateLocationRequired

Updated location details.

Returns

Return Type:Promise<Location>

Was this helpful?

Yes