Alerts

Manage custom alerts, alert rules, and notification preferences for your e-commerce business.

Alert Types

Type	Description
`margin_threshold`	Alert when profit margin falls below threshold
`roas_threshold`	Alert when ROAS falls below threshold
`daily_spend_limit`	Alert when daily ad spend exceeds limit
`revenue_drop`	Alert when revenue drops significantly
`order_spike`	Alert when orders spike unexpectedly

Severity Levels

critical - Urgent issues requiring immediate attention
warning - Important but not critical
info - Informational notifications

Notification Channels

app - In-app notifications
email - Email notifications

GET /v1/alerts

List user alerts with pagination and filtering.

Parameters

Parameter	Type	Required	Description
`page`	number	No	Page number (min: 1, default: 1)
`limit`	number	No	Items per page (1-100, default: 20)
`type`	string	No	Filter by alert type
`severity`	string	No	`all`, `critical`, `warning`, `info` (default: `all`)
`unread`	string	No	`true` or `false` to filter unread alerts

Example Request

bash

curl -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/alerts?page=1&limit=20&severity=critical"

Response

json

{
  "success": true,
  "data": {
    "alerts": [
      {
        "id": "alert_123",
        "user_id": "user_456",
        "type": "margin_threshold",
        "severity": "critical",
        "title": "Profit margin dropped below 20%",
        "message": "Your profit margin for Product XYZ is now 18%, which is below your threshold of 20%.",
        "data": {
          "productId": "prod_789",
          "currentMargin": 18.0,
          "threshold": 20.0
        },
        "read_at": null,
        "created_at": "2024-01-25T10:30:00Z"
      }
    ],
    "unreadCount": 5,
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3
    }
  }
}

GET /v1/alerts/:id

Get a single alert by ID.

Example Request

bash

curl -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/alerts/alert_123"

Response

json

{
  "success": true,
  "data": {
    "alert": {
      "id": "alert_123",
      "user_id": "user_456",
      "type": "margin_threshold",
      "severity": "critical",
      "title": "Profit margin dropped below 20%",
      "message": "Your profit margin for Product XYZ is now 18%...",
      "data": {
        "productId": "prod_789",
        "currentMargin": 18.0,
        "threshold": 20.0
      },
      "read_at": null,
      "created_at": "2024-01-25T10:30:00Z"
    }
  }
}

POST /v1/alerts/:id/read

Mark an alert as read.

Example Request

bash

curl -X POST \
  -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/alerts/alert_123/read"

Response

json

{
  "success": true,
  "data": {
    "message": "تم تحديد التنبيه كمقروء"
  }
}

Alias: PATCH /v1/alerts/:id/read works the same way.

POST /v1/alerts/read-all

Mark all user alerts as read.

Example Request

bash

curl -X POST \
  -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/alerts/read-all"

Response

json

{
  "success": true,
  "data": {
    "message": "تم تحديد جميع التنبيهات كمقروءة",
    "count": 5
  }
}

DELETE /v1/alerts/:id

Delete an alert.

Example Request

bash

curl -X DELETE \
  -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/alerts/alert_123"

Response

json

{
  "success": true,
  "data": {
    "message": "تم حذف التنبيه"
  }
}

GET /v1/alerts/rules

List all alert rules for the user.

Example Request

bash

curl -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/alerts/rules"

Response

json

