Medusa Ratings Plugin

Private Medusa v2 plugin for product ratings and moderated reviews.

What It Adds

• A ratings module with a review DML model.
• Product-to-review module link.
• Store API:
  • GET /store/products/:id/reviews
  • POST /store/products/:id/reviews
• Admin API:
  • GET /admin/reviews
  • GET /admin/reviews/:id
  • POST /admin/reviews/:id/status
  • DELETE /admin/reviews/:id
• Admin UI route at /app/ratings.
• Product detail widget showing review summary and recent reviews.

New reviews are created as pending. Store list responses only return published reviews.

Local Development

Install dependencies in this plugin directory:

pnpm install

Run checks:

pnpm test
pnpm typecheck
pnpm build

Publish to the local package registry:

pnpm publish:local

Install In A Medusa App

From your Medusa app:

pnpm medusa plugin:add @oak-digital/medusa-plugin-ratings

Register the plugin in medusa-config.ts:

import { defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  plugins: [
    {
      resolve: "@oak-digital/medusa-plugin-ratings",
      options: {},
    },
  ],
})

Generate and run migrations in the Medusa app:

pnpm medusa db:generate ratings
pnpm medusa db:migrate

This package also includes a checked-in migration for the review table. If you change the model, regenerate migrations before installing the updated plugin.

API Notes

Create a review:

curl -X POST "http://localhost:9000/store/products/prod_123/reviews" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: pk_..." \
  --data '{
    "rating": 5,
    "title": "Great fit",
    "content": "The product matched the description.",
    "reviewer_name": "A customer",
    "reviewer_email": "[email protected]"
  }'

Publish a review:

curl -X POST "http://localhost:9000/admin/reviews/rev_123/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  --data '{ "status": "published" }'

List published reviews:

curl "http://localhost:9000/store/products/prod_123/reviews?limit=10&offset=0" \
  -H "x-publishable-api-key: pk_..."

Response Shape

Store review list responses include:

{
  "reviews": [],
  "average_rating": 0,
  "review_count": 0,
  "count": 0,
  "limit": 10,
  "offset": 0
}

Admin review list responses include reviewer_email and moderation fields. Store responses intentionally omit private reviewer email.

medusa-ratings-module