# Add Product Reviews to a Medusa Store

Yes. An agent adds a review module, store and admin routes, a moderation page in the admin and a reviews section on the product page, with tests, in one PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-product-reviews/medusa/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the monorepo's own rules before writing a line, because a Medusa project has a fixed shape and a linter that enforces it. In a store like medusajs/dtc-starter, the root `package.json` pins `pnpm@10.11.1`, Turbo runs `build`, `lint` and `test`, and `AGENTS.md` says what goes where: routes under `apps/backend/src/api/{store,admin}/<path>/route.ts`, business logic in `apps/backend/src/workflows/`, a custom data model under `apps/backend/src/modules/<name>/`, links under `src/links/`, and admin pages under `src/admin/`. The backend depends on `@medusajs/medusa` 2.22.2, `@medusajs/admin-sdk`, `@medusajs/ui` 4.2.9 and `zod` 4.2.0, `medusa-config.ts` registers no custom modules yet, and `src/api/middlewares.ts` already calls `defineMiddlewares` with one entry that applies `configureStoreSearch` to `POST /store/search`. The `jest.config.js` selects suites by `TEST_TYPE`, `integration:http` matching `integration-tests/http/*.spec.ts`, and `AGENTS.md` warns those suites need a reachable PostgreSQL. The storefront is Next.js 16 with React 19; its product page is `apps/storefront/src/modules/products/templates/index.tsx`, which lays out `ProductInfo`, `ProductTabs`, `VariantImageGallery`, `ProductActions` and `RelatedProducts`, and its server calls live in `apps/storefront/src/lib/data/`, where `products.ts` wraps `sdk` with `getAuthHeaders` and `getCacheOptions`.

The backend follows the shape Medusa's own product-reviews tutorial lays out, which the agent reads alongside the installed package's `AGENTS.md`. A new module at `src/modules/product-review/` defines a `review` model with `model.define`: `title` nullable text, `content` text, `rating` as a float with a `rating_range` check between 1 and 5, `first_name` and `last_name`, a `status` enum of `pending`, `approved` and `rejected` defaulting to `pending`, an indexed `product_id` and a nullable `customer_id`. `service.ts` extends `MedusaService({ Review })` and adds a `getAverageRating` query, `index.ts` exports `PRODUCT_REVIEW_MODULE` as `productReview`, and `medusa-config.ts` gains `modules: [{ resolve: "./src/modules/product-review" }]`. A read-only link in `src/links/review-product.ts` joins `review.product_id` to the Product Module's `product`, so `query.graph` can load a product's reviews. `pnpm exec medusa db:generate productReview` writes the migration, the one step `AGENTS.md` says people forget.

Then the workflows and routes. `createReviewWorkflow` confirms the product exists with `useQueryGraphStep`, then runs a `createReviewStep` whose compensation deletes the review; `updateReviewWorkflow` changes status with a step that restores the old statuses on failure. `POST /store/reviews` runs the first and `GET /store/products/[id]/reviews` returns approved reviews with the average; `GET /admin/reviews` lists with `createFindParams()` and `POST /admin/reviews/status` takes `ids` and a `status`. In `middlewares.ts` the agent adds entries beside the existing search one: `authenticate("customer", ["session", "bearer"])` and `validateAndTransformBody` with a Zod schema whose `rating` is `min(1).max(5)` on the store POST, `validateAndTransformBody` on the admin POST and `validateAndTransformQuery` on the two GETs. A UI route at `src/admin/routes/reviews/page.tsx`, registered with `defineRouteConfig`, shows a `DataTable` from `@medusajs/ui` with row selection and Approve and Reject commands calling the status route. The code keeps the repository's style: no semicolons, double quotes, kebab-case files, and nothing imported from `@medusajs/utils` directly.

