---
feature: Driver availability
slug: availability
surface: delivery
consumer: flutter
version: 1.0.1
status: ready
brd_version: "1.3"
brd_ids: [DRIV-007]
business_rules: [BR-03, BR-16, BR-17]
decisions: [DEC-07, TD-133, TD-136, TD-138]
schema_tables: [drivers, vehicles, driver_districts, trip_offers]
screens: "driver--home--*"
last_updated: 2026-11-08
---

# Driver availability — Flutter integration guide

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.0.1 | 2026-11-08 | PATCH | Open-decisions note corrected: DEC-08 resolved (TD-149), FCM push and driver earnings built. | None. |
| 1.0.0 | 2026-10-28 | Initial | Cycle F contract. | Implement this flow. |

## Changelog

### 1.0.1 — 2026-11-08

- **Changed:** Open-decisions note corrected: DEC-08 resolved (TD-149), FCM push and driver earnings built.
- **Breaking:** No. **App action required:** None.

### 1.0.0 — 2026-10-28

- Added cycle F endpoints. App action required: integrate the flow and handle documented errors.

## 1. Business summary

Drivers toggle online availability and optionally update their location in the same request. Going offline withdraws pending offers and does not change an accepted trip (DEC-07 remains open).

## 2. User flow and screens

Eligibility requires an approved account, active user, online status, an active vehicle, no live trip and coverage. Coverage considers pickup OR dropoff districts, with city fallback; TD-136 awaits client confirmation. Availability requests use the dashboard-configured dispatch_availability_per_minute limit (default 60; TD-133).

## 3. Endpoints

Use an approved driver account and a bearer token for that app. Public record IDs are UUID strings (TD-19).

### PATCH /api/v1/delivery/availability

is_online is required boolean. lat and lng are optional together, numeric, latitude -90..90 and longitude -180..180.

Postman: `delivery.availability.update` › "200 Driver goes offline".

```json
{
    "status": "success",
    "message": "Availability updated successfully.",
    "data": {
        "is_online": false,
        "current_lat": 24.7136,
        "current_lng": 46.6753,
        "location_updated_at": null
    }
}
```

| HTTP | error_code | Meaning |
|------|------------|---------|
| 401 | `UNAUTHENTICATED` | Missing or expired token |
| 403 | `PERMISSION_DENIED` | Token issued by another app |
| 403 | `ACCOUNT_INACTIVE` | Account is not approved; inspect account_status and complete review. |
| 422 | `—` | Location requires both coordinates |
| 429 | `RATE_LIMITED` | Too many availability updates |

## 4. Statuses and enums

See the sequence and tab mapping in the flow above; status objects expose stable value and localized label.

## Data model

Tables: drivers, vehicles, driver_districts, trip_offers.

## 5. Dart models

Parse UUIDs as strings, monetary values as decimal strings, timestamps as ISO 8601, and nullable fields as nullable.

## 6. Business rules enforced by the backend

Eligibility requires an approved account, active user, online status, an active vehicle, no live trip and coverage. Coverage considers pickup OR dropoff districts, with city fallback; TD-136 awaits client confirmation. Availability requests use the dashboard-configured dispatch_availability_per_minute limit (default 60; TD-133).

## 7. Notifications and real-time events

Eligible drivers receive trip_offer_received inbox notifications with trip_id, order_id and status and the trip.offer event with the same payload keys.

## 8. Localization and UI notes

Use localized labels and test Arabic RTL and English.

## 9. Integration checklist

- Handle loading, empty and error states and refresh after realtime events.
- Handle the documented errors and nullable fields.

## 10. Acceptance scenarios

DRIV-007: see the corresponding cycle F feature tests.

## 11. Open decisions and known limitations

DEC-07 remains partly open. DEC-08 (who confirms driver arrival) is resolved (TD-149). FCM push is built (TD-141..143, TD-167) and driver earnings are built (TD-158).