A store tells its customers when something new lands: a trade in a portfolio they follow, a lesson, an episode or a post, a file, a new product or a discount. It also reminds them of an event they’re going to and thanks them once it’s over: reminders never go by email. Each one lands in the customer’s notifications, and as a browser notification on every browser they allowed. Everything here needs a token (Authentication); the examples use the client from Your own front end.
On your Sherpo storefront this is already built in: a signed-in customer sees their unread notifications in the header’s bell, opens one to go straight to what’s new, deletes one or every read one, chooses what they hear about under Account > Notifications, and turns browser notifications on or off there. Right after a purchase, and on a product they hold that had something new for them in the last two weeks, a small card offers browser notifications for that kind of content; the browser asks for permission only once they press Turn on, and No thanks keeps the card away on every device. It never shows to a customer whose browser notifications are already on, nor where the browser can’t take them. On an iPhone or iPad, browser notifications reach the store once it’s added to the Home Screen and opened from there, which the page and the card say instead of offering a button. The rest of this page is for your own front end.
What notifies
| Type | When | Who |
|---|---|---|
portfolio_trade |
A buy or a sell recorded with notify (the merchant app’s switch, on unless the seller turns it off) |
Customers with access to the portfolio |
new_lesson |
A lesson of a course goes live, published or as its schedule arrives | Customers holding the course who can open it |
new_episode |
An episode of a series or a podcast goes live | Customers holding the series or podcast who can open it |
new_post |
A post of a blog goes live | Customers holding the blog who can open it |
new_file |
A file is added to a files or software product, announced on a portfolio’s holding, or a software release is published with notify |
Customers who can download it (every holder for a release that ships no file) |
new_product |
A product in the main catalog goes live | Every customer of the store |
new_discount |
An automatic discount starts lowering a product’s price | Every customer of the store |
event_reminder |
A session of an event starts in a day, then in an hour; a session moved later reminds again for its new time | Customers going to the event |
event_follow_up |
An hour after an event’s last session ends, to thank those who came | Customers going to the event |
An event’s reminders reach a browser only until the session starts, and one moved after its reminder went reminds again for its new time. Each other thing notifies once: taking it down and putting it up again sends nothing new, and one dated well in the past, such as a post moved over from an archive, sends nothing. The text is in the customer’s own locale, or the store’s when they have none.
The list
GET /v1/stores/{store}/notifications pages the customer’s notifications, newest first. Filter it by read for an unread badge, asking for the total alone:
curl --globoff 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/notifications?filter[read][eq]=false&limit=1&count=true' \
--header 'Authorization: Bearer ctk_...'{
"items": [
{
"id": "<notification id>",
"type": "portfolio_trade",
"title": "Your Store",
"body": "Growth Portfolio opened a position in AAPL at $189.50, now 4.2% of the portfolio",
"path": "/p/growth-portfolio",
"product_id": "<product id>",
"created_at": "2026-11-05T14:30:00.000Z",
"read_at": null
}
],
"cursor": null,
"total": 3
}titleis your store’s name andbodysays what happened in one sentence, already in the customer’s language, with the details at hand: a trade’s price per share and the position’s new weight, a video’s length, a file’s size, a product’s price or a discount’s end.pathis where it opens, on your store’s own host.- A notification about a product taken down leaves the list with it, and every notification goes after 90 days.
POST /v1/stores/{store}/notifications/read marks the ids it names read, up to 100, or every unread one when it names none. It answers how many it marked, and needs profile:write.
POST /v1/stores/{store}/notifications/delete deletes the ids it names, read or not, up to 100, or every read one when it names none. It answers how many it deleted, and needs profile:write. A deleted notification is gone for good: what it was about never notifies again, though a browser notification already on its way still arrives. Every read one includes those the list no longer shows, as about a product taken down, so deleted may count more than the customer saw. An id that isn’t the customer’s deletes nothing.
curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/notifications/delete' \
--header 'Authorization: Bearer ctk_...' \
--header 'Content-Type: application/json' \
--data '{}'What they hear about
GET /v1/stores/{store}/notification_settings answers every type with whether it’s enabled; each is on until the customer turns it off. PATCH /v1/stores/{store}/notification_settings turns types on or off, for the list and browser notifications alike, and needs profile:write:
curl --request PATCH 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/notification_settings' \
--header 'Authorization: Bearer ctk_...' \
--header 'Content-Type: application/json' \
--data '{ "types": { "new_discount": false } }'A type left out keeps its setting.
Browser notifications
Browser notifications use Web Push. Your page asks the browser to subscribe with the store’s key, then hands the subscription over:
- Read the key from
GET /v1/stores/{store}/push_key. Itspublic_keyisnullwhen the store sends no browser notifications; offer none then. - Register a service worker and subscribe with
pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: publicKey }). - Send the subscription’s
endpointandkeystoPOST /v1/stores/{store}/push_subscriptions, withprofile:write. A push carries what the list shows, so the token needsreadtoo, and pushes stop if it loses it.
curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/push_subscriptions' \
--header 'Authorization: Bearer ctk_...' \
--header 'Content-Type: application/json' \
--data '{ "endpoint": "https://fcm.googleapis.com/fcm/send/...", "keys": { "p256dh": "<key>", "auth": "<secret>" } }'Each push carries the notification as JSON: its id, customer_id, type, title, body, path and created_at. Show it with the id as its tag, so a push that arrives twice shows once, and open path on a click. customer_id is the customer the notification belongs to, the id GET /v1/stores/{store}/profile answers. A push can arrive late, after someone else signed in on the same browser: compare it with the signed-in customer’s id and keep what a click opened under that customer_id, so it’s marked read once that customer is back.
A browser is pushed to while the token that added it lasts: once it’s revoked or lapses, nothing more goes, so a shared computer stops receiving the customer’s new notifications after they sign out. A push sent before then can still arrive for up to a day, which is what customer_id tells apart. A customer may allow 10 browsers; an 11th replaces the oldest. A browser added again moves to whoever added it last. The customer handing the same subscription over again, as on every visit, is safe: a notification that reached it isn’t pushed to it again, and it counts as the newest for the cap. POST /v1/stores/{store}/push_subscriptions/delete stops pushing to one by its endpoint, as when the customer turns browser notifications off.
A browser may renew its subscription on its own, firing pushsubscriptionchange in your service worker with a new endpoint. Hand it over to POST /v1/stores/{store}/push_subscriptions/renew with the old endpoint beside the new endpoint and keys. It moves the customer’s subscription in one step, keeping its place among their 10 browsers, so a failed call leaves the old one in place to try again, and a retry naming no revision after one that went through answers the same subscription. When the customer already holds the new endpoint with the same keys, as after an earlier renewal from another old endpoint of the same browser, the two become one: it keeps what was pushed to either, so nothing reaches the browser twice, and takes the older one’s place among the 10. Renew each old endpoint you still know of this way, so none stays behind taking one of the 10 places. An old endpoint the customer doesn’t hold answers not_found, as when its service had already dropped it: hand the new subscription to POST /v1/stores/{store}/push_subscriptions instead.
curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/push_subscriptions/renew' \
--header 'Authorization: Bearer ctk_...' \
--header 'Content-Type: application/json' \
--data '{ "old": "https://fcm.googleapis.com/fcm/send/...", "endpoint": "https://fcm.googleapis.com/fcm/send/...", "keys": { "p256dh": "<key>", "auth": "<secret>" } }'Refusing an out-of-date write
Several tabs, and your service worker, may change the same browser’s subscription, and a call you gave up on can still land later. If another customer took the browser over in between, that late call would move it back. To refuse it, every create, renewal and delete answers a revision, and a create, renewal or delete may name the revision it expects:
- Keep the
revisionof the last answer, in storage your pages and your service worker share, for whoever holds the browser. Store it only from an answer, and keep the old one when a call fails or you give up on it: that old value is what refuses the late call. - Name it as
revisionon the next write, after a delete too: an endpoint a subscription left keeps a revision of its own for a day, so a create you gave up on before the customer turned notifications off is refused. Namenullonly for an endpoint you expect never held one, as a browser’s new subscription. Leaverevisionout when you don’t know it, as after storage was cleared; the write is then unchecked. - A write naming a revision that another write replaced answers
conflictwithfield: "revision"and the endpoint’scurrentrevision (nullwhen it held no subscription in the last day). A renewal checks the newest write of the browser: the subscription at the newendpointif one was written there since, or the revision a delete left there, else the customer’s atold. A delete only checks a subscription the customer holds; one another customer holds stays theirs at a new revision, which the delete answers. - A renewal retried after a try that went through answers
conflictwith the subscription’s currentrevision; its retry namingcurrentlands, and to a new endpoint it then changes nothing. - Retry with
currentonly while the change is still the newest one in this browser: in the page or service worker that holds your lock across tabs, before giving up. Never retry on your server, or anywhere that outlives that lock, since that is the late call this refuses.
A stored revision also goes out of date when core drops the subscription itself: the customer’s 11th browser replaced it, its push service no longer knows it, the session or token that added it ended over 30 days ago, or the app whose token added it was forgotten. A create then answers conflict with the endpoint’s current revision, and its retry naming it lands; a renewal answers not_found, as for any old endpoint the customer doesn’t hold, and a delete answers deleted: false with the revision to name next. A renewal’s not_found may also mean a later renewal already moved the browser on, so read the browser’s current subscription from pushManager.getSubscription() before handing a new one over with a create. Until then, a session or token that ends stops the pushes but keeps the subscription and its revision, so the next write naming it lands.