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 { "success": true, "httpStatus": "OK", "message": "Operation completed successfully", "action_time": "2025-10-26T10:30:45", "data": { // Actual response data goes here } } Error Response Structure { "success": false, "httpStatus": "BAD_REQUEST", "message": "Error description", "action_time": "2025-10-26T10:30:45", "data": "Error description" } Standard Response Fields Field Type Description success boolean Always true for successful operations, false for errors httpStatus string HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.) message string Human-readable message describing the operation result action_time string ISO 8601 timestamp of when the response was generated data object/string Response payload for success, error details for failures HTTP Method Badge Standards For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors: GET - Green (Safe, read-only operations) POST - Blue (Create new resources) PUT - Yellow (Update/replace entire resource) DELETE - Red (Remove resources) Endpoints 1. Get My Notifications Purpose: Retrieve all notifications for the authenticated user with pagination support Endpoint: GET {base_url}/notifications/me Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Query Parameters Parameter Type Required Description Validation Default page integer No Page number (1-based) Must be positive integer 1 size integer No Number of items per page Must be between 1-100 20 Success Response JSON Sample { "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 Field Description notifications Array of notification objects notifications[].id Unique identifier for the notification notifications[].userId ID of the user who received the notification notifications[].shopId ID of the associated shop (nullable) notifications[].serviceId Identifier for the service that generated the notification notifications[].serviceType Type of service (ORDER, PAYMENT, SHIPPING, etc.) notifications[].title Notification title notifications[].message Notification message content notifications[].type Notification type (INFO, WARNING, ERROR, SUCCESS) notifications[].priority Priority level (LOW, MEDIUM, HIGH, URGENT) notifications[].isRead Whether the notification has been read notifications[].data Additional metadata as JSON object notifications[].createdAt Timestamp when notification was created notifications[].readAt Timestamp when notification was read (null if unread) currentPage Current page number (1-based) pageSize Number of items per page totalElements Total number of notifications totalPages Total number of pages hasNext Whether there is a next page hasPrevious Whether there is a previous page isFirst Whether this is the first page isLast Whether this is the last page Error Response JSON Sample { "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: GET {base_url}/notifications/unread Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Query Parameters Parameter Type Required Description Validation Default page integer No Page number (1-based) Must be positive integer 1 size integer No Number of items per page Must be between 1-100 20 Success Response JSON Sample { "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: GET {base_url}/notifications/unread-count Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Unread count retrieved successfully", "action_time": "2025-10-26T10:30:45", "data": { "unreadCount": 12 } } Success Response Fields Field Description unreadCount Total number of unread notifications 4. Get Notification Summary Purpose: Get a summary of all notifications including total, unread, and read counts Endpoint: GET {base_url}/notifications/summary Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Success Response JSON Sample { "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 Field Description total Total number of notifications unread Number of unread notifications read Number of read notifications 5. Get Notifications by Shop Purpose: Retrieve notifications filtered by a specific shop Endpoint: GET {base_url}/notifications/shop/{shopId} Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Path Parameters Parameter Type Required Description Validation shopId UUID Yes Unique identifier of the shop Must be valid UUID format Query Parameters Parameter Type Required Description Validation Default page integer No Page number (1-based) Must be positive integer 1 size integer No Number of items per page Must be between 1-100 20 Success Response JSON Sample { "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: GET {base_url}/notifications/service/{serviceType} Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Path Parameters Parameter Type Required Description Validation serviceType string Yes Type of service (ORDER, PAYMENT, SHIPPING, PRODUCT, ACCOUNT) Must not be empty Query Parameters Parameter Type Required Description Validation Default page integer No Page number (1-based) Must be positive integer 1 size integer No Number of items per page Must be between 1-100 20 Success Response JSON Sample { "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: GET {base_url}/notifications/{notificationId} Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Path Parameters Parameter Type Required Description Validation notificationId UUID Yes Unique identifier of the notification Must be valid UUID format Success Response JSON Sample { "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 { "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: PUT {base_url}/notifications/{notificationId}/read Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Path Parameters Parameter Type Required Description Validation notificationId UUID Yes Unique identifier of the notification Must be valid UUID format Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Notification marked as read", "action_time": "2025-10-26T10:30:45", "data": null } Error Response JSON Sample { "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: PUT {base_url}/notifications/read Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Content-Type string Yes Must be application/json Request JSON Sample { "notificationIds": [ "123e4567-e89b-12d3-a456-426614174000", "223e4567-e89b-12d3-a456-426614174002", "323e4567-e89b-12d3-a456-426614174003" ] } Request Body Parameters Parameter Type Required Description Validation notificationIds array Yes Array of notification IDs to mark as read Must not be empty, each element must be valid UUID Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "3 notification(s) marked as read", "action_time": "2025-10-26T10:30:45", "data": null } Error Response JSON Sample { "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: PUT {base_url}/notifications/read-all Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Success Response JSON Sample { "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: DELETE {base_url}/notifications/{notificationId} Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Path Parameters Parameter Type Required Description Validation notificationId UUID Yes Unique identifier of the notification Must be valid UUID format Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Notification deleted successfully", "action_time": "2025-10-26T10:30:45", "data": null } Error Response JSON Sample { "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: DELETE {base_url}/notifications/batch Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Content-Type string Yes Must be application/json Request JSON Sample { "notificationIds": [ "123e4567-e89b-12d3-a456-426614174000", "223e4567-e89b-12d3-a456-426614174002", "323e4567-e89b-12d3-a456-426614174003" ] } Request Body Parameters Parameter Type Required Description Validation notificationIds array Yes Array of notification IDs to delete Must not be empty, each element must be valid UUID Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "3 notification(s) deleted successfully", "action_time": "2025-10-26T10:30:45", "data": null } Error Response JSON Sample { "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: DELETE {base_url}/notifications/read Access Level: 🔒 Protected (Requires Bearer Token Authentication) Authentication: Bearer Token Request Headers Header Type Required Description Authorization string Yes Bearer token for authentication Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "15 read notification(s) deleted successfully", "action_time": "2025-10-26T10:30:45", "data": 15 } Success Response Fields Field Description data Number of notifications that were deleted 14. Create In-App Notification( DON'T USE) Purpose: Create a new in-app notification (Internal service-to-service endpoint) Endpoint: POST {base_url}/notifications/in-app Access Level: 🔒 Protected (Requires API Key or Service Authentication) Authentication: API Key or Service Token Request Headers Header Type Required Description X-API-Key string Yes API key for service authentication Content-Type string Yes Must be application/json Request JSON Sample { "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 Parameter Type Required Description Validation userId UUID Yes ID of the user to receive the notification Must be valid UUID shopId UUID No ID of the associated shop Must be valid UUID if provided serviceId string Yes Identifier for the service that generated the notification Max length 100 characters serviceType string Yes Type of service (ORDER, PAYMENT, SHIPPING, PRODUCT, ACCOUNT) Max length 50 characters title string Yes Notification title Max length 255 characters message string Yes Notification message content Max length 1000 characters type string Yes Notification type (INFO, WARNING, ERROR, SUCCESS) Max length 50 characters priority string Yes Priority level (LOW, MEDIUM, HIGH, URGENT) Max length 20 characters data object No Additional metadata as JSON object Any valid JSON object Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Notification saved successfully", "action_time": "2025-10-26T10:30:45", "data": "123e4567-e89b-12d3-a456-426614174000" } Success Response Fields Field Description data UUID of the created notification Error Response JSON Sample { "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) { "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) { "success": false, "httpStatus": "UNAUTHORIZED", "message": "Token has expired", "action_time": "2025-10-26T10:30:45", "data": "Token has expired" } Forbidden - Access Denied (403) { "success": false, "httpStatus": "FORBIDDEN", "message": "Access denied: Insufficient permissions", "action_time": "2025-10-26T10:30:45", "data": "Access denied: Insufficient permissions" } Not Found (404) { "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) { "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