Notification Management

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

Base ~~URL~~URL:: https://api.nextgate.com/api/v1

Short Description:

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

The Notification Management API ~~enables~~provides ~~authenticated~~a comprehensive in-app notification system that allows users to ~~manage~~receive, ~~their~~manage, ~~in-app~~and interact with notifications across different services and shops. This API supports creating notifications, ~~including retrieving paginated lists of notifications, viewing unread notifications, getting summary counts,~~ marking ~~notifications~~them as read, filtering by various criteria, and ~~deleting~~managing ~~them.~~notification ~~This API is designed for users to interact~~lifecycle with ~~their~~full ~~personal~~pagination ~~notification data securely and efficiently. It supports operations for individual, batch, and bulk actions on notifications.~~support.

Hints:

Authentication Required: All endpoints under /notifications require Bearer ~~Token~~token authentication (except the Authorization:/notifications/in-app ~~Bearer your_token~~).endpoint

~~Responses~~Pagination: ~~use~~List ~~UTC~~endpoints ~~timestamps~~support inpagination ~~ISO~~with ~~8601 format (e.g.,~~default 2025-10-18T11:32:00Zpage=1). and size=20

Page Numbering: API uses 1-based page numbering (page 1 is the first page)

Rate ~~limiting:~~Limiting: Standard rate limits apply (100 requests per minute per ~~user.~~user)

~~Pagination~~Timezones: isAll ~~used~~timestamps ~~for~~are ~~list~~returned ~~endpoints~~in ISO 8601 format with ~~default~~local ~~page=1~~server ~~and size=20.~~time

~~Testing/sandbox~~Notification ~~information:~~Types: ~~Use~~Supported ~~the~~types ~~sandbox environment at~~include https://sandbox.nextgate.com/api/v1INFO, ~~for~~WARNING, ~~development.~~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-18T11:32:00Z"26T10:30:45", "data": { // Actual response data goes here } }

Error Response Structure

{ "success": false, "httpStatus": "BAD_REQUEST", "message": "Error description", "action_time": "2025-10-18T11:32:00Z"26T10:30:45", "data": "Error description" // or detailed error object }

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~~ - GET - Green (Safe, read-only operations)

~~POST~~ - POST - Blue (Create new resources)
~~PUT~~ - PUT - Yellow (Update/replace entire resource)
~~PATCH~~ - ~~PATCH~~ ~~- Orange (Partial updates)~~

~~DELETE~~ - DELETE - Red (Remove resources)

Endpoints

1. Get My Notifications

~~Purpose~~Purpose:: ~~Retrieves~~Retrieve aall ~~paginated~~notifications ~~list of~~for the authenticated ~~user's~~user ~~in-app~~with ~~notifications.~~pagination support

~~Endpoint~~Endpoint:: GET {base_url}/notifications/me

Access ~~Level~~Level:: 🔒 Protected (~~Authenticated~~Requires ~~user~~Bearer ~~only)~~Token Authentication)

~~Authentication~~Authentication:: Bearer Token

Request Headers:

Header Type Required Description

Authorization string Yes Bearer token for authentication (Bearer your_token)

Query Parameters:

Parameter Type Required Description Validation Default

page integer No Page number ~~for pagination~~(1-based) ~~Min:~~Must 1be positive integer 1

size integer No Number of items per page ~~Min:~~Must 1,be ~~Max:~~between 1-100 20

Success Response JSON Sample:

