---
feature: Halls, features, pricing, availability
slug: halls
surface: provider
consumer: vue
version: 1.2.1
status: ready
brd_version: "v1.0 (11-8-2026) + additional requirements"
brd_ids: [HPV-003, HPV-004, HPV-005, HPV-006]
business_rules: [BR-HALL-03, BR-HALL-04, BR-HALL-05, BR-HALL-06, BR-HALL-08]
decisions: [TD-14, TD-20]
schema_tables: [halls, hall_translations, hall_features, hall_feature_prices, hall_availability]
related_docs: [account.md, ../admin/hall-providers.md]
last_updated: 2026-11-15
---

# Halls, features, pricing, availability — Provider Dashboard Integration Guide

> **Base URL:** `{HOST}/api/v1/provider` · Shared rules: [API_CONVENTIONS.md](../API_CONVENTIONS.md)

## Quick reference

| | |
|---|---|
| Version | 1.2.1 (2026-11-15) — docs only: city source, upload hash, list filter, feature list; app action: none |
| Status | ready · BRD HPV-003..006 · BR-HALL-03..08 |
| Auth | Provider Bearer token. A suspended provider is refused everywhere. Another provider's hall is a 404. |

| Method | Path | Route name | Purpose |
|--------|------|------------|---------|
| `GET` | `/halls` | `provider.halls.index` | Own halls, lean rows (`?status=active\|inactive`, `?per_page=`) |
| `POST` | `/halls` | `provider.halls.store` | Create (active by default) |
| `GET` | `/halls/{hall}` | `provider.halls.show` | One hall |
| `PUT` | `/halls/{hall}` | `provider.halls.update` | Partial edit |
| `PUT` | `/halls/{hall}/status` | `provider.halls.status` | Activate (validated) / deactivate |
| `GET` | `/api/v1/cities` (public) | `shared.geo.cities` | Active cities for the `city_id` picker (`?country_id=<uuid>`, `?paginate=false`) |
| `GET` | `/hall-features` | `provider.hall-features.index` | Admin's active master list |
| `GET` | `/halls/{hall}/availability` | `provider.halls.availability.index` | Periods, soonest first |
| `POST` | `/halls/{hall}/availability` | `provider.halls.availability.store` | Add a period |
| `DELETE` | `/halls/{hall}/availability/{period}` | `provider.halls.availability.destroy` | Remove a period |

**Statuses:** hall `active` / `inactive`.
**Error codes:** `BUSINESS_RULE_VIOLATED` (feature not on the admin list; overlapping or multi-day period; suspended provider) · 422 validation · 404 not your hall.
**Open decisions:** None. The admin master feature list is built (`admin/hall-providers.md`, ADM-016); `/hall-features` stays empty until an admin creates at least one active feature, so show an empty state, not an error.

## 1. Business summary

A provider has any number of halls. Each hall has a base hourly price, a capacity and a selection of features taken from the admin's list, each with a fixed extra price per booking slot (set per hall, charged once per slot, no quantity). Availability is a set of periods, each inside one date; several per day are allowed. Deactivating a hall hides it from new requests and keeps everything linked to it; there is no delete.

## 2. Hall

**Request payload (`POST /halls`):**

```json
{
  "city_id": "a33b175a-65be-475b-81d5-60cbdda2139a",
  "address": "طريق الملك فهد، حي العليا",
  "capacity": 80,
  "hourly_price": 250.00,
  "features": [
    {
      "feature_id": "a33b1760-2c33-4b1d-9e66-c199a2c03a03",
      "price_per_slot": 100.00
    }
  ],
  "ar": {
    "name": "قاعة النخيل للمؤتمرات",
    "description": "قاعة تدريبية واسعة تتسع لـ 80 متدرباً."
  },
  "en": {
    "name": "Al-Nakheel Conference Hall",
    "description": "Spacious training hall accommodating up to 80 trainees."
  }
}
```