{
  "success": true,
  "data": {
    "rules": [
      {
        "id": "rule_123",
        "user_id": "user_456",
        "name": "Low Profit Margin Alert",
        "type": "margin_threshold",
        "conditions": {
          "threshold": 20.0,
          "comparison": "lt",
          "productId": "prod_789"
        },
        "channels": ["app", "email"],
        "enabled": 1,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Alias: GET /v1/alerts/rules/list works the same way.

POST /v1/alerts/rules

Create a new alert rule.

Request Body

json

{
  "name": "Low ROAS Alert",
  "type": "roas_threshold",
  "conditions": {
    "threshold": 3.0,
    "comparison": "lt",
    "campaignId": "camp_123"
  },
  "channels": ["app", "email"],
  "enabled": true
}

Field Descriptions

Field	Type	Required	Description
`name`	string	Yes	Rule name (1-100 characters)
`type`	string	Yes	One of: `margin_threshold`, `roas_threshold`, `daily_spend_limit`, `revenue_drop`, `order_spike`
`conditions`	object	Yes	Rule conditions (varies by type)
`channels`	array	Yes	Notification channels (min 1)
`enabled`	boolean	No	Enable/disable rule (default: true)

Comparison Operators

lt - Less than
gt - Greater than
eq - Equal to
lte - Less than or equal to
gte - Greater than or equal to

Example Request

bash

curl -X POST \
  -H "Authorization: Bearer looha_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Low ROAS Alert",
    "type": "roas_threshold",
    "conditions": {
      "threshold": 3.0,
      "comparison": "lt"
    },
    "channels": ["app", "email"],
    "enabled": true
  }' \
  "https://api.looha.app/v1/alerts/rules"

Response

json

{
  "success": true,
  "data": {
    "ruleId": "rule_456",
    "message": "تم إنشاء قاعدة التنبيه"
  }
}

PUT /v1/alerts/rules/:id

Update an existing alert rule.

Request Body

All fields are optional. Only include fields you want to update.

json

{
  "name": "Updated Rule Name",
  "enabled": false
}

Example Request

bash

curl -X PUT \
  -H "Authorization: Bearer looha_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}' \
  "https://api.looha.app/v1/alerts/rules/rule_123"

Response

json

{
  "success": true,
  "data": {
    "message": "تم تحديث قاعدة التنبيه"
  }
}

DELETE /v1/alerts/rules/:id

Delete an alert rule.

Example Request

bash

curl -X DELETE \
  -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/alerts/rules/rule_123"

Response

json

{
  "success": true,
  "data": {
    "message": "تم حذف قاعدة التنبيه"
  }
}

GET /v1/alerts/preferences

Get alert notification preferences.

Example Request

bash

curl -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/alerts/preferences"

Response

json

{
  "success": true,
  "data": {
    "preferences": {
      "emailEnabled": true,
      "emailCritical": true,
      "emailWarning": true,
      "emailInfo": false,
      "pushEnabled": true,
      "pushCritical": true,
      "pushWarning": true,
      "pushInfo": true,
      "digestEnabled": false,
      "digestFrequency": "daily",
      "quietHoursEnabled": true,
      "quietHoursStart": "22:00",
      "quietHoursEnd": "08:00",
      "quietHoursTimezone": "Asia/Riyadh",
      "audioEnabled": true,
      "audioVolume": 70,
      "audioMutedDuringQuietHours": true,
      "soundForAlert": "notification-1",
      "soundForWarning": "notification-2",
      "soundForInfo": "notification-3",
      "soundForSuccess": "success-1"
    }
  }
}

PUT /v1/alerts/preferences

Update alert notification preferences.

Request Body

json

{
  "emailEnabled": true,
  "emailCritical": true,
  "emailWarning": true,
  "emailInfo": false,
  "pushEnabled": true,
  "pushCritical": true,
  "pushWarning": true,
  "pushInfo": true,
  "digestEnabled": true,
  "digestFrequency": "weekly",
  "quietHoursEnabled": true,
  "quietHoursStart": "22:00",
  "quietHoursEnd": "08:00",
  "quietHoursTimezone": "Asia/Riyadh",
  "audioEnabled": true,
  "audioVolume": 70,
  "audioMutedDuringQuietHours": true
}

Field Descriptions

Field	Type	Description
`emailEnabled`	boolean	Enable email notifications
`emailCritical`	boolean	Email for critical alerts
`emailWarning`	boolean	Email for warning alerts
`emailInfo`	boolean	Email for info alerts
`pushEnabled`	boolean	Enable push notifications
`pushCritical`	boolean	Push for critical alerts
`pushWarning`	boolean	Push for warning alerts
`pushInfo`	boolean	Push for info alerts
`digestEnabled`	boolean	Enable digest emails
`digestFrequency`	string	`daily` or `weekly`
`quietHoursEnabled`	boolean	Enable quiet hours
`quietHoursStart`	string	Start time (HH:MM format)
`quietHoursEnd`	string	End time (HH:MM format)
`quietHoursTimezone`	string	Timezone (e.g., Asia/Riyadh)
`audioEnabled`	boolean	Enable sound notifications
`audioVolume`	number	Volume (0-100)
`audioMutedDuringQuietHours`	boolean	Mute during quiet hours

Example Request

bash

curl -X PUT \
  -H "Authorization: Bearer looha_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "emailEnabled": true,
    "quietHoursEnabled": true,
    "quietHoursStart": "22:00",
    "quietHoursEnd": "08:00"
  }' \
  "https://api.looha.app/v1/alerts/preferences"

Response

json

{
  "success": true,
  "data": {
    "message": "تم تحديث إعدادات التنبيهات"
  }
}

POST /v1/alerts/test

Send a test alert (development/testing).

Example Request

bash

curl -X POST \
  -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/alerts/test"

Response

json

{
  "success": true,
  "data": {
    "alertId": "alert_test_123",
    "message": "تم إرسال التنبيه التجريبي"
  }
}

Use Cases

Create Low Margin Alert

javascript

const API_KEY = 'looha_your_api_key'

const response = await fetch('https://api.looha.app/v1/alerts/rules', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Low Profit Margin - Product ABC',
    type: 'margin_threshold',
    conditions: {
      threshold: 25.0,
      comparison: 'lt',
      productId: 'prod_abc_123',
    },
    channels: ['app', 'email'],
    enabled: true,
  }),
})