The storefront gets `getProductReviews` and `addProductReview` in `lib/data/products.ts`, a `product-reviews` component with the average, the list and a load-more button, a form shown only to a logged-in customer, and one line in the product template rendering the component under the related products. For proof the agent writes `apps/backend/integration-tests/http/reviews.spec.ts` with `medusaIntegrationTestRunner` from `@medusajs/test-utils`: a customer posts a review and reads it back as pending, the store list hides it, the admin approves it, the store list shows it with the average. It installs PostgreSQL in its sandbox, points `DATABASE_URL` at it, runs `pnpm run test:integration:http` from `apps/backend`, then `pnpm run lint` there, which runs `medusa lint` with the `@medusajs/eslint-plugin` rules, `pnpm run build` for both apps, and opens the product page in its browser against the running backend.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add product reviews to this Medusa store. Read the root package.json and AGENTS.md, apps/backend/medusa-config.ts, apps/backend/src/api/middlewares.ts, the READMEs under apps/backend/src, apps/backend/jest.config.js, the AGENTS.md shipped in node_modules/@medusajs/framework after pnpm install, and the storefront's product template and lib/data/products.ts first. Add a product-review module with a review model (nullable title, content, rating 1 to 5, first and last name, status pending/approved/rejected, indexed product_id, nullable customer_id), register it in medusa-config.ts, add a read-only link to the product, and generate its migration. Add create and update-status workflows with compensation, the routes POST /store/reviews, GET /store/products/:id/reviews (approved only, with the average rating), GET /admin/reviews and POST /admin/reviews/status, with Zod validation and customer authentication in middlewares.ts. Add an admin UI route listing reviews with approve and reject actions, and a storefront reviews section with a form for logged-in customers on the product page. Write an HTTP integration test covering post, moderation and listing, run it against a local PostgreSQL, run lint and build for both apps, and open a pull request with the output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds the module directory with its generated migration, the link file, two workflows with their steps, four route files, the admin page, the storefront component, form and data functions, and the integration spec, and changes `medusa-config.ts`, `middlewares.ts` and the product template. Its description quotes the Jest output for the new spec, the `medusa lint` result and both builds, and shows the product page with a review and the admin table from the run's record.

A reviewer reads the model and the migration together, since a column is the one thing that is hard to change after deploy, then the middleware entries, which decide who may post and what a payload must contain. Running `pnpm exec medusa db:migrate` on a staging database and posting one review through the storefront is the last check before merge; the test already did the same against a fresh database.

## Run it on every Linear issue labelled storefront

In the console, add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled`, filtered to the `storefront` label. When an issue such as "customers should be able to rate products" gets the label, the trigger puts the issue after the prompt, and the run reads what fields and moderation the issue asks for before it defines the model. Only label changes by a person in your Rush org fire it, and the automation starts at most `max_runs_per_hour` runs in an hour.

An automation's runs are read-only, so the run that pushes the branch starts from your own server: a handler receiving the automation's comment sends this body to `POST /o/{org}/sessions` with the issue URL in `resources` and a `request_id` that is a UUID v5 of the issue id, so a redelivered event returns the run already started.

## Why run it on Rush?

A review feature crosses every layer of a Medusa project: a model and migration, a link, workflows, routes with validation, an admin page and a storefront section, and the framework's linter rejects code that skips its conventions. The agent reads the project's `AGENTS.md` and the installed package's own notes, follows them, and runs the integration suite against a real PostgreSQL in its own sandbox, with every command and its output kept in the run's record.

The part a laptop rarely finishes is the proof: a database, a migration, a running backend, a test that posts and moderates a review, and a browser on the product page. The agent does all of it before opening the pull request, so the reviewer reads a change that has already been exercised end to end.

## Frequently asked questions

### Can anyone post a review?

No. `middlewares.ts` applies `authenticate("customer", ["session", "bearer"])` to `POST /store/reviews`, so only a logged-in customer can post, and the route takes `customer_id` from the authenticated actor rather than the body. The storefront shows the form only when a customer is signed in.

### Do reviews appear immediately?

No. A new review is `pending`, the store listing returns only `approved` ones, and an admin approves or rejects from the Reviews page or `POST /admin/reviews/status`. Change the model's default to `approved` if you want no moderation; the migration and the tests follow.

### Does the test need a database?

Yes. `medusaIntegrationTestRunner` creates a fresh database per suite on a PostgreSQL it reaches through `DATABASE_URL`, which is why the agent installs one in its sandbox. The pull request names the environment variables the suite reads so CI can do the same.

### Why workflows instead of calling the service from the route?

The project's `AGENTS.md` puts business logic in workflows, and the framework's lint rules expect it. A workflow step carries a compensation, so a failed create leaves no half-written review, and the same workflow can later be run from a subscriber or a scheduled job.

### What if the storefront directory does not exist?

The starter's storefront is optional, and the project's `AGENTS.md` says to check before assuming it. The agent then ships the backend, the admin page and the test, and the pull request says the store routes are ready for whichever storefront you run.

## More Medusa jobs

- [Add Rate Limiting to a Medusa Store API](https://getrush.ai/run/add-rate-limiting/medusa/)
- [Set Up Redis for a Medusa Backend](https://getrush.ai/run/add-redis/medusa/)
- [Add S3 File Storage to a Medusa Backend](https://getrush.ai/run/add-s3-file-storage/medusa/)

## More jobs like this: Turn a Linear label into a PR

- [Add Prometheus Metrics to an aiohttp App](https://getrush.ai/run/add-prometheus-metrics/aiohttp/)
- [Add Prometheus Metrics to Broadway SQS Pipelines With PromEx](https://getrush.ai/run/add-prometheus-metrics/broadway/)
- [Add Prometheus Metrics to a Celery App](https://getrush.ai/run/add-prometheus-metrics/celery/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
