Notifications

Notifications

How the system tells you something has happened — mostly about billing, balance and your subscriptions.

Last updated 2026-10-13

DigitalKey ERP — Docs · digital-key.co/docs/notifications

Overview

Notifications are generated by the system, not written by users. Almost all of them concern money: a deduction succeeded or failed, your balance was topped up, a feature was added or removed, your account changed state.

Notifications — Notification bell and dropdown
Notification bell and dropdown
Notification bell and dropdown — The bell with its unread badge, open to show recent notifications.

Notification types

Values of the type field
ParameterTypeRequiredDescription
billing_deduction_successbillingOptionalYour monthly subscription was deducted. Includes the amount and remaining balance.
billing_deduction_failedbillingOptionalA deduction failed because the balance was too low. Includes what was needed.
billing_suspendedbillingOptionalYour account moved into a suspended state.
billing_reactivatedbillingOptionalA top-up covered the monthly cost and the account was reactivated.
admin_topupadminOptionalAn administrator or reseller added balance to your account.
admin_feature_subscribedadminOptionalA feature was added to your subscription, with its monthly price.
admin_feature_removedadminOptionalA feature was removed from your subscription.
Importantbilling_deduction_failed is the one to act on immediately. It means a grace period has started, and ignoring it leads to suspension. See Lifecycle States.

The notification record

ParameterTypeRequiredDescription
notification_idintegerOptionalIdentifier.
typestringOptionalOne of the types above.
titlestringOptionalShort headline.
messagestringOptionalFull text, including amounts.
created_by_rolestringOptionalWho caused it — system, admin or reseller.
ref_typestringOptionalWhat it relates to, when it points at a record.
ref_idintegerOptionalIdentifier of that record.
is_readbooleanOptionalWhether you have read it.
read_attimestampOptionalWhen you read it.
created_attimestampOptionalWhen it was raised.
time_agostringOptionalHuman-readable age, such as '2 hours ago'. Computed.

The bell

The bell in the top bar carries a badge with the number of unread notifications and opens a list of the most recent. The full history is on the Notifications page.

Endpoints
ParameterTypeRequiredDescription
GET /notifications/summaryendpointOptionalUnread count plus the recent list, for the bell.
GET /notifications/countendpointOptionalJust the unread count.
GET /notificationsendpointOptionalFull paginated history.
POST /notifications/{id}/readendpointOptionalMark one as read.
POST /notifications/read-allendpointOptionalMark everything as read.
NoteMarking as read only affects your own view. It does not dismiss the underlying situation — reading a failed-deduction notice does not restore your balance.

Broadcasts

Platform administrators can send a message to a whole tenant, or to everyone in a particular role, for maintenance windows and announcements.

POST /api/v1/admin/notifications (admin only)
ParameterTypeRequiredDescription
tenant_idintegerRequiredWhich business to send to.
rolestringRequiredWhich role within that business receives it.
titlestringRequiredHeadline.
messagestringRequiredBody text.
WarningA broadcast is delivered once, to the people matching at that moment. Users created afterwards do not receive it, so announcing something in advance will not reach anyone who joins later.

Related