Notifications

The authenticated customer's notification inbox. Order status updates, promotional messages and campaigns are stored here as well as sent by push, so the app can list them, show an unread badge and mark them as read. Every request needs the `Customer-Token` header. A customer only sees their own notifications, limited to the storefront app the request is made with: a store key sees that store's notifications, a network key sees the network's and its member stores'. Notifications that reference no storefront are shown in every app. New notifications are also broadcast in realtime on the SocketCluster channel `contact.{customer uuid}` with the same shape as an inbox item.

The Notification object

An inbox item. `type` identifies what the notification is about (for example `order_accepted`, `order_completed`, `promotional` or `campaign`), and `data` carries the identifiers the app needs to deep link. Recipient details are never included.

Attributes

idstringoptional

Notification id (uuid).

typestringoptional

What the notification is about, e.g. order_accepted, order_enroute, order_nearby, order_completed, order_canceled, order_ready, order_driver_assigned, promotional or campaign.

titlestringoptional

Notification title.

bodystringoptional

Notification message.

imagestringoptional

Optional image URL.

dataobjectoptional

Deep link data with null values removed, such as order_id, store_id, network_id, promotion_id, campaign_id and action/action_id/action_url.

is_readbooleanoptional

Whether the customer has read the notification.

read_attimestampoptional

When the notification was read.

created_attimestampoptional

When the notification was created.

The Notification object

{
  "id": "0f4c9a52-8d3f-4a6e-9f0e-2b1f7f2f8c11",
  "type": "order_completed",
  "title": "Your order from Acme Market has been delivered",
  "body": "Your order from Acme Market has been delivered, enjoy!",
  "image": null,
  "data": {
    "order_id": "order_9Kx2mQ1",
    "storefront_id": "store_3Xb9kL2",
    "store_id": "store_3Xb9kL2"
  },
  "is_read": false,
  "read_at": null,
  "created_at": "2026-09-26T09:30:00Z"
}

GET/v1/notifications

List Notifications

Lists the authenticated customer's notifications for the current storefront, newest first. Filter with unread and type, and page with limit (default 25, maximum 100) and offset.

Query parameters

unreadbooleanoptional

Only return notifications that have not been read.

typestringoptional

Only return notifications of this type, e.g. order_completed or promotional.

limitintegeroptional

Maximum number of notifications to return. Defaults to 25, maximum 100.

offsetintegeroptional

Number of notifications to skip.

GET/v1/notifications

curl https://api.fleetbase.io/v1/notifications?unread=false \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

GET/v1/notifications/unread-count

Count Unread Notifications

Returns { "count": n }, the number of unread notifications for the authenticated customer in the current storefront. Use it for badges.

GET/v1/notifications/unread-count

curl https://api.fleetbase.io/v1/notifications/unread-count \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

GET/v1/notifications

Retrieve a Notification

Retrieves one of the authenticated customer's notifications. Returns 404 for a notification that does not exist or belongs to another customer or storefront.

GET/v1/notifications

curl https://api.fleetbase.io/v1/notifications \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

PUT/v1/notifications/read

Mark a Notification as Read

Marks one notification as read and returns it. Marking an already read notification keeps its original read_at.

PUT/v1/notifications/read

curl -X PUT https://api.fleetbase.io/v1/notifications/read \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

PUT/v1/notifications/read-all

Mark All Notifications as Read

Marks every unread notification of the authenticated customer in the current storefront as read. Returns { "status": "OK", "updated": n }.

PUT/v1/notifications/read-all

curl -X PUT https://api.fleetbase.io/v1/notifications/read-all \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

DELETE/v1/notifications

Delete a Notification

Deletes one of the authenticated customer's notifications. Returns { "status": "OK", "id": "...", "deleted": true }.

DELETE/v1/notifications

curl -X DELETE https://api.fleetbase.io/v1/notifications \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

GET/v1/notifications/preferences

Get Notification Preferences

Returns the authenticated customer's notification preferences, { "order_updates": true, "promotions": true } by default. order_updates controls push notifications about the customer's orders (the inbox copy is always kept); promotions controls promotional notifications and campaigns entirely.

GET/v1/notifications/preferences

curl https://api.fleetbase.io/v1/notifications/preferences \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

PUT/v1/notifications/preferences

Update Notification Preferences

Updates the authenticated customer's notification preferences. Only the keys sent are changed; unknown keys are ignored. Returns the full preferences, or 400 when a value is not a boolean.

Body parameters

order_updatesbooleanoptional

Receive push notifications about order status changes.

promotionsbooleanoptional

Receive promotional notifications and campaigns (push and inbox).

PUT/v1/notifications/preferences

curl -X PUT https://api.fleetbase.io/v1/notifications/preferences \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "order_updates": true,
  "promotions": true
}'