AI Recommendations

Get smart, actionable recommendations powered by Claude AI to optimize your business performance and increase profitability.

Pro Plan Required

AI recommendations feature requires an active Pro plan subscription with AI features enabled.

Recommendation Types

Type	Description
`action`	Actionable recommendations you can implement
`insight`	Data insights and patterns
`warning`	Issues that need attention

Priority Levels

high - High-impact recommendations
medium - Medium-impact recommendations
low - Nice-to-have improvements

GET /v1/recommendations

Get AI-generated recommendations with filtering.

Parameters

Parameter	Type	Required	Description
`category`	string	No	Filter: `all`, `pricing`, `ads`, `inventory`, `costs` (default: `all`)
`priority`	string	No	Filter: `all`, `high`, `medium`, `low` (default: `all`)
`status`	string	No	Filter: `active`, `dismissed`, `completed`, `expired`, `all` (default: `active`)
`page`	number	No	Page number (min: 1, default: 1)
`limit`	number	No	Items per page (1-50, default: 10)

Example Request

bash

curl -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/recommendations?category=pricing&priority=high&page=1&limit=10"

Response

json

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "id": "rec_123",
        "user_id": "user_456",
        "type": "action",
        "category": "pricing",
        "priority": "high",
        "title": "Increase price for high-margin products",
        "description": "Products with 40%+ margin show strong demand elasticity. Consider increasing prices by 5-10% to maximize profit.",
        "impact_type": "profit",
        "impact_estimated": 2500,
        "impact_confidence": 85,
        "created_at": "2024-01-25T10:00:00Z",
        "expires_at": "2024-02-25T10:00:00Z",
        "dismissed_at": null,
        "completed_at": null
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 15,
      "totalPages": 2
    }
  }
}

Response Fields

Field	Type	Description
`impact_type`	string	Impact area: `profit`, `revenue`, `cost`
`impact_estimated`	number	Estimated impact in SAR
`impact_confidence`	number	Confidence level (0-100)
`expires_at`	string	Recommendation expiry date
`dismissed_at`	string	When recommendation was dismissed (null if active)
`completed_at`	string	When recommendation was completed (null if not completed)

POST /v1/recommendations/generate

Generate new AI recommendations based on current data.

AI Quota Usage

This endpoint consumes 1 AI request from your monthly quota:

Starter Plan: 4 AI requests/month
Growth Plan: 12 AI requests/month

Example Request

bash

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

Response

json

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "type": "action",
        "category": "costs",
        "priority": "high",
        "title": "Reduce shipping costs on low-margin items",
        "description": "Products with <15% margin should use economy shipping to preserve profitability.",
        "impact": {
          "type": "cost",
          "estimated": 1800,
          "confidence": 75
        }
      }
    ]
  }
}

Error Responses

403 Forbidden - No Subscription:

json

{
  "success": false,
  "error": "NO_SUBSCRIPTION"
}

403 Forbidden - Feature Not Available:

json

{
  "success": false,
  "error": "FEATURE_NOT_AVAILABLE"
}

429 Too Many Requests - Quota Exceeded:

json

{
  "success": false,
  "error": "AI quota exceeded for this month"
}

GET /v1/recommendations/:id

Get a single recommendation by ID.

Example Request

bash

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

Response

json

{
  "success": true,
  "data": {
    "recommendation": {
      "id": "rec_123",
      "user_id": "user_456",
      "type": "action",
      "category": "pricing",
      "priority": "high",
      "title": "Increase price for high-margin products",
      "description": "Products with 40%+ margin show strong demand elasticity...",
      "impact_type": "profit",
      "impact_estimated": 2500,
      "impact_confidence": 85,
      "created_at": "2024-01-25T10:00:00Z",
      "expires_at": "2024-02-25T10:00:00Z"
    }
  }
}

POST /v1/recommendations/:id/dismiss

