Ratings and Reviews

Rating System

Packages are rated on a 1-5 star scale. Only users who have successfully installed the package in their tenant can submit a rating. This prevents fake reviews from users who have never used the package.

Submitting a Review

POST /api/marketplace/packages/{packageId}/reviews
Authorization: Bearer {token}
{
  "rating":    5,
  "title":     "Works exactly as described",
  "body":      "Installed in minutes, onboarding flow is clean and the approval logic is solid. Required minor customization for our department structure but the merge strategy made that easy.",
  "version":   "3.0.0"
}

// Response:
{
  "reviewId":    "rev-a1b2c3",
  "status":      "PendingModeration",
  "message":     "Your review will appear after moderation (typically 24-48 hours)."
}

Getting Reviews

GET /api/marketplace/packages/{packageId}/reviews?pageSize=10&sortBy=helpful

{
  "averageRating": 4.8,
  "totalReviews":  142,
  "distribution":  { "5": 110, "4": 22, "3": 8, "2": 1, "1": 1 },
  "reviews": [
    {
      "reviewId":    "rev-a1b2c3",
      "rating":      5,
      "title":       "Works exactly as described",
      "body":        "Installed in minutes...",
      "author":      "Engineer at Acme Corp",
      "version":     "3.0.0",
      "publishedAt": "2026-05-10T00:00:00Z",
      "helpfulCount": 34
    }
  ]
}

Moderation Policy

All reviews are moderated before publication. Reviews are rejected if they:

• Contain personal information about the reviewer or others
• Include profanity or abusive language
• Are not related to the package's functionality
• Appear to be fake or coordinated
• Are submitted by the package publisher (publishers cannot review their own packages)

Flagging a Review

POST /api/marketplace/reviews/{reviewId}/flag
{ "reason": "Appears to be fake — submitted within 1 hour of install with no substantive content" }

Flagged reviews are removed from public view pending moderation investigation.

Review Impact on Trust

Packages with consistently low ratings (below 2.5 stars with 10+ reviews) are flagged for re-review by the marketplace team. Official and Certified packages that fall below 3 stars may have their trust level suspended pending investigation.