Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway.

Locations API

Manage restaurant locations and their configurations.

Overview

The Locations API provides complete location management:

Feature	Description
Location CRUD	Create, read, update, delete locations
Business Hours	Operating schedule management
Settings	Location-specific configuration
Hardware	Device and terminal management
Service Areas	Delivery zones and regions

Location Model

{
  "id": "loc-xyz789",
  "tenant_id": "tenant-abc123",
  "name": "Downtown Location",
  "code": "DT001",
  "status": "open",
  "address": {
    "line1": "123 Main Street",
    "line2": "Suite 100",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102",
    "country": "US"
  },
  "coordinates": {
    "lat": 37.7749,
    "lng": -122.4194
  },
  "phone": "+1-415-555-1234",
  "timezone": "America/Los_Angeles",
  "created_at": "2025-06-15T10:00:00Z"
}

List Locations

Request

GET /api/v1/locations?tenant_id=tenant-abc123&status=open
Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Description
`tenant_id`	string	Filter by tenant
`status`	string	Filter by status
`search`	string	Search by name or code
`near`	string	Coordinates for proximity search
`radius_km`	number	Search radius in kilometers

Response

{
  "locations": [
    {
      "id": "loc-xyz789",
      "name": "Downtown Location",
      "code": "DT001",
      "status": "open",
      "address": {
        "city": "San Francisco",
        "state": "CA"
      },
      "current_status": {
        "is_open": true,
        "closes_at": "22:00"
      },
      "stats": {
        "orders_today": 145,
        "revenue_today": 4250.00
      }
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0
  }
}

Get Location

Request

GET /api/v1/locations/{location_id}
Authorization: Bearer {access_token}

Response

{
  "id": "loc-xyz789",
  "tenant_id": "tenant-abc123",
  "name": "Downtown Location",
  "code": "DT001",
  "status": "open",
  "address": {
    "line1": "123 Main Street",
    "line2": "Suite 100",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102",
    "country": "US",
    "formatted": "123 Main Street, Suite 100, San Francisco, CA 94102"
  },
  "coordinates": {
    "lat": 37.7749,
    "lng": -122.4194
  },
  "contact": {
    "phone": "+1-415-555-1234",
    "email": "downtown@acmerestaurants.com",
    "manager": "Jane Manager"
  },
  "timezone": "America/Los_Angeles",
  "settings": {
    "currency": "USD",
    "tax_rate": 8.625,
    "tip_presets": [15, 18, 20, 25],
    "receipt_footer": "Thank you for dining with us!",
    "order_number_prefix": "DT"
  },
  "business_hours": {
    "monday": {"open": "11:00", "close": "22:00"},
    "tuesday": {"open": "11:00", "close": "22:00"},
    "wednesday": {"open": "11:00", "close": "22:00"},
    "thursday": {"open": "11:00", "close": "22:00"},
    "friday": {"open": "11:00", "close": "23:00"},
    "saturday": {"open": "10:00", "close": "23:00"},
    "sunday": {"open": "10:00", "close": "21:00"}
  },
  "features": {
    "dine_in": true,
    "takeout": true,
    "delivery": true,
    "curbside": true,
    "drive_thru": false,
    "reservations": true
  },
  "hardware": {
    "terminals": 4,
    "kds_stations": 2,
    "printers": 3,
    "kiosks": 2
  },
  "created_at": "2025-06-15T10:00:00Z",
  "updated_at": "2026-01-15T14:30:00Z"
}

Create Location

Request

POST /api/v1/locations
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "tenant_id": "tenant-abc123",
  "name": "New Location",
  "code": "NL001",
  "address": {
    "line1": "456 Oak Avenue",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "US"
  },
  "phone": "+1-415-555-5678",
  "timezone": "America/Los_Angeles",
  "settings": {
    "tax_rate": 8.625
  }
}

Parameters

Field	Type	Required	Description
`tenant_id`	string	Yes	Parent tenant
`name`	string	Yes	Location name
`code`	string	No	Short identifier
`address`	object	Yes	Physical address
`phone`	string	No	Contact phone
`timezone`	string	Yes	IANA timezone
`settings`	object	No	Location settings

Response

{
  "id": "loc-new123",
  "name": "New Location",
  "code": "NL001",
  "status": "setup",
  "created_at": "2026-01-18T12:00:00Z"
}

Update Location

Request

PATCH /api/v1/locations/{location_id}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "Downtown - Main Street",
  "contact": {
    "manager": "New Manager Name"
  }
}

Update Business Hours

Request

PUT /api/v1/locations/{location_id}/hours
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "regular_hours": {
    "monday": {"open": "11:00", "close": "22:00"},
    "tuesday": {"open": "11:00", "close": "22:00"},
    "wednesday": {"open": "11:00", "close": "22:00"},
    "thursday": {"open": "11:00", "close": "22:00"},
    "friday": {"open": "11:00", "close": "23:00"},
    "saturday": {"open": "10:00", "close": "23:00"},
    "sunday": {"open": "10:00", "close": "21:00"}
  },
  "special_hours": [
    {
      "date": "2026-12-25",
      "closed": true,
      "reason": "Christmas Day"
    },
    {
      "date": "2026-12-31",
      "open": "11:00",
      "close": "02:00",
      "reason": "New Year's Eve"
    }
  ]
}

Update Location Settings

Request

PUT /api/v1/locations/{location_id}/settings
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "currency": "USD",
  "tax_rate": 8.625,
  "tax_inclusive": false,
  "tip_presets": [15, 18, 20, 25],
  "default_tip_percent": 18,
  "auto_gratuity": {
    "enabled": true,
    "party_size": 6,
    "percent": 18
  },
  "receipt_header": "Acme Restaurants",
  "receipt_footer": "Thank you for dining with us!",
  "order_number_prefix": "DT",
  "order_number_reset": "daily",
  "table_management": {
    "enabled": true,
    "auto_assign": false,
    "turn_time_minutes": 60
  },
  "kitchen": {
    "default_prep_time_minutes": 15,
    "rush_threshold": 20
  }
}