const result = await response.json()
console.log(`Alert rule created: ${result.data.ruleId}`)

Check Unread Alerts

python

import requests

API_KEY = 'looha_your_api_key'

response = requests.get(
    'https://api.looha.app/v1/alerts',
    params={'unread': 'true', 'severity': 'critical'},
    headers={'Authorization': f'Bearer {API_KEY}'}
)

data = response.json()
unread = data['data']['alerts']

print(f"You have {len(unread)} unread critical alerts")
for alert in unread:
    print(f"- {alert['title']}")

Batch Mark as Read

javascript

// Get all unread alerts
const response = await fetch('https://api.looha.app/v1/alerts?unread=true', {
  headers: { Authorization: `Bearer ${API_KEY}` },
})

const data = await response.json()
console.log(`Found ${data.data.alerts.length} unread alerts`)

// Mark all as read
const markReadResponse = await fetch('https://api.looha.app/v1/alerts/read-all', {
  method: 'POST',
  headers: { Authorization: `Bearer ${API_KEY}` },
})

const result = await markReadResponse.json()
console.log(result.data.message)

Next: Recommendations API →

Alerts ​

Alert Types ​

Severity Levels ​

Notification Channels ​

GET /v1/alerts ​

Parameters ​

Example Request ​

Response ​

GET /v1/alerts/:id ​

Example Request ​

Response ​

POST /v1/alerts/:id/read ​

Example Request ​

Response ​

POST /v1/alerts/read-all ​

Example Request ​

Response ​

DELETE /v1/alerts/:id ​

Example Request ​

Response ​

GET /v1/alerts/rules ​

Example Request ​

Response ​

POST /v1/alerts/rules ​

Request Body ​

Field Descriptions ​

Comparison Operators ​

Example Request ​

Response ​

PUT /v1/alerts/rules/:id ​

Request Body ​

Example Request ​

Response ​

DELETE /v1/alerts/rules/:id ​

Example Request ​

Response ​

GET /v1/alerts/preferences ​

Example Request ​

Response ​

PUT /v1/alerts/preferences ​

Request Body ​

Field Descriptions ​

Example Request ​

Response ​

POST /v1/alerts/test ​

Example Request ​

Response ​

Use Cases ​

Create Low Margin Alert ​

Check Unread Alerts ​

Batch Mark as Read ​

Alerts

Alert Types

Severity Levels

Notification Channels

GET /v1/alerts

Parameters

Example Request

Response

GET /v1/alerts/:id

Example Request

Response

POST /v1/alerts/:id/read

Example Request

Response

POST /v1/alerts/read-all

Example Request

Response

DELETE /v1/alerts/:id

Example Request

Response

GET /v1/alerts/rules

Example Request

Response

POST /v1/alerts/rules

Request Body

Field Descriptions

Comparison Operators

Example Request

Response

PUT /v1/alerts/rules/:id

Request Body

Example Request

Response

DELETE /v1/alerts/rules/:id

Example Request

Response

GET /v1/alerts/preferences

Example Request

Response

PUT /v1/alerts/preferences

Request Body

Field Descriptions

Example Request

Response

POST /v1/alerts/test

Example Request

Response

Use Cases

Create Low Margin Alert

Check Unread Alerts

Batch Mark as Read