Dismiss a recommendation (you're not interested).

Example Request

bash

curl -X POST \
  -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/recommendations/rec_123/dismiss"

Response

json

{
  "success": true,
  "data": {
    "message": "تم تجاهل التوصية"
  }
}

POST /v1/recommendations/:id/complete

Mark a recommendation as completed (you implemented it).

Example Request

bash

curl -X POST \
  -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/recommendations/rec_123/complete"

Response

json

{
  "success": true,
  "data": {
    "message": "تم إكمال التوصية"
  }
}

GET /v1/recommendations/analytics/summary

Get recommendations analytics for user.

Example Request

bash

curl -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/recommendations/analytics/summary"

Response

json

{
  "success": true,
  "data": {
    "total": 45,
    "active": 12,
    "completed": 28,
    "dismissed": 5,
    "completionRate": "62.2%",
    "byCategory": [
      {
        "category": "pricing",
        "count": 15
      },
      {
        "category": "costs",
        "count": 12
      }
    ],
    "byStatus": [
      {
        "status": "completed",
        "count": 28
      },
      {
        "status": "active",
        "count": 12
      }
    ],
    "avgImpact": 1850,
    "totalCompletedImpact": 51800
  }
}

GET /v1/recommendations/analytics/usage

Get AI quota and usage statistics.

Example Request

bash

curl -H "Authorization: Bearer looha_your_api_key" \
  "https://api.looha.app/v1/recommendations/analytics/usage"

Response

json

{
  "success": true,
  "data": {
    "quotas": [
      {
        "feature": "ai_recommendations",
        "plan_type": "growth",
        "quota_limit": 12,
        "used_count": 8,
        "usage_percent": 66.67,
        "reset_at": "2024-02-01T00:00:00Z",
        "last_used_at": "2024-01-25T14:30:00Z"
      }
    ],
    "dailyUsage": [
      {
        "date": "2024-01-25",
        "feature": "ai_recommendations",
        "count": 2,
        "successful": 2,
        "failed": 0,
        "avg_latency": 1250,
        "total_cost": 0.08
      }
    ],
    "providers": [
      {
        "provider": "anthropic",
        "count": 8,
        "avg_latency": 1200,
        "successful_calls": 8
      }
    ]
  }
}

Use Cases

Generate Monthly Recommendations

javascript

const API_KEY = 'looha_your_api_key'

// Check quota first
const quotaResponse = await fetch('https://api.looha.app/v1/recommendations/analytics/usage', {
  headers: { Authorization: `Bearer ${API_KEY}` },
})

const quota = await quotaResponse.json()
const aiQuota = quota.data.quotas.find(q => q.feature === 'ai_recommendations')

if (aiQuota.used_count < aiQuota.quota_limit) {
  // Generate new recommendations
  const genResponse = await fetch('https://api.looha.app/v1/recommendations/generate', {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}` },
  })

  const recommendations = await genResponse.json()
  console.log(`Generated ${recommendations.data.recommendations.length} recommendations`)
} else {
  console.log('AI quota exhausted for this month')
}

Track High-Impact Recommendations

python

import requests

API_KEY = 'looha_your_api_key'

response = requests.get(
    'https://api.looha.app/v1/recommendations',
    params={'priority': 'high', 'status': 'active', 'limit': 20},
    headers={'Authorization': f'Bearer {API_KEY}'}
)

recommendations = response.json()['data']['recommendations']

# Sort by estimated impact
sorted_recs = sorted(
    recommendations,
    key=lambda r: r['impact_estimated'],
    reverse=True
)

print('Top 5 High-Impact Recommendations:')
for i, rec in enumerate(sorted_recs[:5], 1):
    print(f"{i}. {rec['title']}")
    print(f"   Impact: {rec['impact_estimated']} SAR ({rec['impact_confidence']}% confidence)")

Measure Recommendation Success

javascript

const API_KEY = 'looha_your_api_key'

const response = await fetch('https://api.looha.app/v1/recommendations/analytics/summary', {
  headers: { Authorization: `Bearer ${API_KEY}` },
})

const summary = await response.json()
const data = summary.data

console.log(`Recommendations Completed: ${data.completed}/${data.total}`)
console.log(`Completion Rate: ${data.completionRate}`)
console.log(`Total Impact from Completed: ${data.totalCompletedImpact} SAR`)
console.log(`Average Impact: ${data.avgImpact} SAR`)

Next: Reports API →

AI Recommendations ​

Recommendation Types ​

Categories ​

Priority Levels ​

GET /v1/recommendations ​

Parameters ​

Example Request ​

Response ​

Response Fields ​

POST /v1/recommendations/generate ​

Example Request ​

Response ​

Error Responses ​

GET /v1/recommendations/:id ​

Example Request ​

Response ​

POST /v1/recommendations/:id/dismiss ​

Example Request ​

Response ​

POST /v1/recommendations/:id/complete ​

Example Request ​

Response ​

GET /v1/recommendations/analytics/summary ​

Example Request ​

Response ​

GET /v1/recommendations/analytics/usage ​

Example Request ​

Response ​

Use Cases ​

Generate Monthly Recommendations ​

Track High-Impact Recommendations ​

Measure Recommendation Success ​

AI Recommendations

Recommendation Types

Categories

Priority Levels

GET /v1/recommendations

Parameters

Example Request

Response

Response Fields

POST /v1/recommendations/generate

Example Request

Response

Error Responses

GET /v1/recommendations/:id

Example Request

Response

POST /v1/recommendations/:id/dismiss

Example Request

Response

POST /v1/recommendations/:id/complete

Example Request

Response

GET /v1/recommendations/analytics/summary

Example Request

Response

GET /v1/recommendations/analytics/usage

Example Request

Response

Use Cases

Generate Monthly Recommendations

Track High-Impact Recommendations

Measure Recommendation Success