# Notification-nexgate-service(4)

# Notification Management

**Author**: Josh S. Sakweli, Backend Lead Team  
**Last Updated:** 2025-10-26  
**Version:** v1.0

**Base URL:** `https://api.nextgate.com/api/v1`

## Short Description

The Notification Management API provides a comprehensive in-app notification system that allows users to receive, manage, and interact with notifications across different services and shops. This API supports creating notifications, marking them as read, filtering by various criteria, and managing notification lifecycle with full pagination support.

## Hints

- **Authentication Required:** All endpoints under `/notifications` require Bearer token authentication except the `/notifications/in-app` endpoint
- **Pagination:** List endpoints support pagination with default `page=1` and `size=20`
- **Page Numbering:** API uses 1-based page numbering (page 1 is the first page)
- **Rate Limiting:** Standard rate limits apply (100 requests per minute per user)
- **Timezones:** All timestamps are returned in ISO 8601 format with local server time
- **Notification Types:** Supported types include `INFO`, `WARNING`, `ERROR`, `SUCCESS`
- **Priority Levels:** Supported priorities include `LOW`, `MEDIUM`, `HIGH`, `URGENT`
- **Service Types:** Examples include `ORDER`, `PAYMENT`, `SHIPPING`, `PRODUCT`, `ACCOUNT`

---

## Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

### Success Response Structure

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

```

### Error Response Structure

```json
{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-26T10:30:45",
  "data": "Error description"
}

```

### Standard Response Fields

<table id="bkmrk-field-type-descripti"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>success</td><td>boolean</td><td>Always true for successful operations, false for errors</td></tr><tr><td>httpStatus</td><td>string</td><td>HTTP status name (OK, BAD\_REQUEST, NOT\_FOUND, etc.)</td></tr><tr><td>message</td><td>string</td><td>Human-readable message describing the operation result</td></tr><tr><td>action\_time</td><td>string</td><td>ISO 8601 timestamp of when the response was generated</td></tr><tr><td>data</td><td>object/string</td><td>Response payload for success, error details for failures</td></tr></tbody></table>

---

## HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

- <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> - Green (Safe, read-only operations)
- <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> - Blue (Create new resources)
- <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> - Yellow (Update/replace entire resource)
- <span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span> - Red (Remove resources)

---

## Endpoints

### 1. Get My Notifications

**Purpose:** Retrieve all notifications for the authenticated user with pagination support

**Endpoint:** <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/notifications/me`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr></tbody></table>

#### Query Parameters

<table id="bkmrk-parameter-type-requi"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th><th>Default</th></tr></thead><tbody><tr><td>page</td><td>integer</td><td>No</td><td>Page number (1-based)</td><td>Must be positive integer</td><td>1</td></tr><tr><td>size</td><td>integer</td><td>No</td><td>Number of items per page</td><td>Must be between 1-100</td><td>20</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Notifications retrieved successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "notifications": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "userId": "987fcdeb-51a2-43d7-9c4e-123456789abc",
        "shopId": "456e7890-e89b-12d3-a456-426614174001",
        "serviceId": "ORD-2024-001",
        "serviceType": "ORDER",
        "title": "Order Confirmed",
        "message": "Your order #ORD-2024-001 has been confirmed",
        "type": "SUCCESS",
        "priority": "MEDIUM",
        "isRead": false,
        "data": {
          "orderId": "ORD-2024-001",
          "amount": 150.00,
          "currency": "USD"
        },
        "createdAt": "2025-10-26T09:15:30",
        "readAt": null
      }
    ],
    "currentPage": 1,
    "pageSize": 20,
    "totalElements": 45,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

