Locations

Permission: locations (read / write). A location-limited key sees only its own locations.

GET /v1/locations (updated_since, limit, cursor) and GET /v1/locations/{id}.

{
  "object": "location",
  "id": 18,
  "name": "Wick & Ember — Stow",
  "address": { "line1": "4368 Kent Rd", "line2": null, "city": "Stow", "state": "OH", "postal_code": "44224", "country": "US" },
  "phone": "330-555-0100",
  "email": "stow@wickember.example",
  "timezone": "America/New_York",
  "tax_rate_bps": 725,
  "business_hours": { "mon": [["10:00", "19:00"]], "sun": [] },
  "status": "active",
  "is_default": true,
  "offers_pickup": true,
  "bigcommerce_location_id": 1,
  "latitude": 41.1595,
  "longitude": -81.4404,
  "updated_at": "2026-09-06T12:00:00Z"
}

Update contact details and hours

PATCH /v1/locations/{id} accepts only phone, email and business_hours, for listing tools that keep store details in step. Anything else is 409 FIELD_NOT_WRITABLE (details.fields): creating or removing a location changes the shop's bill, and the tax rate changes what the register charges, so those stay in Black Beach POS.

curl -X PATCH https://app.blackbeachpos.com/api/v1/locations/18 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"phone": "330-555-0100", "business_hours": {"mon": [["10:00", "19:00"]], "sat": [["10:00", "17:00"]], "sun": []}}'

business_hours is keyed by mon … sun; each day is a list of ["HH:MM", "HH:MM"] pairs in the store's local time (several pairs = split shifts), and a missing or empty day is closed. null clears the hours.