Notifications

Notification inbox for the authenticated user (clients and drivers). Covers order, offer, wallet, and account events. Entries older than the retention window are no longer listed. Paths are relative to the /api/v1 prefix; all routes require Authorization: Bearer {token}.

See Common errors.

Endpoints

Method	URI	Role	Description
`GET`	`/notifications`	any	List the caller's notifications (cursor paginated)
`GET`	`/notifications/unread-count`	any	Count of the caller's unread notifications
`POST`	`/notifications/{id}/read`	any	Mark a notification as read
`POST`	`/notifications/read-all`	any	Mark all of the caller's notifications as read
`DELETE`	`/notifications/{id}`	any	Delete a notification

GET /notifications

Lists the caller's notifications, newest first, using cursor pagination.

Query params

Field	Type	Required	Rules
`limit`	integer	no	1–100 (default 30)
`cursor`	string	no	Opaque cursor from a previous `next_cursor`
`filter`	string	no	one of `unread` (only unread notifications)

Response 200

{
  "items": [
    {
      "id": "9b7f0e2c-1d3a-4f5b-8c6d-2e1f0a9b8c7d",
      "type": "offer_received",
      "title": "Nueva oferta",
      "body": "Un repartidor te envió una oferta.",
      "priority": "normal",
      "data": { "order_id": 5, "offer_id": 12 },
      "read_at": null,
      "created_at": "2026-07-17T10:15:00+00:00"
    }
  ],
  "next_cursor": "eyJpZCI6...",
  "has_more": true
}

type is the notification kind (e.g. offer_received, order_delivered).
priority is one of normal, high, critical.
data is the notification's domain payload (keys vary by type).
read_at is null for unread notifications.

Errors

Status	Body	When
`422`	`{ "error": "ValidationError", "details": { "fieldErrors": { … } } }`	Invalid `limit`, `cursor` or `filter`

GET /notifications/unread-count

Response 200

{ "unread_count": 3 }

POST /notifications/{id}/read

Marks a single notification as read. Idempotent.

Path params

Field	Type	Required	Rules
`id`	string (uuid)	yes	Must belong to the caller

Response 200

{ "read_at": "2026-07-17T10:20:00+00:00" }

Errors

Status	Body	When
`404`	`{ "error": "NotFound", "message": "Notification not found." }`	The notification does not exist or belongs to another user

POST /notifications/read-all

Marks all of the caller's unread notifications as read.

Response 200 — { "ok": true }

DELETE /notifications/{id}

Deletes one of the caller's notifications.

Path params

Field	Type	Required	Rules
`id`	string (uuid)	yes	Must belong to the caller

Response 200 — { "ok": true }

Errors

Status	Body	When
`404`	`{ "error": "NotFound", "message": "Notification not found." }`	The notification does not exist or belongs to another user

Examples

# List unread notifications
curl /api/v1/notifications?filter=unread \
  -H "Authorization: Bearer {token}"

# Unread count
curl /api/v1/notifications/unread-count \
  -H "Authorization: Bearer {token}"

# Mark one as read
curl -X POST /api/v1/notifications/9b7f0e2c-1d3a-4f5b-8c6d-2e1f0a9b8c7d/read \
  -H "Authorization: Bearer {token}"

# Mark all as read
curl -X POST /api/v1/notifications/read-all \
  -H "Authorization: Bearer {token}"

# Delete one
curl -X DELETE /api/v1/notifications/9b7f0e2c-1d3a-4f5b-8c6d-2e1f0a9b8c7d \
  -H "Authorization: Bearer {token}"