```

#### Success Response Fields

<table id="bkmrk-field-description-no"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>notifications</td><td>Array of notification objects</td></tr><tr><td>notifications\[\].id</td><td>Unique identifier for the notification</td></tr><tr><td>notifications\[\].userId</td><td>ID of the user who received the notification</td></tr><tr><td>notifications\[\].shopId</td><td>ID of the associated shop (nullable)</td></tr><tr><td>notifications\[\].serviceId</td><td>Identifier for the service that generated the notification</td></tr><tr><td>notifications\[\].serviceType</td><td>Type of service (ORDER, PAYMENT, SHIPPING, etc.)</td></tr><tr><td>notifications\[\].title</td><td>Notification title</td></tr><tr><td>notifications\[\].message</td><td>Notification message content</td></tr><tr><td>notifications\[\].type</td><td>Notification type (INFO, WARNING, ERROR, SUCCESS)</td></tr><tr><td>notifications\[\].priority</td><td>Priority level (LOW, MEDIUM, HIGH, URGENT)</td></tr><tr><td>notifications\[\].isRead</td><td>Whether the notification has been read</td></tr><tr><td>notifications\[\].data</td><td>Additional metadata as JSON object</td></tr><tr><td>notifications\[\].createdAt</td><td>Timestamp when notification was created</td></tr><tr><td>notifications\[\].readAt</td><td>Timestamp when notification was read (null if unread)</td></tr><tr><td>currentPage</td><td>Current page number (1-based)</td></tr><tr><td>pageSize</td><td>Number of items per page</td></tr><tr><td>totalElements</td><td>Total number of notifications</td></tr><tr><td>totalPages</td><td>Total number of pages</td></tr><tr><td>hasNext</td><td>Whether there is a next page</td></tr><tr><td>hasPrevious</td><td>Whether there is a previous page</td></tr><tr><td>isFirst</td><td>Whether this is the first page</td></tr><tr><td>isLast</td><td>Whether this is the last page</td></tr></tbody></table>

#### Error Response JSON Sample

```json
{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-10-26T10:30:45",
  "data": "Token has expired"
}

```

---

### 2. Get Unread Notifications

**Purpose:** Retrieve only unread notifications for the authenticated user

**Endpoint:** <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/notifications/unread`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-1"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr></tbody></table>

#### Query Parameters

<table id="bkmrk-parameter-type-requi-1"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th><th>Default</th></tr></thead><tbody><tr><td>page</td><td>integer</td><td>No</td><td>Page number (1-based)</td><td>Must be positive integer</td><td>1</td></tr><tr><td>size</td><td>integer</td><td>No</td><td>Number of items per page</td><td>Must be between 1-100</td><td>20</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Notifications retrieved successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "notifications": [
      {
        "id": "223e4567-e89b-12d3-a456-426614174002",
        "userId": "987fcdeb-51a2-43d7-9c4e-123456789abc",
        "shopId": null,
        "serviceId": "PAY-2024-050",
        "serviceType": "PAYMENT",
        "title": "Payment Pending",
        "message": "Your payment for order #ORD-2024-001 is pending",
        "type": "WARNING",
        "priority": "HIGH",
        "isRead": false,
        "data": {
          "paymentId": "PAY-2024-050",
          "amount": 150.00
        },
        "createdAt": "2025-10-26T10:15:30",
        "readAt": null
      }
    ],
    "currentPage": 1,
    "pageSize": 20,
    "totalElements": 12,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": true
  }
}

```

---

### 3. Get Unread Count

**Purpose:** Get the total count of unread notifications for the authenticated user

**Endpoint:** <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/notifications/unread-count`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-2"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Unread count retrieved successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "unreadCount": 12
  }
}

```

#### Success Response Fields

<table id="bkmrk-field-description-un"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>unreadCount</td><td>Total number of unread notifications</td></tr></tbody></table>

---

### 4. Get Notification Summary

**Purpose:** Get a summary of all notifications including total, unread, and read counts

**Endpoint:** <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/notifications/summary`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-3"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification summary retrieved successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "total": 45,
    "unread": 12,
    "read": 33
  }
}

