---
feature: Provider availability
slug: availability
surface: provider
consumer: flutter
version: 1.0.0
status: ready
brd_version: "1.3"
brd_ids: [PROV-012, PROV-013]
business_rules: [BR-03, BR-08, BR-12]
decisions: [D3, DEC-04, DEC-05, SCR-21, TD-19, TD-78, TD-92]
schema_tables: [providers, provider_working_hours, provider_time_off, orders]
screens: [provider--home--01-paused, provider--home--02-online-*, provider--schedule--01-*, provider--schedule--02-*, provider--schedule--03-*]
related_docs: [orders.md, ../client/provider-selection.md, ../client/booking.md]
last_updated: 2026-10-25
---

# Provider availability — Flutter Integration Guide (provider)

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

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.0.0 | 2026-10-25 | Initial | Receiving switch, instant opt-in, weekly hours and time off. | Bind the provider home toggle and calendar to these routes. |

## Changelog

### 1.0.0 — 2026-10-25
- **Added:** Six availability routes; **Changed/Fixed/Removed:** None; **Breaking:** No.
- **Endpoints affected:** `GET /availability`, `PATCH /availability/receiving`, `PATCH /availability/instant`, `PUT /availability/working-hours/{weekday}`, `POST /availability/time-off`, `DELETE /availability/time-off/{time_off}`.
- **App action required:** Reload the returned stable availability resource after each mutation; ask for explicit instant terms acknowledgement.
- **BRD / decisions:** PROV-012/013, BR-03/08, D3, SCR-21, TD-92.

## 1. Business summary

An approved provider pauses or resumes receiving requests, independently enables instant requests after accepting their terms, and defines weekly Saudi-local hours plus time off. `can_receive_instant` is computed from approval, toggles, acknowledgement, current hours/time off and existing order overlap; use it for the home state.

## 2. User flow and screens

| Screen | Endpoint | App behavior |
|--------|----------|--------------|
| Paused/online home | `GET /availability`, `PATCH /availability/receiving` | Show persisted switch and `can_receive_instant`. |
| Instant settings | `PATCH /availability/instant` | Require explicit terms before enabling. |
| Schedule hours | `PUT /availability/working-hours/{weekday}` | Replace one day; an empty periods array closes it. |
| Time off | `POST /availability/time-off`, `DELETE /availability/time-off/{time_off}` | Create a full local date or bounded period, or reopen. |

## 3. Endpoints

All require a **provider bearer token with approved operational status**. Guest 401; pending/suspended provider 403. Mutations return the same resource as `GET /availability`.

| Method and path | Body/path | Validation | Captured success/error |
|-----------------|-----------|------------|------------------------|
| `GET /availability` | None | — | Postman: `provider.availability.show` › "200 Paused provider availability". |
| `PATCH /availability/receiving` | `is_accepting_bookings`: required boolean | Pause/resume requests. | Postman: `provider.availability.receiving` › "200 Receiving bookings with instant availability", "422 Missing required availability fields". |
| `PATCH /availability/instant` | `instant_enabled`: required boolean; `accept_instant_terms`: required true on enable | Saves `instant_terms_ack_at`; missing acceptance is typed `INSTANT_TERMS_REQUIRED` (422). | Postman: `provider.availability.instant` › "200 Instant opt-in while paused", "422 Instant terms must be accepted". |
| `PUT /availability/working-hours/{weekday}` | `weekday`: 0 Sunday to 6 Saturday; `periods`: array of `start_time`/`end_time` `HH:mm` | Ordered, nonoverlapping, end after start; empty closes day. | Postman: `provider.availability.working-hours` › "200 Sunday working periods", "422 Overlapping working periods", "422 Invalid period shape". |
| `POST /availability/time-off` | `date` (`YYYY-MM-DD`) or `starts_at`/`ends_at` (ISO), optional `reason` | Period end after start; local full date converted to UTC. | Postman: `provider.availability.time-off.store` › "201 Full local date closed", "422 Missing required availability fields". |
| `DELETE /availability/time-off/{time_off}` | Owned time-off UUID | Foreign/integer ID 404. | Postman: `provider.availability.time-off.destroy` › "200 Time off removed", "404 Another provider time off is hidden". |

