> ## Documentation Index
> Fetch the complete documentation index at: https://twigz.arqqin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Notifications

> Real-time admin notification management and delivery

## Overview

Admin Notifications API provides real-time notification management for platform administrators. Notifications are triggered by key platform events (store approvals, payout requests, flagged reviews, order issues) and delivered via both in-app and email channels. All public functions require admin authorization.

**Location:** `convex/admins/adminNotifications.ts`

***

## Get Unread Notifications

Returns up to 50 unread notifications ordered by most recent. Designed for real-time subscription to power the notification bell indicator.

*No parameters required.*

<CodeGroup>
  ```typescript TypeScript theme={null}
  const unread = await convex.query(api.admins.adminNotifications.getUnreadNotifications, {});
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "_id": "n123456789",
      "_creationTime": 1700000000000,
      "type": "store_approval",
      "title": "New Store Pending Approval",
      "message": "Fresh Bakes has submitted a store application",
      "relatedId": "s123",
      "relatedType": "store",
      "priority": "high",
      "isRead": false,
      "metadata": {
        "storeName": "Fresh Bakes"
      },
      "createdAt": 1700000000000
    }
  ]
  ```
</ResponseExample>

<Note>
  Notification types: `store_approval`, `payout_request`, `review_flagged`, `order_issue`. Priority levels: `high`, `medium`, `low`.
</Note>

***

## Get All Notifications

Returns all notifications with offset-based pagination, ordered by most recent first.

<ParamField path="limit" type="number">
  Number of notifications to return. Defaults to `50`.
</ParamField>

<ParamField path="offset" type="number">
  Number of notifications to skip. Defaults to `0`.
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await convex.query(api.admins.adminNotifications.getAllNotifications, {
    limit: 20,
    offset: 0
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "notifications": [
      {
        "_id": "n123456789",
        "_creationTime": 1700000000000,
        "type": "payout_request",
        "title": "Payout Request Received",
        "message": "Pizza Palace requested a payout of 500 AED",
        "relatedId": "p456",
        "relatedType": "payout",
        "priority": "medium",
        "isRead": true,
        "metadata": {
          "storeName": "Pizza Palace",
          "amount": 500
        },
        "createdAt": 1700000000000
      }
    ],
    "totalCount": 85
  }
  ```
</ResponseExample>

***

## Get Notification Count

Returns the total number of unread notifications. Use this for badge counters.

*No parameters required.*

<CodeGroup>
  ```typescript TypeScript theme={null}
  const count = await convex.query(api.admins.adminNotifications.getNotificationCount, {});
  // count: 5
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  5
  ```
</ResponseExample>

***

## Mark As Read

Marks a single notification as read and records the read timestamp.

<ParamField path="notificationId" type="Id<'adminNotifications'>" required>
  The notification ID to mark as read
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.admins.adminNotifications.markAsRead, {
    notificationId: "n123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  null
  ```
</ResponseExample>

***

## Mark All As Read

Marks all unread notifications as read. Iterates through all notifications with `isRead: false` and updates each one.

*No parameters required.*

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.admins.adminNotifications.markAllAsRead, {});
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  null
  ```
</ResponseExample>

***

## Delete Notification

Permanently deletes a notification from the database.

<ParamField path="notificationId" type="Id<'adminNotifications'>" required>
  The notification ID to delete
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.admins.adminNotifications.deleteNotification, {
    notificationId: "n123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  null
  ```
</ResponseExample>

<Note>
  Notifications are also created internally via `createNotification` (an internal mutation) triggered by other platform events. When a notification is created, email delivery is automatically scheduled for all admins whose notification settings match the event category.
</Note>