{ "success": true, "httpStatus": "OK", "message": "Notifications retrieved successfully", "action_time": "2025-10-18T11:32:00Z"26T10:30:45", "data": { "content"notifications": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "userId": "223e4567-987fcdeb-51a2-43d7-9c4e-123456789abc", "shopId": "456e7890-e89b-12d3-a456-426614174001", "shopId": "323e4567-e89b-12d3-a456-426614174002", "serviceId": "service-123"ORD-2024-001", "serviceType": "ORDER", "title": "Order Shipped"Confirmed", "message": "Your order #ORD-2024-001 has been shipped."confirmed", "type": "INFO"SUCCESS", "priority": "NORMAL"MEDIUM", "isRead": false, "data": { "orderId": "order-456"ORD-2024-001", "amount": 150.00, "currency": "USD" }, "createdAt": "2025-10-17T10:00:00Z"26T09:15:30", "readAt": null } ], "pageable"currentPage": { "sort": { "sorted": true, "unsorted": false, "empty": false }, "pageNumber": 0,1, "pageSize": 20, "offset"totalElements": 0,45, "paged"totalPages": 3, "hasNext": true, "unpaged"hasPrevious": false },false, "totalPages": 1, "totalElements": 1, "last"isFirst": true, "numberOfElements": 1, "first": true, "size": 20, "number": 0, "sort": { "sorted": true, "unsorted": false, "empty": false }, "empty"isLast": false } }

Success Response Fields:

Field Description

contentnotifications Array of ~~notifications~~notification objects

content[notifications[].id Unique identifier offor the notification

content[notifications[].userId ID of the user ~~receiving~~who received the notification

content[notifications[].shopId ID of the associated shop (~~if applicable)~~nullable)

content[notifications[].serviceId IDIdentifier offor the service ~~generating~~that generated the notification

content[notifications[].serviceType Type of service (~~e.g.,~~ORDER, ~~ORDER)~~PAYMENT, SHIPPING, etc.)

content[notifications[].title ~~Title~~Notification ~~of the notification~~title

content[notifications[].message ~~Body~~Notification message ~~of the notification~~content

content[notifications[].type ~~Type~~Notification ~~of notification~~type (~~e.g.,~~INFO, ~~INFO)~~WARNING, ERROR, SUCCESS)

content[notifications[].priority Priority level (~~e.g.,~~LOW, ~~NORMAL)~~MEDIUM, HIGH, URGENT)

content[notifications[].isRead Whether the notification has been read

content[notifications[].data Additional ~~data~~metadata as ~~key-value~~JSON ~~pairs~~object

content[notifications[].createdAt Timestamp when notification was created

content[notifications[].readAt Timestamp when notification was read (null if unread)

pageablecurrentPage ~~Pagination~~Current ~~details~~page number (1-based)

pageSize Number of items per page
totalElements Total number of notifications
totalPages Total number of pages

totalElements ~~Total number of notifications~~
lasthasNext Whether ~~this~~there is ~~the~~a ~~last~~next page

numberOfElementshasPrevious ~~Number~~Whether ofthere ~~elements~~is ina ~~this~~previous page

firstisFirst Whether this is the first page

size ~~Page size~~
number ~~Current page number~~
sort ~~Sorting details~~
emptyisLast Whether ~~the page~~this is ~~empty~~the last page

Error Response JSON Sample:

{ "success": false, "httpStatus": "BAD_REQUEST"UNAUTHORIZED", "message": "InvalidToken paginationhas parameters"expired", "action_time": "2025-10-18T11:32:00Z"26T10:30:45", "data": "InvalidToken paginationhas parameters"expired" }

~~Standard Error Types~~:

400 BAD_REQUEST~~: Invalid pagination parameters~~

401 UNAUTHORIZED~~: Invalid or expired token~~

404 NOT_FOUND~~: No notifications found~~

2. Get Unread Notifications

~~Purpose~~Purpose:: ~~Retrieves~~Retrieve aonly ~~paginated~~unread ~~list~~notifications offor the authenticated ~~user's unread in-app notifications.~~user

~~Endpoint~~Endpoint:: GET {base_url}/notifications/unread

Access ~~Level~~Level:: 🔒 Protected (~~Authenticated~~Requires ~~user~~Bearer ~~only)~~Token Authentication)

~~Authentication~~Authentication:: Bearer Token

Request Headers:

Header Type Required Description

Authorization string Yes Bearer token for authentication (Bearer your_token)

Query Parameters:

Parameter Type Required Description Validation Default

page integer No Page number ~~for pagination~~(1-based) ~~Min:~~Must 1be positive integer 1

size integer No Number of items per page ~~Min:~~Must 1,be ~~Max:~~between 1-100 20

Success Response JSON Sample:

{ "success": true, "httpStatus": "OK", "message": "Unread notificationsNotifications retrieved successfully", "action_time": "2025-10-18T11:32:00Z"26T10:30:45", "data": { "content"notifications": [ { "id": "123e4567-223e4567-e89b-12d3-a456-426614174000"426614174002", "userId": "223e4567-e89b-12d3-a456-426614174001"987fcdeb-51a2-43d7-9c4e-123456789abc", "shopId": "323e4567-e89b-12d3-a456-426614174002",null, "serviceId": "service-123"PAY-2024-050", "serviceType": "ORDER"PAYMENT", "title": "OrderPayment Shipped"Pending", "message": "Your payment for order has#ORD-2024-001 beenis shipped."pending", "type": "INFO"WARNING", "priority": "NORMAL"HIGH", "isRead": false, "data": { "orderId"paymentId": "order-456"PAY-2024-050", "amount": 150.00 }, "createdAt": "2025-10-17T10:00:00Z"26T10:15:30", "readAt": null } ], "pageable"currentPage": { "sort": { "sorted": true, "unsorted": false, "empty": false }, "pageNumber": 0,1, "pageSize": 20, "offset"totalElements": 0, "paged": true, "unpaged": false },12, "totalPages": 1, "totalElements"hasNext": 1,false, "last"hasPrevious": false, "isFirst": true, "numberOfElements"isLast": 1, "first": true, "size": 20, "number": 0, "sort": { "sorted": true, "unsorted": false, "empty": false }, "empty": falsetrue } }

3. Get Unread Count

~~Success~~Purpose: ~~Response~~Get ~~Fields~~:
the total

~~Field~~ ~~Description~~
content ~~Array~~count of unread notifications ~~(same structure as Get My Notifications)~~
pageable ~~Pagination details~~
totalPages ~~Total number of pages~~
totalElements ~~Total number of unread notifications~~
last ~~Whether this is the last page~~
numberOfElements ~~Number of elements in this page~~
first ~~Whether this is the first page~~
size ~~Page size~~
number ~~Current page number~~
sort ~~Sorting details~~
empty ~~Whether the page is empty~~

~~Error Response JSON Sample~~:

{ "success": false, "httpStatus": "BAD_REQUEST", "message": "Invalid pagination parameters", "action_time": "2025-10-18T11:32:00Z", "data": "Invalid pagination parameters" }

~~Standard Error Types~~:

400 BAD_REQUEST~~: Invalid pagination parameters~~

401 UNAUTHORIZED~~: Invalid or expired token~~

404 NOT_FOUND~~: No unread notifications found~~

~~3. Get Notification Summary~~

~~Purpose~~~~: Retrieves a summary of~~for the authenticated ~~user's notification counts (total, unread, read).~~user

~~Endpoint~~Endpoint:: GET {base_url}/notifications/summaryunread-count

Access ~~Level~~Level:: 🔒 Protected (~~Authenticated~~Requires ~~user~~Bearer ~~only)~~Token Authentication)

~~Authentication~~Authentication:: Bearer Token

Request Headers:

Header Type Required Description

Authorization string Yes Bearer token for authentication (Bearer your_token)

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-18T11:32:00Z"26T10:30:45", "data": { "totalCount"total": 10,45, "unreadCount"unread": 3,12, "readCount"read": 733 } }

Success Response Fields:

Field Description

totalCounttotal Total number of notifications

unreadCountunread Number of unread notifications

readCountread Number of read notifications

~~Error~~
~~Response~~
5. ~~JSON~~Get ~~Sample~~:
Notifications
{by "success": false, "httpStatus": "BAD_REQUEST", "message": "User ID cannot be null", "action_time": "2025-10-18T11:32:00Z", "data": "User ID cannot be null" }
Shop

~~Standard~~Purpose: ~~Error~~Retrieve ~~Types~~:
notifications
filtered
400 BAD_REQUEST~~: User ID issues~~

401 UNAUTHORIZED~~: Invalid or expired token~~

~~4. Mark Notification as Read~~

~~Purpose~~~~: Marks~~by a specific ~~notification as read for the authenticated user.~~shop

~~Endpoint~~Endpoint:: ~~PATCH~~GET {base_url}/notifications/shop/{notificationId}/readshopId}

Access ~~Level~~Level:: 🔒 Protected (~~Authenticated~~Requires ~~user~~Bearer ~~only)~~Token Authentication)

~~Authentication~~Authentication:: Bearer Token

Request Headers:

Header Type Required Description

Authorization string Yes Bearer token for authentication (Bearer your_token)

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 ~~Valid~~Must be valid UUID format

Success Response JSON Sample:

{ "success": true, "httpStatus": "OK", "message": "Notification markedretrieved as read"successfully", "action_time": "2025-10-18T11:32:00Z"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 } }

~~Success Response Fields~~:

~~Field~~ ~~Description~~
data ~~Null or optional details~~

Error Response JSON Sample:

{ "success": false, "httpStatus": "NOT_FOUND", "message": "Notification not found or access denied", "action_time": "2025-10-18T11:32:00Z"26T10:30:45", "data": "Notification not found or access denied" }

~~Standard~~
~~Error~~
8. ~~Types~~:

400 BAD_REQUEST~~: Invalid notification ID~~

401 UNAUTHORIZED~~: Invalid or expired token~~

403 FORBIDDEN~~: Access denied (not user's notification)~~

404 NOT_FOUND:Mark Notification ~~not found~~

~~5. Batch Mark~~ as Read

~~Purpose~~Purpose:: ~~Marks~~Mark ~~multiple~~a ~~notifications~~single notification as read ~~for the authenticated user.~~

~~Endpoint~~Endpoint:: ~~PATCH~~PUT {base_url}/notifications/batch/{notificationId}/read

Access ~~Level~~Level:: 🔒 Protected (~~Authenticated~~Requires ~~user~~Bearer ~~only)~~Token Authentication)

~~Authentication~~Authentication:: Bearer Token

Request Headers:

Header Type Required Description

Authorization string Yes Bearer token for authentication (Bearer your_token)

~~Request JSON Sample~~:

{ "notificationIds": [ "123e4567-e89b-12d3-a456-426614174000", "223e4567-e89b-12d3-a456-426614174001" ] }

~~Request Body~~
Path Parameters:

Parameter Type Required Description Validation

notificationIds ~~array~~ ~~Yes~~ ~~List of notification IDs to mark as read~~ ~~Non-empty array of valid UUIDs~~

~~Success Response JSON Sample~~:

{ "success": true, "httpStatus": "OK", "message": "2 notification(s) marked as read", "action_time": "2025-10-18T11:32:00Z", "data": null }

~~Success Response Fields~~:

~~Field~~ ~~Description~~
data ~~Null or optional details~~

~~Error Response JSON Sample~~:

{ "success": false, "httpStatus": "BAD_REQUEST", "message": "Notification IDs cannot be empty", "action_time": "2025-10-18T11:32:00Z", "data": "Notification IDs cannot be empty" }

~~Standard Error Types~~:

400 BAD_REQUEST~~: Empty or invalid notification IDs~~

401 UNAUTHORIZED~~: Invalid or expired token~~

403 FORBIDDEN~~: Access denied for some notifications~~

404 NOT_FOUND~~: Some notifications not found~~

~~6. Mark All as Read~~

~~Purpose~~~~: Marks all notifications as read for the authenticated user.~~

~~Endpoint~~: ~~PATCH~~ {base_url}/notifications/read

~~Access Level~~~~: 🔒 Protected (Authenticated user only)~~

~~Authentication~~~~: Bearer Token~~

~~Request Headers~~:

~~Header~~ ~~Type~~ ~~Required~~ ~~Description~~
Authorization ~~string~~ ~~Yes~~ ~~Bearer token for authentication (~~Bearer your_token)

~~Success Response JSON Sample~~:

{ "success": true, "httpStatus": "OK", "message": "All notifications marked as read", "action_time": "2025-10-18T11:32:00Z", "data": null }

~~Success Response Fields~~:

~~Field~~ ~~Description~~
data ~~Null or optional details~~

~~Error Response JSON Sample~~:

{ "success": false, "httpStatus": "NOT_FOUND", "message": "User not found", "action_time": "2025-10-18T11:32:00Z", "data": "User not found" }

~~Standard Error Types~~:

401 UNAUTHORIZED~~: Invalid or expired token~~

404 NOT_FOUND~~: User not found~~

~~7. Delete Notification~~

~~Purpose~~~~: Deletes a specific notification for the authenticated user.~~

~~Endpoint~~: ~~DELETE~~ {base_url}/notifications/{notificationId}

~~Access Level~~~~: 🔒 Protected (Authenticated user only)~~

~~Authentication~~~~: Bearer Token~~

~~Request Headers~~:

~~Header~~ ~~Type~~ ~~Required~~ ~~Description~~
Authorization ~~string~~ ~~Yes~~ ~~Bearer token for authentication (~~Bearer your_token)

~~Path Parameters~~:

~~Parameter~~ ~~Type~~ ~~Required~~ ~~Description~~ ~~Validation~~
notificationId UUID Yes Unique identifier of the notification ~~Valid~~Must be valid UUID format

Success Response JSON Sample:

{ "success": true, "httpStatus": "OK", "message": "Notification deletedmarked successfully"as read", "action_time": "2025-10-18T11:32:00Z"26T10:30:45", "data": null }

~~Success Response Fields~~:

~~Field~~ ~~Description~~
data ~~Null or optional details~~

Error Response JSON Sample:

{ "success": false, "httpStatus": "NOT_FOUND", "message": "Notification not found or access denied", "action_time": "2025-10-18T11:32:00Z"26T10:30:45", "data": "Notification not found or access denied" }

~~Standard Error Types~~:

400 BAD_REQUEST~~: Invalid notification ID~~

401 UNAUTHORIZED~~: Invalid or expired token~~

403 FORBIDDEN~~: Access denied~~

404 NOT_FOUND~~: Notification not found~~

8.
9. ~~Batch~~Mark ~~Delete~~Multiple Notifications
as Read
~~Purpose~~Purpose:: ~~Deletes~~Mark multiple notifications ~~for~~as ~~the~~read ~~authenticated~~in ~~user.~~a single request

~~Endpoint~~Endpoint:: ~~DELETE~~PUT {base_url}/notifications/batchread

Access ~~Level~~Level:: 🔒 Protected (~~Authenticated~~Requires ~~user~~Bearer ~~only)~~Token Authentication)

~~Authentication~~Authentication:: Bearer Token

Request Headers:
(Beareryour_token)

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-426614174001"426614174002", "323e4567-e89b-12d3-a456-426614174003" ] }

Request Body Parameters:

Parameter Type Required Description Validation

notificationIds array Yes ~~List~~Array of notification IDs to ~~delete~~mark as read ~~Non-empty~~Must ~~array~~not ofbe empty, each element must be valid ~~UUIDs~~UUID

Success Response JSON Sample:

{ "success": true, "httpStatus": "OK", "message": "23 notification(s) deletedmarked successfully"as read", "action_time": "2025-10-18T11:32:00Z"26T10:30:45", "data": null }

~~Success Response Fields~~:

~~Field~~ ~~Description~~
data ~~Null or optional details~~

Error Response JSON Sample:

{ "success": false, "httpStatus": "BAD_REQUEST", "message": "NotificationSome IDsnotifications cannotnot befound empty"or access denied", "action_time": "2025-10-18T11:32:00Z"26T10:30:45", "data": "Notification IDs cannot be empty" }

~~Standard Error Types~~:

400 BAD_REQUEST~~: Empty or invalid notification IDs~~

401 UNAUTHORIZED~~: Invalid or expired token~~

403 FORBIDDEN~~: Access denied for some notifications~~

404 NOT_FOUND: Some notifications not found

or access denied" }

9.
10. ~~Delete~~Mark All Notifications as Read ~~Notifications~~

~~Purpose~~Purpose:: ~~Deletes~~Mark all ~~read~~unread notifications for the authenticated ~~user.~~user as read

~~Endpoint~~Endpoint:: ~~DELETE~~PUT {base_url}/notifications/readread-all

Access ~~Level~~Level:: 🔒 Protected (~~Authenticated~~Requires ~~user~~Bearer ~~only)~~Token Authentication)

~~Authentication~~Authentication:: Bearer Token

Request Headers:

Header Type Required Description

Authorization string Yes Bearer token for authentication (Bearer your_token)

Success Response JSON Sample:

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

11. Delete Notification

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

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

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-18T11:32:00Z"26T10:30:45", "data": 515 }

Success Response Fields:

Field Description

data Number of notifications that were deleted ~~notifications~~

14. Create In-App Notification

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-18T11:32:00Z"26T10:30:45", "data": "User ID cannot be null" }

~~Standard~~
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 ~~Types~~:
(422)

{ 400 BAD_REQUEST"success": Userfalse, ID issues 401 UNAUTHORIZED"httpStatus": Invalid"UNPROCESSABLE_ENTITY", or"message": expired"Validation token 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

~~HTTP Method Badge Code Templates~~

~~GET Badge:~~

GET

~~POST Badge:~~

POST

~~PATCH Badge:~~

PATCH

~~DELETE Badge:~~

DELETE

Common HTTP Status Codes

200 OK:OK: Successful GET/~~PUT/PATCH~~PUT request

201 Created:Created: Successful POST request

204 No Content:Content: Successful DELETE request

400 Bad Request:Request: Invalid request data

401 Unauthorized:Unauthorized: Authentication required/failed

403 Forbidden:Forbidden: Insufficient permissions

404 Not Found:Found: Resource not found

422 Unprocessable Entity:Entity: Validation errors

429 Too Many Requests:Requests: Rate limit exceeded

500 Internal Server Error:Error: Server error

Authentication Types

Bearer ~~Token~~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~~Dates:: Use ISO 8601 format (2025-10-~~18T11:32:00Z)~~26T14:30:00)

IDs: All IDs: use UUID format

~~Pagination~~Pagination:: ~~Include~~Uses ~~page,~~1-based ~~size,~~page ~~total_count,~~numbering
~~total_pages~~
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

Parameter	Type	Required	Description	Validation	Default
`page`	integer	No	Page number ~~for pagination~~(1-based)	~~Min:~~Must 1be positive integer	1
`size`	integer	No	Number of items per page	~~Min:~~Must 1,be ~~Max:~~between 1-100	20

Field	Description
`content`notifications	Array of ~~notifications~~notification objects
`content[notifications[].id`	Unique identifier offor the notification
`content[notifications[].userId`	ID of the user ~~receiving~~who received the notification
`content[notifications[].shopId`	ID of the associated shop (~~if applicable)~~nullable)
`content[notifications[].serviceId`	IDIdentifier offor the service ~~generating~~that generated the notification
`content[notifications[].serviceType`	Type of service (~~e.g.,~~ORDER, ~~ORDER)~~PAYMENT, SHIPPING, etc.)
`content[notifications[].title`	~~Title~~Notification ~~of the notification~~title
`content[notifications[].message`	~~Body~~Notification message ~~of the notification~~content
`content[notifications[].type`	~~Type~~Notification ~~of notification~~type (~~e.g.,~~INFO, ~~INFO)~~WARNING, ERROR, SUCCESS)
`content[notifications[].priority`	Priority level (~~e.g.,~~LOW, ~~NORMAL)~~MEDIUM, HIGH, URGENT)
`content[notifications[].isRead`	Whether the notification has been read
`content[notifications[].data`	Additional ~~data~~metadata as ~~key-value~~JSON ~~pairs~~object
`content[notifications[].createdAt`	Timestamp when notification was created
`content[notifications[].readAt`	Timestamp when notification was read (null if unread)
`pageable`currentPage	~~Pagination~~Current ~~details~~page number (1-based)
`pageSize`	Number of items per page
totalElements	Total number of notifications
totalPages	Total number of pages
`totalElements`	~~Total number of notifications~~
`last`hasNext	Whether ~~this~~there is ~~the~~a ~~last~~next page
`numberOfElements`hasPrevious	~~Number~~Whether ofthere ~~elements~~is ina ~~this~~previous page
`first`isFirst	Whether this is the first page
`size`	~~Page size~~
`number`	~~Current page number~~
`sort`	~~Sorting details~~
`empty`isLast	Whether ~~the page~~this is ~~empty~~the last page

~~Field~~	~~Description~~
`content`	~~Array~~count of unread notifications ~~(same structure as Get My Notifications)~~
`pageable`	~~Pagination details~~
`totalPages`	~~Total number of pages~~
`totalElements`	~~Total number of unread notifications~~
`last`	~~Whether this is the last page~~
`numberOfElements`	~~Number of elements in this page~~
`first`	~~Whether this is the first page~~
`size`	~~Page size~~
`number`	~~Current page number~~
`sort`	~~Sorting details~~
`empty`	~~Whether the page is empty~~

Field	Description
`totalCount`total	Total number of notifications
`unreadCount`unread	Number of unread notifications
`readCount`read	Number of read notifications

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

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be application/json

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be application/json

Header	Type	Required	Description
X-API-Key	string	Yes	API key for service authentication
Content-Type	string	Yes	Must be application/json

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

Notification Management

Short Description:

Hints:

Standard Response Format

Success Response Structure

Error Response Structure

Standard Response Fields

HTTP Method Badge Standards

Endpoints

1. Get My Notifications

Request Headers:

Query Parameters:

Success Response JSON Sample:

Success Response Fields:

Error Response JSON Sample:

2. Get Unread Notifications

Request Headers:

Query Parameters:

Success Response JSON Sample:

3. Get Unread Count

3. Get Notification Summary

Request Headers:

Success Response JSON Sample

Success Response Fields

4. Get Notification Summary

Request Headers

Success Response JSON Sample

Success Response Fields:

5. JSONGet Sample:Notifications {by "success": false, "httpStatus": "BAD_REQUEST", "message": "User ID cannot be null", "action_time": "2025-10-18T11:32:00Z", "data": "User ID cannot be null" } Shop

4. Mark Notification as Read

Request Headers:

Path Parameters:

Query Parameters

Success Response JSON Sample

6. Get Notifications by Service Type

Request Headers

Path Parameters

Query Parameters

Success Response JSON Sample

7. Get Notification by ID

Request Headers

Path Parameters

Success Response JSON Sample:

Error Response JSON Sample:

8. Types: 400 BAD_REQUEST: Invalid notification ID 401 UNAUTHORIZED: Invalid or expired token 403 FORBIDDEN: Access denied (not user's notification) 404 NOT_FOUND:Mark Notification not found

5. Batch Mark as Read

Request Headers:

Path Parameters:

6. Mark All as Read

7. Delete Notification

Success Response JSON Sample:

Error Response JSON Sample:

8.

9. BatchMark DeleteMultiple Notifications

Request Headers:

Request JSON Sample:

Request Body Parameters:

Success Response JSON Sample:

Error Response JSON Sample:

9.

10. DeleteMark All Notifications as Read Notifications

Request Headers:

Success Response JSON Sample:

11. Delete Notification

Request Headers

Path Parameters

Success Response JSON Sample

Error Response JSON Sample

12. Batch Delete Notifications

Request Headers

Request JSON Sample

Request Body Parameters

Success Response JSON Sample

Error Response JSON Sample

13. Delete All Read Notifications

Request Headers

Success Response JSON Sample

Success Response Fields:

14. Create In-App Notification

Request Headers

5. JSONGet Sample:
Notifications
`{by "success": false, "httpStatus": "BAD_REQUEST", "message": "User ID cannot be null", "action_time": "2025-10-18T11:32:00Z", "data": "User ID cannot be null" }`
Shop

8. Types:

`400 BAD_REQUEST`: Invalid notification ID

`401 UNAUTHORIZED`: Invalid or expired token

`403 FORBIDDEN`: Access denied (not user's notification)

`404 NOT_FOUND`:Mark Notification not found

Validation Error Types:
(422)