```

#### Success Response Fields

<table id="bkmrk-field-description-to"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>total</td><td>Total number of notifications</td></tr><tr><td>unread</td><td>Number of unread notifications</td></tr><tr><td>read</td><td>Number of read notifications</td></tr></tbody></table>

---

### 5. Get Notifications by Shop

**Purpose:** Retrieve notifications filtered by a specific shop

**Endpoint:** <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/notifications/shop/{shopId}`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-4"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr></tbody></table>

#### Path Parameters

<table id="bkmrk-parameter-type-requi-2"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th></tr></thead><tbody><tr><td>shopId</td><td>UUID</td><td>Yes</td><td>Unique identifier of the shop</td><td>Must be valid UUID format</td></tr></tbody></table>

#### Query Parameters

<table id="bkmrk-parameter-type-requi-3"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th><th>Default</th></tr></thead><tbody><tr><td>page</td><td>integer</td><td>No</td><td>Page number (1-based)</td><td>Must be positive integer</td><td>1</td></tr><tr><td>size</td><td>integer</td><td>No</td><td>Number of items per page</td><td>Must be between 1-100</td><td>20</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Notifications retrieved successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "notifications": [
      {
        "id": "323e4567-e89b-12d3-a456-426614174003",
        "userId": "987fcdeb-51a2-43d7-9c4e-123456789abc",
        "shopId": "456e7890-e89b-12d3-a456-426614174001",
        "serviceId": "PROD-2024-100",
        "serviceType": "PRODUCT",
        "title": "New Product Available",
        "message": "A new product has been added to your shop",
        "type": "INFO",
        "priority": "LOW",
        "isRead": true,
        "data": {
          "productId": "PROD-2024-100",
          "productName": "Sample Product"
        },
        "createdAt": "2025-10-25T14:20:00",
        "readAt": "2025-10-25T15:30:00"
      }
    ],
    "currentPage": 1,
    "pageSize": 20,
    "totalElements": 8,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": true
  }
}

```

---

### 6. Get Notifications by Service Type

**Purpose:** Retrieve notifications filtered by service type

**Endpoint:** <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/notifications/service/{serviceType}`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-5"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr></tbody></table>

#### Path Parameters

<table id="bkmrk-parameter-type-requi-4"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th></tr></thead><tbody><tr><td>serviceType</td><td>string</td><td>Yes</td><td>Type of service (ORDER, PAYMENT, SHIPPING, PRODUCT, ACCOUNT)</td><td>Must not be empty</td></tr></tbody></table>

#### Query Parameters

<table id="bkmrk-parameter-type-requi-5"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th><th>Default</th></tr></thead><tbody><tr><td>page</td><td>integer</td><td>No</td><td>Page number (1-based)</td><td>Must be positive integer</td><td>1</td></tr><tr><td>size</td><td>integer</td><td>No</td><td>Number of items per page</td><td>Must be between 1-100</td><td>20</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Notifications retrieved successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "notifications": [
      {
        "id": "423e4567-e89b-12d3-a456-426614174004",
        "userId": "987fcdeb-51a2-43d7-9c4e-123456789abc",
        "shopId": "456e7890-e89b-12d3-a456-426614174001",
        "serviceId": "ORD-2024-002",
        "serviceType": "ORDER",
        "title": "Order Shipped",
        "message": "Your order #ORD-2024-002 has been shipped",
        "type": "SUCCESS",
        "priority": "MEDIUM",
        "isRead": false,
        "data": {
          "orderId": "ORD-2024-002",
          "trackingNumber": "TRK123456789"
        },
        "createdAt": "2025-10-26T08:45:00",
        "readAt": null
      }
    ],
    "currentPage": 1,
    "pageSize": 20,
    "totalElements": 15,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": true
  }
}

```

---

### 7. Get Notification by ID

**Purpose:** Retrieve a single notification by its unique identifier

**Endpoint:** <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/notifications/{notificationId}`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-6"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr></tbody></table>

#### Path Parameters

