---
feature: Current and past trips
slug: trips
surface: delivery
consumer: flutter
version: 1.1.1
status: ready
brd_version: "1.3"
brd_ids: [DRIV-016]
business_rules: [BR-22, BR-23]
decisions: [DEC-08, TD-132, TD-138, TD-139, TD-149]
schema_tables: [trips, trip_status_history, orders, drivers, vehicles]
screens: "Not captured"
last_updated: 2026-11-02
---

# Current and past trips — Flutter integration guide

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.1.1 | 2026-11-02 | PATCH | `amount_due_status` of a completed trip reads `available` (DEC-11 answer, TD-158). | None. |
| 1.1.0 | 2026-11-01 | MINOR | Trip card and details add `arrival_confirmed_by`, `can_confirm_arrival`, `completed_at`; `amount_due_status` and `net_earning` are filled once the trip is completed (TD-149). | Show the net earning on completed trips. |
| 1.0.0 | 2026-10-28 | Initial | Cycle F contract. | Implement this flow. |

## Changelog

### 1.1.0 — 2026-11-01

- **Added:** on `GET /trips` rows and `GET /trips/{trip}`: `arrival_confirmed_by` (`null` or `{value: driver|provider|customer, label}`), `can_confirm_arrival` (bool) and `completed_at`. `amount_due_status` (`{value,label}`: `pending`, `available`, `in_payout`, `paid`, `reversed`) and `net_earning` (SAR string) are set once the arrival is confirmed; they stay `null` on an `arrived` trip waiting for confirmation. Confirming is documented in [trip-execution](trip-execution.md). Postman: `delivery.trips.confirm-arrival` › "200 Driver confirms arrival and the trip completes".
- **Breaking:** No. **App action required:** show the net earning and its status on completed trips.

### 1.0.0 — 2026-10-28

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

## 1. Business summary

Drivers list their own current, completed or cancelled trips and inspect their own trip details.

## 2. User flow and screens

current includes accepted through to_customer; completed includes arrived and completed; cancelled includes cancelled (TD-132). amount_due_status and net_earning are null until the arrival is confirmed, then show the driver's earning (net = delivery fee − driver commission, TD-149). Provider display name is returned without phones or customer name.

## 3. Endpoints

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

### GET /api/v1/delivery/trips

tab is current, completed or cancelled; page and per_page control pagination.

Postman: `delivery.trips.index` › "200 Current driver trips".

```json
{
    "status": "success",
    "message": "",
    "data": {
        "data": [
            {
                "id": "01a18163-bd4f-71af-9e28-48a546ac0cab",
                "code": "TRP-qbcr88542290",
                "order_id": "01a18163-bd4d-727e-b73a-a83e94e8abaf",
                "status": {
                    "value": "to_provider",
                    "label": "Driver on the way to provider"
                },
                "pickup": {
                    "address": "Al Olaya Street, Riyadh",
                    "lat": 24.7136,
                    "lng": 46.6753,
                    "provider": {
                        "id": "01a18163-bd3a-7379-b892-cc8a62f9bdf6",
                        "name": "Emmett Larkin"
                    }
                },
                "dropoff": {
                    "address": "Al Nakheel Dist, Riyadh",
                    "lat": 24.7743,
                    "lng": 46.7386
                },
                "distance_km": "8.50",
                "est_duration_min": 22,
                "delivery_fee": "25.00",
                "amount_due_status": null,
                "net_earning": null,
                "created_at": "2026-10-28T07:22:39+00:00",
                "accepted_at": "2026-10-28T07:22:39+00:00"
            }
        ],
        "links": {
            "first": "http://localhost/api/v1/delivery/trips?tab=current&page=1",
            "last": "http://localhost/api/v1/delivery/trips?tab=current&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/delivery/trips?tab=current&page=1",
                    "label": "1",
                    "page": 1,
                    "active": true
                },
                {
                    "url": null,
                    "label": "Next &raquo;",
                    "page": null,
                    "active": false
                }
            ],
            "path": "http://localhost/api/v1/delivery/trips",
            "per_page": 15,
            "to": 1,
            "total": 1
        }
    }
}
```

| 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 | `—` | Invalid driver trip tab |

### GET /api/v1/delivery/trips/{trip}

The trip path parameter is a UUID.

Postman: `delivery.trips.show` › "200 Driver trip details".

```json
{
    "status": "success",
    "message": "",
    "data": {
        "id": "01a18163-b183-733d-98d3-6df34306d595",
        "code": "TRP-sgof91831880",
        "order_id": "01a18163-b172-734d-9f0c-3e5df9ae3ea5",
        "status": {
            "value": "accepted",
            "label": "Driver accepted"
        },
        "next_status": {
            "value": "to_provider",
            "label": "Driver on the way to provider"
        },
        "can_advance": true,
        "pickup": {
            "address": "Al Olaya Street, Riyadh",
            "lat": 24.7136,
            "lng": 46.6753,
            "provider": {
                "id": "01a18163-b150-7067-8f97-d829260c4742",
                "name": "Amos Gislason"
            }
        },
        "dropoff": {
            "address": "Al Nakheel Dist, Riyadh",
            "lat": 24.7743,
            "lng": 46.7386
        },
        "distance_km": "8.50",
        "est_duration_min": 22,
        "delivery_fee": "25.00",
        "amount_due_status": null,
        "net_earning": null,
        "vehicle": {
            "id": "01a18163-b17c-7122-b429-16f0c1b41877",
            "make_model": "Toyota Yaris",
            "plate_number": "CAR-oitu52200574",
            "vehicle_type": "car"
        },
        "timeline": [],
        "cancel_reason": 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. |
| 404 | `ENTITY_NOT_FOUND` | Trip not found |

## 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: trips, trip_status_history, orders, drivers, vehicles.

## 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

current includes accepted through to_customer; completed includes arrived and completed; cancelled includes cancelled (TD-132). amount_due_status and net_earning are null until the arrival is confirmed, then show the driver's earning (net = delivery fee − driver commission, TD-149). Provider display name is returned without phones or customer name.

## 7. Notifications and real-time events

trip.updated has trip_id, order_id, status and reason. A cancelled assigned trip sends trip_cancelled inbox data with trip_id, order_id and status.

## 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-016: see the corresponding cycle F feature tests.

## 11. Open decisions and known limitations

DEC-07 remains open; DEC-08 is resolved by TD-149. An earning is `available` as soon as the arrival is confirmed and payouts are requested in [earnings](earnings.md) (DEC-11, TD-158).
