Register push devices, read the customer's notifications inbox, and manage notification preferences from your storefront app.

Customer Notifications

Everything Storefront sends a customer — order updates, campaigns and promotional messages — is delivered by push to their devices and kept in a notifications inbox your app can display. This page covers the customer-facing API your app uses. All requests use the storefront key as the bearer token and the customer's Customer-Token header.

Registering devices

After the customer grants notification permission, register the device token they received from APNs (iOS) or FCM (Android):

POST /storefront/v1/customers/register-device
Authorization: Bearer store_your_store_key
Customer-Token: 1|VlKK7lZ...

{ "token": "<device token>", "platform": "ios" }

platform is ios or android. Send the raw APNs device token on iOS and the FCM registration token on Android.
Optionally send environment (production or sandbox) for iOS tokens. When it is omitted, Storefront tries production first and falls back to sandbox, so development builds work too.
Register again whenever the token changes or a different customer signs in. A token belongs to one app install, so it always moves to the customer who registered it last.
On sign out, remove the token so the device stops receiving that customer's notifications:

POST /storefront/v1/customers/unregister-device

{ "token": "<device token>" }

Tokens that Apple or Google report as no longer valid (for example after the app is uninstalled) are removed automatically.

The notifications inbox

Endpoint	Purpose
`GET /storefront/v1/notifications`	List notifications, newest first. Filters: `unread`, `type`; paging: `limit` (default 25, max 100), `offset`
`GET /storefront/v1/notifications/unread-count`	`{ "count": n }` for a badge
`GET /storefront/v1/notifications/{id}`	One notification
`PUT /storefront/v1/notifications/{id}/read`	Mark one as read
`PUT /storefront/v1/notifications/read-all`	Mark all as read
`DELETE /storefront/v1/notifications/{id}`	Delete one

Each item looks like this:

{
  "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", "store_id": "store_3Xb9kL2" },
  "is_read": false,
  "read_at": null,
  "created_at": "2026-09-26T09:30:00Z"
}

type tells you what the notification is about — order updates such as order_accepted, order_enroute or order_completed, campaign, or promotional — and data carries the identifiers to deep link with: order_id, store_id/network_id, and for campaigns campaign_id, promotion_id and action/action_id/action_url.

The inbox is scoped to the app making the request: a store's app sees that store's notifications, a network's app sees the network's and its member stores'.

Realtime updates

New inbox notifications are also broadcast over Fleetbase's SocketCluster connection on the channel contact.{customer uuid}, with the same type, title, body, image and data as an inbox item plus its id. Subscribe to it to update the inbox and badge without polling.

Notification preferences

Customers can choose what they receive:

GET /storefront/v1/notifications/preferences
PUT /storefront/v1/notifications/preferences

{ "order_updates": true, "promotions": false }

Preference	When off
`order_updates`	No push notifications about the customer's orders. They still appear in the inbox.
`promotions`	No campaigns or promotional messages at all — neither push nor inbox.

Both default to on. Only the keys you send are changed.

Customer Notifications

Customer Notifications

Registering devices

The notifications inbox

Realtime updates

Notification preferences

On this page