<table id="bkmrk-parameter-type-requi-6"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th></tr></thead><tbody><tr><td>notificationId</td><td>UUID</td><td>Yes</td><td>Unique identifier of the notification</td><td>Must be valid UUID format</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification retrieved successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "userId": "987fcdeb-51a2-43d7-9c4e-123456789abc",
    "shopId": "456e7890-e89b-12d3-a456-426614174001",
    "serviceId": "ORD-2024-001",
    "serviceType": "ORDER",
    "title": "Order Confirmed",
    "message": "Your order #ORD-2024-001 has been confirmed",
    "type": "SUCCESS",
    "priority": "MEDIUM",
    "isRead": false,
    "data": {
      "orderId": "ORD-2024-001",
      "amount": 150.00,
      "currency": "USD"
    },
    "createdAt": "2025-10-26T09:15:30",
    "readAt": null
  }
}

```

#### Error Response JSON Sample

```json
{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Notification not found or access denied",
  "action_time": "2025-10-26T10:30:45",
  "data": "Notification not found or access denied"
}

```

---

### 8. Mark Notification as Read

**Purpose:** Mark a single notification as read

**Endpoint:** <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `{base_url}/notifications/{notificationId}/read`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-7"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr></tbody></table>

#### Path Parameters

<table id="bkmrk-parameter-type-requi-7"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th></tr></thead><tbody><tr><td>notificationId</td><td>UUID</td><td>Yes</td><td>Unique identifier of the notification</td><td>Must be valid UUID format</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification marked as read",
  "action_time": "2025-10-26T10:30:45",
  "data": null
}

```

#### Error Response JSON Sample

```json
{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Notification not found or access denied",
  "action_time": "2025-10-26T10:30:45",
  "data": "Notification not found or access denied"
}

```

---

### 9. Mark Multiple Notifications as Read

**Purpose:** Mark multiple notifications as read in a single request

**Endpoint:** <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `{base_url}/notifications/read`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-8"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr><tr><td>Content-Type</td><td>string</td><td>Yes</td><td>Must be application/json</td></tr></tbody></table>

#### Request JSON Sample

```json
{
  "notificationIds": [
    "123e4567-e89b-12d3-a456-426614174000",
    "223e4567-e89b-12d3-a456-426614174002",
    "323e4567-e89b-12d3-a456-426614174003"
  ]
}

```

#### Request Body Parameters

<table id="bkmrk-parameter-type-requi-8"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th></tr></thead><tbody><tr><td>notificationIds</td><td>array</td><td>Yes</td><td>Array of notification IDs to mark as read</td><td>Must not be empty, each element must be valid UUID</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "3 notification(s) marked as read",
  "action_time": "2025-10-26T10:30:45",
  "data": null
}

```

#### Error Response JSON Sample

```json
{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Some notifications not found or access denied",
  "action_time": "2025-10-26T10:30:45",
  "data": "Some notifications not found or access denied"
}

```

---

### 10. Mark All Notifications as Read

**Purpose:** Mark all unread notifications for the authenticated user as read

**Endpoint:** <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `{base_url}/notifications/read-all`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-9"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "All notifications marked as read",
  "action_time": "2025-10-26T10:30:45",
  "data": null
}

```

---

### 11. Delete Notification( DON'T USE)

**Purpose:** Delete a single notification permanently

**Endpoint:** <span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span> `{base_url}/notifications/{notificationId}`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-10"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr></tbody></table>

#### Path Parameters

<table id="bkmrk-parameter-type-requi-9"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th></tr></thead><tbody><tr><td>notificationId</td><td>UUID</td><td>Yes</td><td>Unique identifier of the notification</td><td>Must be valid UUID format</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification deleted successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": null
}

```

#### Error Response JSON Sample

```json
{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Notification not found or access denied",
  "action_time": "2025-10-26T10:30:45",
  "data": "Notification not found or access denied"
}