`data` always contains `is_accepting_bookings`, `instant_enabled`, `instant_terms_ack_at`, `can_receive_instant`, `working_hours[]` (`id`, `weekday`, `start_time`, `end_time`), and `time_off[]`. **Real response:** Postman: `provider.availability.show` › "200 Paused provider availability". Every ID is a public UUID.

## 4. Statuses and enums

| Value | Meaning |
|-------|---------|
| `is_accepting_bookings=false` | New matching bookings excluded. |
| `instant_enabled=true` with acknowledgement | Opted into D3 instant requests; currently bookable only when `can_receive_instant=true`. |

## Data model

| Table | Read / write | Notes |
|-------|--------------|-------|
| `providers` | read/write | Receiving, instant flag and terms timestamp. |
| `provider_working_hours`, `provider_time_off` | read/write | Saudi-local weekly hours, UTC closure periods. |
| `orders` | read | TD-92 full-duration overlap. |

## 5. Dart models

Represent flags as booleans, `working_hours` and `time_off` as lists keyed by UUID, and acknowledgement/time-off timestamps as nullable offset dates. `weekday` starts at Sunday 0. Never infer instant eligibility from the toggles alone; use `can_receive_instant`.

## 6. Business rules enforced by the backend

| Rule | Backend | App response |
|------|---------|--------------|
| BR-03 | Only approved operational providers can mutate availability. | Show approval state on 403. |
| BR-08/D3 | Instant requires explicit terms, active hours and no overlap. | Show terms confirmation; refresh returned resource. |
| DEC-04/TD-92 | Pending, awaiting-payment and confirmed orders block full estimated duration. | Show unavailable slots after refresh. |

## 7. Notifications and real-time events

New requests produce `order_request_received` in the provider's shared notification inbox with public `data.order_id`. While the socket is connected the provider app also receives the live `order.requested` event ([provider orders §7](orders.md), [API conventions §9](../API_CONVENTIONS.md)); poll [provider orders](orders.md) only while it is disconnected. A production push (FCM) sender is not wired in this slice.

## 8. Localization and UI notes

Display weekly hours in Saudi local time. Arabic/English labels belong to the app; the API returns booleans and time values. Do not show provider home stats/earnings, which are outside this slice.

## 9. Integration checklist

- [ ] Bind home pause switch and instant confirmation to persisted flags.
- [ ] Replace a full weekday at a time; show overlap validation.
- [ ] Render time off by UUID and refresh the returned resource.
- [ ] Check approved-only 403, guest 401, and Arabic RTL.

## 10. Acceptance scenarios

| AC ID | Scenario | Expected |
|-------|----------|----------|
| AC-PROV-012 | Pause/resume and opt into instant | Flags persist; terms required on enable. |
| AC-PROV-013 | Define hours and close time | Overlap refused; time off suppresses instant eligibility. |

## 11. Open decisions and known limitations

TD-92 values are working assumptions: pending_provider/awaiting_payment/confirmed block full estimated duration; slots step 15 minutes, minimum lead 60, ETA 45, scheduled response 30 and payment 15. Values proposed by the project owner on 2026-10-25; DEC-05 stays Partly resolved until the client confirms the numbers. DEC-04 capacity/slot holds remain open. Fixed-amount provider commission is not supported at checkout until the earnings feature adds a snapshot column (TD-93); the simulator is a launch blocker (TD-94).

Out of scope: group booking (D2), packages and package sessions (D1), coupons, VAT on orders, wallet/payment/invoice screens, cancellation, transport choice and driver trips, execution beyond `confirmed`, chat, provider home stats/earnings, rating, and realtime sockets.