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

# Notifications

> Fetch, read, and manage in-app notifications for ride events using the RideShare API.

<Note>
  All notification endpoints require an `Authorization` header with a valid bearer token. The API returns only notifications belonging to your authenticated account.

  ```bash theme={null}
  Authorization: Bearer <your_token>
  ```
</Note>

## Notification events

The RideShare API generates in-app notifications automatically as your ride moves through its lifecycle. Common event types you can expect to receive include:

| `eventType`         | When it fires                                        |
| ------------------- | ---------------------------------------------------- |
| `RIDE_REQUESTED`    | Your ride booking is confirmed and awaiting a driver |
| `RIDE_ACCEPTED`     | A driver has accepted your ride                      |
| `DRIVER_NEARBY`     | Your driver is approaching the pickup point          |
| `RIDE_STARTED`      | The trip has begun (status changed to `PICKED`)      |
| `RIDE_COMPLETED`    | The trip has ended                                   |
| `RIDE_CANCELLED`    | The ride was cancelled by either party               |
| `PAYMENT_CONFIRMED` | Payment has been processed successfully              |

Each notification object contains a `channel` (e.g. `IN_APP`), a human-readable `title` and `message`, and a `read` flag.

## Fetch notification history

Retrieve all notifications for your account, including unread and previously read items.

```bash theme={null}
GET /notifications/history
Authorization: Bearer <your_token>
```

**Example response**

```json theme={null}
{
  "unreadCount": 2,
  "notifications": [
    {
      "id": 301,
      "rideId": 1042,
      "title": "Driver on the way",
      "message": "Your driver Rajan has accepted the ride and is heading to MG Road.",
      "eventType": "RIDE_ACCEPTED",
      "channel": "IN_APP",
      "read": false,
      "status": "DELIVERED",
      "createdAt": "2026-04-02T10:17:05Z",
      "deliveredAt": "2026-04-02T10:17:06Z"
    },
    {
      "id": 298,
      "rideId": 1038,
      "title": "Ride completed",
      "message": "Your ride to Whitefield is complete. Total fare: ₹310.00.",
      "eventType": "RIDE_COMPLETED",
      "channel": "IN_APP",
      "read": true,
      "status": "DELIVERED",
      "createdAt": "2026-04-01T09:30:00Z",
      "deliveredAt": "2026-04-01T09:30:01Z"
    }
  ]
}
```

## Mark a notification as read

Mark a single notification as read by supplying its `id` as a path parameter.

```bash theme={null}
POST /notifications/mark-read/301
Authorization: Bearer <your_token>
```

**Response**

```json theme={null}
{
  "message": "Notification marked as read."
}
```

## Mark all notifications as read

Mark every unread notification in your account as read in a single call.

```bash theme={null}
POST /notifications/mark-all-read
Authorization: Bearer <your_token>
```

**Response**

```json theme={null}
{
  "message": "All notifications marked as read."
}
```

## Send a test notification

Trigger a test in-app notification to verify that your notification integration is working correctly.

```bash theme={null}
POST /notifications/test
Authorization: Bearer <your_token>
```

**Response**

```json theme={null}
{
  "message": "Test notification queued."
}
```

<Note>
  The test notification is queued asynchronously. Call `GET /notifications/history` a moment later to confirm delivery. Use this endpoint during development only — it does not correspond to a real ride event.
</Note>