Skip to main content
Manage your business locations including addresses and geographic coordinates.

​
Create Location

Requires authentication.
Create a new business location with address and geographic information.
POST /api/v1/merchant/locations
curl -X POST 'https://api.example.com/api/v1/merchant/locations' \
  --cookie "session_token=your_session_token" \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "United States",
    "city": "San Francisco",
    "postal_code": "94102",
    "address": "123 Market St",
    "geo_point": {
      "latitude": 37.7749,
      "longitude": -122.4194
    },
    "place_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
    "formatted_location": "123 Market St, San Francisco, CA 94102, USA",
    "is_primary": true,
    "is_active": true
  }'
​
country
string
Country name
​
city
string
City name
​
postal_code
string
Postal or ZIP code
​
address
string
Street address
​
geo_point
object
required
Geographic coordinates
​
place_id
string
Google Places ID or similar identifier
​
formatted_location
string
required
Complete formatted address for display
​
is_primary
boolean
required
Whether this is the primary business location
​
is_active
boolean
required
Whether this location is currently active

​
Response

Returns 201 Created on successful location creation.

​
Location Data Model

Locations are referenced in merchant settings and appear in customer-facing booking flows. The primary location is displayed on the merchant’s public page.

​
Geographic Point

The geo_point object contains latitude and longitude coordinates: 
{
  "latitude": 37.7749,
  "longitude": -122.4194
}
These coordinates can be used for:
  • Displaying the location on a map
  • Calculating distance for customers
  • Location-based search and filtering

​
Formatted Location

The formatted_location field should contain a human-readable complete address: 
123 Market St, San Francisco, CA 94102, USA
This is displayed to customers during booking and in confirmation emails.

​
Primary vs Multiple Locations

While the current API supports creating locations, the merchant settings endpoint returns the primary location information. The is_primary flag designates which location is shown by default. Future versions may support:
  • Multiple active locations
  • Location-specific services
  • Location-based team member assignments
  • Service availability by location

​
Best Practices

​
Address Validation

When creating locations:
  1. Use a geocoding service (like Google Maps API) to validate addresses
  2. Obtain the place_id from the geocoding service
  3. Use the service’s formatted address for consistency
  4. Store exact latitude/longitude coordinates

​
Example with Google Maps

// Pseudocode for location creation with Google Maps
const result = await googleMaps.geocode('123 Market St, San Francisco');

const location = {
  country: result.country,
  city: result.city,
  postal_code: result.postalCode,
  address: result.streetAddress,
  geo_point: {
    latitude: result.lat,
    longitude: result.lng
  },
  place_id: result.placeId,
  formatted_location: result.formattedAddress,
  is_primary: true,
  is_active: true
};

​
Updating Locations

Currently, the API supports creating new locations. To update location information:
  1. Create a new location with updated details
  2. Set is_primary: true on the new location
  3. The merchant settings will reflect the new primary location
Note: Location update and delete endpoints may be added in future versions.

Build docs developers (and LLMs) love

Get started for freeTalk to us