> ## Documentation Index
> Fetch the complete documentation index at: https://rideshare.docs.sumit-dhondikar.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Ride Lifecycle

> Follow a ride from the initial request through to completion, and learn which endpoints drive each status transition.

Every ride moves through a series of statuses from the moment it is booked to the moment it ends. Understanding these statuses helps you build a reliable integration and handle edge cases like cancellations.

## Status flow

```
REQUESTED → ACCEPTED → PICKED → COMPLETED
                ↓           ↓          ↓
            CANCELLED   CANCELLED  CANCELLED
```

<Steps>
  <Step title="REQUESTED">
    **Triggered by: Rider**

    When you call `POST /rides/book`, the ride is created with status `REQUESTED`. The ride is now visible to available drivers via `GET /rides/requested`.

    At this point, the ride has a `startOtp` and `endOtp` generated by the server. These one-time passwords are used to verify that the correct driver picks up and completes the ride.
  </Step>

  <Step title="ACCEPTED">
    **Triggered by: Driver**

    A driver calls `POST /rides/status/{rideId}` with `"status": "ACCEPTED"` and their `driverId`. The ride is assigned to that driver and `acceptedAt` is recorded.

    ```http theme={null}
    POST /rides/status/{rideId}
    ```

    ```json theme={null}
    {
      "status": "ACCEPTED",
      "driverId": "42"
    }
    ```

    The rider can now poll `GET /rides/status/{rideId}` to see the driver's live location as it updates via `driverLat` and `driverLon`.
  </Step>

  <Step title="PICKED">
    **Triggered by: Driver**

    When the driver arrives and picks up the rider, they call `POST /rides/status/{rideId}` with `"status": "PICKED"` and the `startOtp` provided by the rider. The server validates the OTP before accepting the transition.

    ```json theme={null}
    {
      "status": "PICKED",
      "driverId": "42",
      "otp": "7391"
    }
    ```

    The `startOtp` confirms the right driver picked up the right rider. If the OTP is incorrect, the request is rejected.
  </Step>

  <Step title="COMPLETED">
    **Triggered by: Driver**

    At the destination, the driver calls `POST /rides/status/{rideId}` with `"status": "COMPLETED"` and the `endOtp` provided by the rider. The server validates the OTP before marking the ride complete.

    ```json theme={null}
    {
      "status": "COMPLETED",
      "driverId": "42",
      "otp": "5824"
    }
    ```

    Once completed, the rider can submit a rating and feedback via `POST /rides/feedback/{rideId}`.
  </Step>
</Steps>

## Cancelling a ride

Either the rider or the driver can cancel a ride at any point before completion by calling `POST /rides/cancel/{rideId}`. The request body accepts an optional `reason` string.

```http theme={null}
POST /rides/cancel/{rideId}
```

```json theme={null}
{
  "reason": "Driver took too long to arrive"
}
```

The response includes the updated ride object with `status` set to `CANCELLED`, `cancelledBy` set to the user who cancelled, and `cancellationReason` populated with the reason you provided.

<Warning>
  Cancelling a ride after it has been accepted may incur a cancellation fee. Check the `cancellationFee` field on the returned ride object to see the amount charged. The fee is determined by platform policy based on the stage at which you cancel.
</Warning>

## Updating driver location

While a ride is active, the driver should call `POST /rides/location/{rideId}` periodically to broadcast their position to the rider.

```http theme={null}
POST /rides/location/{rideId}
```

```json theme={null}
{
  "lat": 12.9716,
  "lon": 77.5946
}
```

The ride object is returned with updated `driverLat`, `driverLon`, and `driverLocationUpdatedAt` fields.

## The Ride object

Below is a representative ride object as returned by the API.

```json theme={null}
{
  "id": 101,
  "status": "ACCEPTED",
  "riderId": 7,
  "driverId": 42,
  "pickupLocation": "MG Road, Bengaluru",
  "dropLocation": "Whitefield, Bengaluru",
  "pickupLat": 12.9758,
  "pickupLon": 77.6069,
  "dropLat": 12.9698,
  "dropLon": 77.7499,
  "pickupPlusCode": "7J4VXMJM+PQ",
  "dropPlusCode": "7J4VXP2Q+88",
  "pickupLandmark": "Near Cauvery Emporium, MG Road Metro Station",
  "dropLandmark": "ITPL Main Gate, Whitefield",
  "fare": 185.50,
  "paymentMode": "UPI",
  "paymentStatus": "PENDING",
  "paymentReference": null,
  "startOtp": "7391",
  "endOtp": "5824",
  "createdAt": "2026-04-02T10:15:00Z",
  "acceptedAt": "2026-04-02T10:16:30Z",
  "driverLat": 12.9720,
  "driverLon": 77.6050,
  "driverLocationUpdatedAt": "2026-04-02T10:18:00Z",
  "cancellationReason": null,
  "cancelledBy": null,
  "cancellationFee": null,
  "riderRating": null,
  "riderFeedback": null,
  "driverRating": null,
  "driverFeedback": null,
  "riderName": "Alice",
  "riderEmail": "alice@example.com"
}
```

### Key fields

| Field                     | Description                                                                              |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| `status`                  | Current lifecycle status: `REQUESTED`, `ACCEPTED`, `PICKED`, `COMPLETED`, or `CANCELLED` |
| `startOtp`                | One-time password the rider shares with the driver to confirm pickup                     |
| `endOtp`                  | One-time password the rider shares with the driver to confirm drop-off                   |
| `fare`                    | Estimated fare in INR calculated at booking time                                         |
| `paymentMode`             | Payment method chosen at booking (e.g. `UPI`, `CARD`, `CASH`)                            |
| `paymentStatus`           | Current payment status: `PENDING`, `PAID`, or `FAILED`                                   |
| `paymentReference`        | Razorpay payment ID, populated after successful payment verification                     |
| `driverLat` / `driverLon` | Driver's most recent reported coordinates                                                |
| `cancellationFee`         | Fee applied if the ride was cancelled after acceptance                                   |
| `riderRating`             | Rating (1–5) the rider gave the driver after completion                                  |
| `driverRating`            | Rating (1–5) the driver gave the rider after completion                                  |