Location Status

Get Current Status

GET /api/v1/locations/{location_id}/status
Authorization: Bearer {access_token}

Response

{
  "location_id": "loc-xyz789",
  "is_open": true,
  "current_hours": {
    "open": "11:00",
    "close": "22:00"
  },
  "next_change": {
    "action": "close",
    "at": "2026-01-18T22:00:00-08:00"
  },
  "occupancy": {
    "current": 45,
    "capacity": 80,
    "waitlist": 3
  },
  "kitchen_status": "normal",
  "delivery_status": "active",
  "alerts": []
}

Update Status

PUT /api/v1/locations/{location_id}/status
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "status": "busy",
  "kitchen_status": "backed_up",
  "delivery_paused": true,
  "pause_reason": "Kitchen overwhelmed",
  "pause_duration_minutes": 30
}

Status Values

Status	Description
`open`	Normal operations
`busy`	Higher than normal volume
`closed`	Outside business hours
`temporarily_closed`	Closed for emergency
`setup`	Initial configuration

Service Areas

Get Delivery Zones

GET /api/v1/locations/{location_id}/delivery-zones
Authorization: Bearer {access_token}

Response

{
  "zones": [
    {
      "id": "zone-001",
      "name": "Zone 1 - Close",
      "radius_km": 3,
      "delivery_fee": 2.99,
      "min_order": 15.00,
      "estimated_time_minutes": 20
    },
    {
      "id": "zone-002",
      "name": "Zone 2 - Medium",
      "radius_km": 5,
      "delivery_fee": 4.99,
      "min_order": 25.00,
      "estimated_time_minutes": 35
    }
  ]
}

Create Delivery Zone

POST /api/v1/locations/{location_id}/delivery-zones
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "Zone 3 - Far",
  "type": "radius",
  "radius_km": 8,
  "delivery_fee": 6.99,
  "min_order": 35.00,
  "estimated_time_minutes": 45
}

Hardware Management

List Devices

GET /api/v1/locations/{location_id}/devices
Authorization: Bearer {access_token}

Response

{
  "devices": [
    {
      "id": "device-001",
      "type": "terminal",
      "name": "POS Terminal 1",
      "model": "Clover Station",
      "status": "online",
      "last_seen": "2026-01-18T12:00:00Z"
    },
    {
      "id": "device-002",
      "type": "kds",
      "name": "Grill Station KDS",
      "model": "OlympusEdge KDS",
      "status": "online",
      "last_seen": "2026-01-18T12:00:00Z"
    },
    {
      "id": "device-003",
      "type": "printer",
      "name": "Kitchen Printer",
      "model": "Epson TM-T88VI",
      "status": "online",
      "last_seen": "2026-01-18T12:00:00Z"
    }
  ]
}

Register Device

POST /api/v1/locations/{location_id}/devices
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "type": "terminal",
  "name": "POS Terminal 2",
  "activation_code": "ABC123XYZ"
}

Location Analytics

Get Summary

GET /api/v1/locations/{location_id}/analytics?period=today
Authorization: Bearer {access_token}

Response

{
  "period": "today",
  "date": "2026-01-18",
  "summary": {
    "orders": 145,
    "revenue": 4250.00,
    "avg_ticket": 29.31,
    "guests": 312,
    "table_turns": 2.4
  },
  "by_channel": {
    "dine_in": {"orders": 80, "revenue": 2800.00},
    "takeout": {"orders": 35, "revenue": 875.00},
    "delivery": {"orders": 30, "revenue": 575.00}
  },
  "vs_last_week": {
    "orders_change": 12.5,
    "revenue_change": 15.2
  }
}

Delete Location

Request

DELETE /api/v1/locations/{location_id}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "confirm": true,
  "transfer_data_to": "loc-other123"
}

Error Responses

Location Not Found (404)

{
  "error": {
    "code": "LOCATION_NOT_FOUND",
    "message": "Location does not exist"
  }
}

Location Limit Exceeded (403)

{
  "error": {
    "code": "LOCATION_LIMIT_EXCEEDED",
    "message": "Maximum locations reached for subscription plan",
    "current": 10,
    "limit": 10
  }
}

Tenants API - Organization management
Users API - User management
Orders API - Order processing

Overview​

Location Model​

List Locations​

Request​

Query Parameters​

Response​

Get Location​

Request​

Response​

Create Location​

Request​

Parameters​

Response​

Update Location​

Request​

Update Business Hours​

Request​

Update Location Settings​

Request​

Location Status​

Get Current Status​

Response​

Update Status​

Status Values​

Service Areas​

Get Delivery Zones​

Response​

Create Delivery Zone​

Hardware Management​

List Devices​

Response​

Register Device​

Location Analytics​

Get Summary​

Response​

Delete Location​

Request​

Error Responses​

Location Not Found (404)​

Location Limit Exceeded (403)​

Related Documentation​

Overview

Location Model

List Locations

Request

Query Parameters

Response

Get Location

Request

Response

Create Location

Request

Parameters

Response

Update Location

Request

Update Business Hours

Request

Update Location Settings

Request

Location Status

Get Current Status

Response

Update Status

Status Values

Service Areas

Get Delivery Zones

Response

Create Delivery Zone

Hardware Management

List Devices

Response

Register Device

Location Analytics

Get Summary

Response

Delete Location

Request

Error Responses

Location Not Found (404)

Location Limit Exceeded (403)

Related Documentation