Locations

Role in the hierarchy

Locations sit under a company and anchor timezone, operating hours, and which services and resources apply. For the full model, see Architecture: company vs location.

Core API surface

Authenticated company API (Bearer + company context). Exact query parameters and bodies are in the API reference.

Area	Base paths	Notes
Collection	`GET /v3/locations`, `POST /v3/location`	List and create (plus `POST /v3/location/bulk` where supported)
Single record	`GET/PUT/DELETE /v3/location/:id`	Read, update, soft-delete patterns per your account rules
Weekly hours	`GET/POST /v3/location/:id/weeklyAvailability`	Schedule-mode baseline for the location
Associations	`POST .../setAssociations`, `PUT .../addAssociations`, `PUT .../removeAssociations`	Link related entities as your integration requires

Set each location’s IANA timezone so GET /v3/availability and appointments interpret local dates correctly. New locations default to America/New_York. Daily booking caps use UTC only when the stored timezone is blank.

Custom fields

Each location carries a free-form CustomFields object of string key/value pairs, set on POST /v3/location and PUT /v3/location/:id. Use it for identifiers your own systems need — a region code, a store number, a CRM record id.

GET /v3/locations filters on those values using dot notation:

curl "https://v3.onsched.com/v3/locations?CustomFields.regionCode=east-1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Use CustomFields.<key>=<value> query parameters.
Values are matched exactly and case-sensitively.
Multiple CustomFields.* parameters are combined with AND.
Empty string values are allowed.
Other CustomFields query shapes (for example CustomFields={...} or customFields.<key>) are rejected with 400.
Combine them with the existing name, services, resources, and include filters.

The filter requires an authenticated company request. GET /v3/public/locations rejects CustomFields.<key> with 400, since public location responses return only id and name.

Settings and limits

Company- and entity-level booking rules often reference location context. Location customerDailyBookingLimit caps how many appointments one customer may start at that location on a calendar day (all services). It is merchant-only — public Location GET still returns id and name.

Location expirationDelay sets the expiration timer for appointment holds, in seconds. New locations default to 900 seconds (15 minutes) when this field is omitted. Existing locations keep their current value; see Settings overview for overrides and update behavior. Locations created before this default may have no expiry and should set a positive delay.

See Settings overview, Booking limits, and Availability rules.

Holidays (v3 API)

Company-scoped holiday sets are available on the holidays routes (see Platform API utilities for a short overview). Legacy v1-style per-location holiday CRUD is described in the v1 alias endpoints guide if you still use that shim.

Public and unauthenticated flows

Customer-facing listing of locations for a public client uses GET /v3/public/locations (with a public client id and a matching Allowed Domain Origin). See Authentication.