# Owner API

Owners manage buildings, units, employees, reservations, billing, and promo codes.

## Role requirements

- Routes require the `owner` role.
- Creation/management actions require the owner to be approved (`status = active`).

## Dashboard & profile

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/owner/dashboard` | Revenue and occupancy dashboard. |
| GET | `/api/v1/owner/profile` | Get owner profile. |
| PUT | `/api/v1/owner/profile` | Update owner profile. |
| GET | `/api/v1/owner/calendar` | Unit availability calendar. |

## Permission templates

Owners can create reusable permission presets and assign direct permissions to employees.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/owner/permission-catalog` | List all assignable permissions. |
| GET | `/api/v1/owner/employees/{employee}/permissions` | Show an employee's direct permissions. |
| PUT | `/api/v1/owner/employees/{employee}/permissions` | Replace an employee's direct permissions. |
| GET | `/api/v1/owner/permission-templates` | List permission templates. |
| POST | `/api/v1/owner/permission-templates` | Create a permission template. |
| GET | `/api/v1/owner/permission-templates/{template}` | Show a template. |
| PUT | `/api/v1/owner/permission-templates/{template}` | Update a template. |
| DELETE | `/api/v1/owner/permission-templates/{template}` | Delete a template. |

> Templates are stored presets. Applying a template to an employee currently requires copying its permissions into the `PUT /api/v1/owner/employees/{employee}/permissions` endpoint.

## Shared owner/employee routes

The following routes accept both `owner` and `employee` roles. Employees are gated by granular permissions (`buildings.view`, `units.create`, etc.); owners are gated by approval status.

### Buildings

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/buildings` | List buildings. |
| POST | `/api/v1/buildings` | Create a building. |
| GET | `/api/v1/buildings/{building}` | Show a building. |
| PUT | `/api/v1/buildings/{building}` | Update a building. |
| DELETE | `/api/v1/buildings/{building}` | Delete a building. |
| PUT | `/api/v1/buildings/{building}/disable` | Disable a building. |
| POST | `/api/v1/buildings/{building}/photos` | Upload building photos. |
| GET | `/api/v1/buildings/{building}/facilities` | List building facilities. |
| POST | `/api/v1/buildings/{building}/facilities` | Assign facilities. |
| DELETE | `/api/v1/buildings/{building}/facilities/{facility}` | Unassign a facility. |
| GET | `/api/v1/buildings/{building}/units` | List units in a building. |
| POST | `/api/v1/buildings/{building}/units/bulk` | Bulk-create units. |

### Facilities

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/facilities` | List facilities. |
| POST | `/api/v1/facilities` | Create a facility. |
| GET | `/api/v1/facilities/{facility}` | Show a facility. |
| PUT | `/api/v1/facilities/{facility}` | Update a facility. |
| DELETE | `/api/v1/facilities/{facility}` | Delete a facility. |

### Units

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/owner/units` | List owner's units. |
| POST | `/api/v1/owner/units` | Create a unit. |
| GET | `/api/v1/owner/units/{unit}` | Show a unit. |
| PUT | `/api/v1/owner/units/{unit}` | Update a unit. |
| DELETE | `/api/v1/owner/units/{unit}` | Delete a unit. |
| POST | `/api/v1/owner/units/{unit}/photos` | Upload unit photos. |
| GET | `/api/v1/owner/units/{unit}/facilities` | List unit facilities. |
| POST | `/api/v1/owner/units/{unit}/facilities` | Assign facilities. |
| DELETE | `/api/v1/owner/units/{unit}/facilities/{facility}` | Unassign a facility. |

### Employees

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/employees` | List employees. |
| POST | `/api/v1/employees` | Create an employee. |
| GET | `/api/v1/employees/{employee}` | Show an employee. |
| PUT | `/api/v1/employees/{employee}` | Update an employee. |
| DELETE | `/api/v1/employees/{employee}` | Delete an employee. |

### Reservations

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/reservations` | List reservations. |
| POST | `/api/v1/reservations` | Create a reservation. |
| GET | `/api/v1/reservations/{reservation}` | Show a reservation. |
| PUT | `/api/v1/reservations/{reservation}` | Update a reservation. |
| DELETE | `/api/v1/reservations/{reservation}` | Cancel a reservation. |
| POST | `/api/v1/reservations/{reservation}/check-in` | Check in a guest. |
| POST | `/api/v1/reservations/{reservation}/check-out` | Check out a guest. |
| POST | `/api/v1/reservations/on-arrival/prepare` | Start an on-arrival booking. |
| POST | `/api/v1/reservations/on-arrival/validate` | Validate the on-arrival OTP. |
| POST | `/api/v1/reservations/on-arrival/verify` | Verify the on-arrival OTP. |

### Promo codes

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/promo-codes` | List promo codes. |
| POST | `/api/v1/promo-codes` | Create a promo code. |
| GET | `/api/v1/promo-codes/{promo_code}` | Show a promo code. |
| PUT | `/api/v1/promo-codes/{promo_code}` | Update a promo code. |
| DELETE | `/api/v1/promo-codes/{promo_code}` | Delete a promo code. |
| POST | `/api/v1/promo-codes/preview` | Preview promo-code discount. |

### Customers

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/owner/customers` | List customers scoped to the owner's buildings. |

> Owner/employee customer deletion is not exposed; only admins can delete customers via `DELETE /api/v1/customers/{customer}`.

## Owner-only billing

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/owner/invoices` | List invoices. |
| GET | `/api/v1/owner/invoices/{invoice}` | Show an invoice. |
| DELETE | `/api/v1/owner/invoices/{invoice}` | Delete an invoice. |
| GET | `/api/v1/transactions` | List transactions. |
| POST | `/api/v1/transactions` | Record a payment or refund. |
| GET | `/api/v1/transactions/{transaction}` | Show a transaction. |
| GET | `/api/v1/about-to-end` | Reservations about to end. |

## Unit availability

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/unit-availabilities` | List availability. |
| POST | `/api/v1/unit-availabilities/block` | Block dates. |
| POST | `/api/v1/unit-availabilities/unblock` | Unblock dates. |

For detailed schemas, see [`auto-generated.md`](../auto-generated.md).