Create a review from your own route

Run createReviewWorkflow to create a review outside the built-in POST /store/reviews route, for example in a custom checkout follow-up, an import script, or a seed. The workflow validates the order, creates the review as pending, and writes its four links.

Before you begin

You need the following:

A customer and an order: the order’s customer_id must match the customer you pass
A target id: a product id for a product review, or a seller id for a store review
Mercur core installed: the Review module ships in @mercurjs/core, so there’s nothing else to register

Add the route

Create a route that reads the signed-in customer and runs the workflow:

src/api/store/order-reviews/route.ts

import type {
  AuthenticatedMedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { createReviewWorkflow } from "@mercurjs/core/workflows"

type Body = { order_id: string; product_id: string; rating: number }

export async function POST(
  req: AuthenticatedMedusaRequest<Body>,
  res: MedusaResponse
) {
  const { order_id, product_id, rating } = req.body
  const { result } = await createReviewWorkflow(req.scope).run({
    input: {
      order_id,
      reference: "product",
      reference_id: product_id,
      rating,
      customer_id: req.auth_context.actor_id,
    },
  })

  res.status(201).json({ review: result })
}

The route always creates a product review. Pass reference: "seller" with a seller id in reference_id to rate a store instead. customer_note is optional and defaults to null.

Require a signed-in customer

Custom /store routes aren’t authenticated by default. Add the authenticate middleware so auth_context.actor_id holds the customer id:

src/api/middlewares.ts

import { authenticate, defineMiddlewares } from "@medusajs/framework/http"

export default defineMiddlewares({
  routes: [
    {
      method: ["POST"],
      matcher: "/store/order-reviews",
      middlewares: [authenticate("customer", ["session", "bearer"])],
    },
  ],
})

This is the same middleware the built-in Store review routes use.

Call the route

Send a request as the customer who placed the order:

curl -X POST http://localhost:9000/store/order-reviews \
  -H "Authorization: Bearer your_customer_token" \
  -H "x-publishable-api-key: your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "order_01JD8Q1234567",
    "product_id": "prod_01JD8Q1234568",
    "rating": 5
  }'

The response holds the new review with status: "pending".

Validate the rating and the target

createReviewWorkflow checks only that the order belongs to the customer and that the order hasn’t reviewed this target yet. It stores any rating you pass and doesn’t check that the product or seller was part of the order. Validate both before you run it:

src/api/store/order-reviews/route.ts

if (!Number.isInteger(rating) || rating < 1 || rating > 5) {
  throw new MedusaError(MedusaError.Types.INVALID_DATA, "Invalid rating")
}

const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
const { data: [order] } = await query.graph({
  entity: "order",
  fields: ["items.product_id"],
  filters: { id: order_id },
})

if (!order?.items?.some((item) => item?.product_id === product_id)) {
  throw new MedusaError(MedusaError.Types.NOT_ALLOWED, "Not in order")
}

Import MedusaError and ContainerRegistrationKeys from @medusajs/framework/utils. Put this block before the workflow call.

Handle a rejected submission

The workflow throws a MedusaError with type INVALID_DATA in two cases, and Medusa returns them as 400 responses:

“Order not found!”: the order doesn’t exist or belongs to another customer
“Review already exists”: this order already has a review with the same reference and target id

When either check fails, nothing is written. If a later step fails, the workflow deletes the review it created.

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Before you begin

Validate the rating and the target

Handle a rejected submission

Next steps

​Before you begin

​Validate the rating and the target

​Handle a rejected submission

​Next steps

Before you begin

Validate the rating and the target

Handle a rejected submission

Next steps