Smart Alerts

The smart_alerts feature lets end users define rules that trigger notifications when specific events occur. For example, an end user can be alerted when a high-value order is created or when a shipment is delayed.

Enable it by adding smart_alerts to your enabled_features.

Alert Rules

End users can create up to 20 alert rules. Each rule watches for a specific event type and optionally checks a condition.

Create a Rule

POST /api/embed/alerts/rules
Authorization: Bearer est_session-token
Content-Type: application/json
 
{
  "name": "High Value Orders",
  "description": "Alert when orders over $1,000 are created",
  "eventType": "order.created",
  "condition": {
    "field": "totals.amount",
    "operator": "gt",
    "value": 1000
  },
  "deliveryMethod": "in_app",
  "cooldownMinutes": 30
}

Rule Fields

List Rules

GET /api/embed/alerts/rules
Authorization: Bearer est_session-token

Update a Rule

PATCH /api/embed/alerts/rules/:id
Authorization: Bearer est_session-token
Content-Type: application/json
 
{
  "is_active": false
}

Delete a Rule

DELETE /api/embed/alerts/rules/:id
Authorization: Bearer est_session-token

Notifications

When a rule fires, it creates a notification. Notifications have a severity level and read/dismissed status.

List Notifications

GET /api/embed/alerts/notifications?unread=true
Authorization: Bearer est_session-token

Returns notifications with an unreadCount in the response. Supports filtering by unread=true.

Mark as Read

PATCH /api/embed/alerts/notifications/:id
Authorization: Bearer est_session-token
Content-Type: application/json
 
{
  "is_read": true
}

You can also set is_dismissed: true to dismiss the notification entirely.

Notification Severity

Cooldown

The cooldownMinutes field prevents alert fatigue. After a rule fires, it won’t fire again until the cooldown period has passed, even if the condition is met again.