API Reference
Notifications API
Retrieve, filter and manage user notifications.
List Notifications
GET /v1/notificationsReturns the signed-in user's notifications, newest first. Without any filters this is the 50 most recent.
Auth: Required
Query parameters
All parameters are optional. Omitting one means "do not narrow by it".
| Parameter | Type | Description |
|---|---|---|
eventType | string | Narrow to a single event, e.g. invoice.paid. Repeat the parameter to match several: ?eventType=invoice.paid&eventType=order.refunded. |
type | string | Narrow to one severity: INFO, WARNING, ERROR or SUCCESS. |
read | boolean | true for read notifications only, false for unread only. |
from | string | Only notifications created on or after this ISO date or datetime. |
to | string | Only notifications created on or before it. A bare date covers that whole day. |
limit | integer | How many to return, 1–200. Defaults to 50. |
An eventType outside the catalogue, a limit above the cap, or a malformed
date is rejected with 422 and a VALIDATION_ERROR — values are never silently
ignored or clamped.
Response
Each notification carries an eventType naming what produced it, such as
invoice.paid. It is null on notifications created before the field existed.
{
"success": true,
"data": {
"notifications": [
{
"id": "clx1...",
"title": "Payment received",
"body": "Your payment of USD 49.99 for Acme was received.",
"type": "SUCCESS",
"eventType": "invoice.paid",
"read": false,
"link": "/controlpanel/billing",
"createdAt": "2026-08-20T09:15:00.000Z"
}
]
}
}Mark All as Read
PATCH /v1/notifications/read-allMarks every unread notification as read. This is not affected by the filters above — it always applies to the full list.
Auth: Required
Mark One as Read
PATCH /v1/notifications/:id/readMarks a single notification as read.
Auth: Required