```

---

### 12. Batch Delete Notifications( DON'T USE)

**Purpose:** Delete multiple notifications in a single request

**Endpoint:** <span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span> `{base_url}/notifications/batch`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-11"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr><tr><td>Content-Type</td><td>string</td><td>Yes</td><td>Must be application/json</td></tr></tbody></table>

#### Request JSON Sample

```json
{
  "notificationIds": [
    "123e4567-e89b-12d3-a456-426614174000",
    "223e4567-e89b-12d3-a456-426614174002",
    "323e4567-e89b-12d3-a456-426614174003"
  ]
}

```

#### Request Body Parameters

<table id="bkmrk-parameter-type-requi-10"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th></tr></thead><tbody><tr><td>notificationIds</td><td>array</td><td>Yes</td><td>Array of notification IDs to delete</td><td>Must not be empty, each element must be valid UUID</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "3 notification(s) deleted successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": null
}

```

#### Error Response JSON Sample

```json
{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Some notifications not found or access denied",
  "action_time": "2025-10-26T10:30:45",
  "data": "Some notifications not found or access denied"
}

```

---

### 13. Delete All Read Notifications( DON'T USE)

**Purpose:** Delete all read notifications for the authenticated user

**Endpoint:** <span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span> `{base_url}/notifications/read`

**Access Level:** 🔒 Protected (Requires Bearer Token Authentication)

**Authentication:** Bearer Token

#### Request Headers

<table id="bkmrk-header-type-required-12"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Yes</td><td>Bearer token for authentication</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "15 read notification(s) deleted successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": 15
}

```

#### Success Response Fields

<table id="bkmrk-field-description-da"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>Number of notifications that were deleted</td></tr></tbody></table>

---

### 14. Create In-App Notification( DON'T USE)

**Purpose:** Create a new in-app notification (Internal service-to-service endpoint)

**Endpoint:** <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/notifications/in-app`

**Access Level:** 🔒 Protected (Requires API Key or Service Authentication)

**Authentication:** API Key or Service Token

#### Request Headers

<table id="bkmrk-header-type-required-13"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>X-API-Key</td><td>string</td><td>Yes</td><td>API key for service authentication</td></tr><tr><td>Content-Type</td><td>string</td><td>Yes</td><td>Must be application/json</td></tr></tbody></table>

#### Request JSON Sample

```json
{
  "userId": "987fcdeb-51a2-43d7-9c4e-123456789abc",
  "shopId": "456e7890-e89b-12d3-a456-426614174001",
  "serviceId": "ORD-2024-001",
  "serviceType": "ORDER",
  "title": "Order Confirmed",
  "message": "Your order #ORD-2024-001 has been confirmed and is being processed",
  "type": "SUCCESS",
  "priority": "MEDIUM",
  "data": {
    "orderId": "ORD-2024-001",
    "amount": 150.00,
    "currency": "USD",
    "items": 3
  }
}

```

#### Request Body Parameters

<table id="bkmrk-parameter-type-requi-11"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Validation</th></tr></thead><tbody><tr><td>userId</td><td>UUID</td><td>Yes</td><td>ID of the user to receive the notification</td><td>Must be valid UUID</td></tr><tr><td>shopId</td><td>UUID</td><td>No</td><td>ID of the associated shop</td><td>Must be valid UUID if provided</td></tr><tr><td>serviceId</td><td>string</td><td>Yes</td><td>Identifier for the service that generated the notification</td><td>Max length 100 characters</td></tr><tr><td>serviceType</td><td>string</td><td>Yes</td><td>Type of service (ORDER, PAYMENT, SHIPPING, PRODUCT, ACCOUNT)</td><td>Max length 50 characters</td></tr><tr><td>title</td><td>string</td><td>Yes</td><td>Notification title</td><td>Max length 255 characters</td></tr><tr><td>message</td><td>string</td><td>Yes</td><td>Notification message content</td><td>Max length 1000 characters</td></tr><tr><td>type</td><td>string</td><td>Yes</td><td>Notification type (INFO, WARNING, ERROR, SUCCESS)</td><td>Max length 50 characters</td></tr><tr><td>priority</td><td>string</td><td>Yes</td><td>Priority level (LOW, MEDIUM, HIGH, URGENT)</td><td>Max length 20 characters</td></tr><tr><td>data</td><td>object</td><td>No</td><td>Additional metadata as JSON object</td><td>Any valid JSON object</td></tr></tbody></table>