**Captured response (`GET /halls/{hall}`):**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "a33b1760-2aa4-4402-aab6-0c6bfea30608",
    "name": "قاعة النخيل للمؤتمرات",
    "status": {
      "value": "active",
      "label": "نشط"
    },
    "city": {
      "id": "a33b175a-65be-475b-81d5-60cbdda2139a",
      "name": "الرياض"
    },
    "capacity": 80,
    "hourly_price": "250.00",
    "created_at": "2026-11-15T11:25:05+00:00",
    "description": "قاعة تدريبية واسعة تتسع لـ 80 متدرباً.",
    "address": "طريق الملك فهد، حي العليا",
    "map_url": null,
    "photos": [
      "https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200"
    ],
    "features": [
      {
        "id": "a33b1760-2c33-4b1d-9e66-c199a2c03a03",
        "name": "جهاز عرض",
        "price_per_slot": "100.00"
      }
    ],
    "translations": {
      "ar": {
        "name": "قاعة النخيل للمؤتمرات",
        "description": "قاعة تدريبية واسعة تتسع لـ 80 متدرباً."
      },
      "en": {
        "name": "Al-Nakheel Conference Hall",
        "description": "Spacious training hall accommodating up to 80 trainees."
      }
    }
  }
}
```

Form fields (`POST` requires the first five; `PUT` accepts any):

| Field | Validation |
|-------|-----------|
| `ar.name`, `en.name` | required, string, max 255 |
| `ar.description`, `en.description` | nullable string, max 5000 |
| `city_id` | required, uuid of an active city |
| `address` | required, string, max 1000 |
| `map_url` | nullable url |
| `capacity` | required, integer 1–100000 |
| `hourly_price` | required, ≥ 0.01, at most 2 decimals |
| `photos` | array ≤ 10 of media hashes |
| `features` | array of `{feature_id (uuid, distinct), price_per_slot (≥ 0.01, 2 decimals)}`. **Omitted = unchanged; `[]` = clear.** |

The price of a booking (HPV-005) is computed later from these values; attendee count never affects it.

### Activation validation

A hall goes live (on create, and on `PUT /halls/{hall}/status` with `active`) only when the name in both languages, city, address, capacity above zero, base hourly price above zero and a price above zero on every selected feature are all present. Otherwise `422 BUSINESS_RULE_VIOLATED` names what is missing, e.g. `The hall cannot be activated until these are complete: Name (en), Feature price.`, and the hall stays as it was. Deactivating is never refused. Photos are optional.

### List row

`GET /halls` items carry only what the table shows: `id`, `name`, `status`, `city`, `capacity`, `hourly_price`, `cover_photo` (first photo URL or `null`), `features_count`, `created_at`. Photos, features, description, address and translations come from `GET /halls/{hall}` (and from create / edit / status responses).

**Captured list response (`GET /halls`):**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "data": [
      {
        "id": "a33b1760-2aa4-4402-aab6-0c6bfea30608",
        "name": "قاعة النخيل للمؤتمرات",
        "status": {
          "value": "active",
          "label": "نشط"
        },
        "city": {
          "id": "a33b175a-65be-475b-81d5-60cbdda2139a",
          "name": "الرياض"
        },
        "capacity": 80,
        "hourly_price": "250.00",
        "created_at": "2026-11-15T11:25:05+00:00",
        "cover_photo": null,
        "features_count": 1
      }
    ],
    "links": {
      "first": "http://localhost/api/v1/provider/halls?page=1",
      "last": "http://localhost/api/v1/provider/halls?page=1",
      "prev": null,
      "next": null
    },
    "meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 1,
      "links": [
        {"url": null, "label": "&laquo; Previous", "page": null, "active": false},
        {"url": "http://localhost/api/v1/provider/halls?page=1", "label": "1", "page": 1, "active": true},
        {"url": null, "label": "Next &raquo;", "page": null, "active": false}
      ],
      "path": "http://localhost/api/v1/provider/halls",
      "per_page": 15,
      "to": 1,
      "total": 1
    }
  }
}
```

## 2a. Cities, photos and the list filter

- **City:** `city_id` is the `id` from `GET /api/v1/cities?paginate=false` (public, no token; add `&country_id=<uuid>` from `GET /api/v1/countries` to narrow). Only active cities are listed and accepted; anything else is a 422.
- **Photos and logo:** upload each file with `POST /api/v1/client/upload` (multipart `file`; it needs no token), then send **`data.hash`** from the response in `photos` (array, max 10) or in the profile `logo`. Do not send `data.id` (an internal integer) or `data.url`. See `API_CONVENTIONS.md` → *Media upload*.
- **List filter:** the provider list takes `?status=active` or `?status=inactive`. `filters[is_active]` belongs to the admin list endpoints and is ignored here; the generic query string in the Postman collection is not this endpoint's contract.