#### Success Response JSON Sample

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification saved successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": "123e4567-e89b-12d3-a456-426614174000"
}

```

#### Success Response Fields

<table id="bkmrk-field-description-da-1"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>UUID of the created notification</td></tr></tbody></table>

#### Error Response JSON Sample

```json
{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "userId": "must not be null",
    "title": "must not be blank",
    "message": "must not be blank"
  }
}

```

---

## Standard Error Types

### Application-Level Exceptions (400-499)

- **400 BAD\_REQUEST:** General invalid request data, random exceptions, or item already exists
- **401 UNAUTHORIZED:** Authentication issues (empty, invalid, expired, or malformed tokens)
- **403 FORBIDDEN:** Access denied, permission issues, verification failures, expired invitations
- **404 NOT\_FOUND:** Requested resource does not exist
- **422 UNPROCESSABLE\_ENTITY:** Validation errors with detailed field information
- **429 TOO\_MANY\_REQUESTS:** Rate limit exceeded

### Server-Level Exceptions (500+)

- **500 INTERNAL\_SERVER\_ERROR:** Unexpected server errors

---

## Error Response Examples

### Bad Request - General (400)

```json
{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "User ID cannot be null",
  "action_time": "2025-10-26T10:30:45",
  "data": "User ID cannot be null"
}

```

### Unauthorized - Token Issues (401)

```json
{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-10-26T10:30:45",
  "data": "Token has expired"
}

```

### Forbidden - Access Denied (403)

```json
{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Access denied: Insufficient permissions",
  "action_time": "2025-10-26T10:30:45",
  "data": "Access denied: Insufficient permissions"
}

```

### Not Found (404)

```json
{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Notification not found or access denied",
  "action_time": "2025-10-26T10:30:45",
  "data": "Notification not found or access denied"
}

```

### Validation Error (422)

```json
{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "userId": "must not be null",
    "title": "must not be blank",
    "serviceType": "must not be blank",
    "priority": "must not be blank"
  }
}

```

---

## Quick Reference Guide

### Common HTTP Status Codes

- **200 OK:** Successful GET/PUT request
- **201 Created:** Successful POST request
- **204 No Content:** Successful DELETE request
- **400 Bad Request:** Invalid request data
- **401 Unauthorized:** Authentication required/failed
- **403 Forbidden:** Insufficient permissions
- **404 Not Found:** Resource not found
- **422 Unprocessable Entity:** Validation errors
- **429 Too Many Requests:** Rate limit exceeded
- **500 Internal Server Error:** Server error

### Authentication Types

- **Bearer Token:** Include `Authorization: Bearer your_token` in headers (for user endpoints)
- **API Key:** Include `X-API-Key: your_key` in headers (for service-to-service endpoints)

### Data Format Standards

- **Dates:** Use ISO 8601 format (2025-10-26T14:30:00)
- **IDs:** All IDs use UUID format
- **Pagination:** Uses 1-based page numbering
- **Boolean Fields:** Use `true` or `false` (not 1/0)

### Notification Types

- **INFO:** General informational notifications
- **WARNING:** Warning or caution notifications
- **ERROR:** Error or failure notifications
- **SUCCESS:** Success or confirmation notifications

### Priority Levels

- **LOW:** Low priority, can be checked later
- **MEDIUM:** Normal priority
- **HIGH:** High priority, needs attention soon
- **URGENT:** Urgent priority, requires immediate attention

### Service Types

- **ORDER:** Order-related notifications
- **PAYMENT:** Payment-related notifications
- **SHIPPING:** Shipping and delivery notifications
- **PRODUCT:** Product-related notifications
- **ACCOUNT:** Account and profile notifications