## 3. Features

`GET /hall-features` → `[{ "id": "<uuid>", "name": "جهاز عرض", "icon": "<url>" }]`. Only active features are listed and accepted.

## 4. Availability

`POST /halls/{hall}/availability` — `{ "starts_at": "2026-11-25 08:00", "ends_at": "2026-11-25 14:00" }` (`Y-m-d H:i`, start in the future, end after start).

```json
{"status":"success","message":"Created successfully","data":{"id":"a33b1760-2e3d-4c7f-a109-e593d40d7a12","date":"2026-11-25","starts_at":"2026-11-25T08:00:00+00:00","ends_at":"2026-11-25T14:00:00+00:00"}}
```

Overlap or a period crossing midnight:

```json
{"status":"error","message":"The period must be within one day and must not overlap another period of this hall.","data":{"error_code":"BUSINESS_RULE_VIOLATED"}}
```

Touching periods (14:00 end, 14:00 start) are allowed. Times are stored and returned in the application timezone.

## 5. Types

```ts
export interface Hall {
  id: string; name: string; description: string | null;
  status: EnumValue<'active' | 'inactive'>;
  city: { id: string; name: string } | null;
  address: string; map_url: string | null; capacity: number;
  hourly_price: Money; photos: string[];
  features: { id: string; name: string; price_per_slot: Money }[];
  translations: Record<'ar' | 'en', { name: string; description: string | null }>;
  created_at: string;
}
export interface HallAvailability { id: string; date: string; starts_at: string; ends_at: string }
```

## 6. Known limitations

- Removing a period does not yet check it against booking requests; that arrives with `provider/bookings.md` (HPV-007+).
- `photos` returns the placeholder URL when empty (conventions).
- Concurrent period creation is serialised by a row lock on the hall (needs MySQL; covered logically, not by a concurrency test).

## Version history

| Version | Date | Type | Summary | Dashboard action required |
|---------|------|------|---------|---------------------------|
| 1.2.1 | 2026-11-15 | PATCH | Docs: where `city_id` and the upload `hash` come from, the list filter is `?status=`, feature list is built. New public `GET /cities`; `/countries` no longer 500s. | Enable the city picker and photo / logo upload. |
| 1.2.0 | 2026-11-15 | MINOR | List items are lean; detail unchanged. Not yet integrated, so no migration. | Build the list from the row fields. |
| 1.1.0 | 2026-11-15 | MINOR | Activation validation; a feature price must be above zero. | Show the 422 message when activating. |
| 1.0.0 | 2026-11-15 | Initial | Halls, features and prices, status, availability. | Integrate as described above. |

## Changelog

### 1.2.1 — 2026-11-15
- **Added:** public `GET /api/v1/cities` (`shared.geo.cities`).
- **Fixed:** `GET /api/v1/countries` returned 500 whenever the request matched a geo resolver (`X-Country` header, profile or IP); its rows now carry `id` (uuid) instead of `uuid`.
- **Breaking:** No (the countries endpoint never worked for these callers).
- **Dashboard action required:** Build the city picker from `/cities`; send `hash` for photos.
- **BRD / decisions:** HPV-003
### 1.2.0 — 2026-11-15
- **Changed:** `GET /halls` items shrink to the row fields above; `HallDetailsResource` serves every other response.
- **Breaking:** List items lose `photos`, `features`, `description`, `address`, `translations` (no app had integrated 1.1.0 yet).
- **App action required:** Use `GET /halls/{hall}` for the edit screen.
- **BRD / decisions:** HPV-003

### 1.1.0 — 2026-11-15
- **Added:** `HallIsReadyToActivate` rule on create and on activation.
- **Changed:** `features.*.price_per_slot` minimum is now 0.01 (was 0).
- **Breaking:** No (a price of 0 was not meaningful before either)
- **Dashboard action required:** Handle the activation refusal.
- **BRD / decisions:** HPV-003, HPV-004, TD-18

### 1.0.0 — 2026-11-15
- **Added:** halls CRUD without delete, status, master feature list, availability.
- **Breaking:** No
- **Dashboard action required:** Build the halls screens.
- **BRD / decisions:** HPV-003..006, BR-HALL-03..08, TD-14
