Create Product Review

Submit a review and rating for a product.

Endpoint

POST /api/shop/reviews

The product is identified by productId in the body. There is no POST /products/{id}/reviews route — that path exists for reading only.

Request Headers

Header	Required	Description
Content-Type	Yes	application/json
X-STOREFRONT-KEY	Yes	Your storefront API key
Authorization	Depends	Customer Bearer token. Required unless the store allows guest reviews.

Request Body

{
  "productId": 126,
  "title": "Excellent product!",
  "comment": "Very satisfied with this purchase.",
  "rating": 5,
  "name": "John Doe"
}

Field	Type	Required	Description
productId	integer	Yes	The product being reviewed. product_id is accepted as well.
title	string	Yes	Review headline.
comment	string	Yes	Review body. No minimum length is enforced.
rating	integer	Yes	Star rating from 1 to 5.
name	string	No	Display name shown with the review.

Response Fields (201 Created)

The stored review, flat — there is no wrapper object and no message.

Field	Type	Description
id	integer	Review ID. Needed for Update and Delete.
name	string	Display name as submitted.
title / comment	string	Review text as submitted.
rating	integer	Star rating.
status	string	Always pending on creation.
createdAt / updatedAt	string	ISO 8601 timestamps.

The product ID is not echoed back — keep it client-side if the confirmation screen needs it.

Who Can Review

Two store settings gate this endpoint, and both are enforced here.

Setting	Effect when off
Customer reviews	Every submission is refused with 403, token or not.
Guest reviews	A submission without a customer token is refused with 403. Logged-in customers are unaffected.

Nothing stops the same customer reviewing the same product more than once — enforce a one-review rule in the client if the store wants one.

Use Cases

• Review form on a product page — post the four fields and show the returned status of pending, since the review will not appear in the default listing until it is approved.
• Show the customer their own submission — the default product-review listing excludes pending rows, so read it back with ?status=pending on Get Product Reviews.

Best Practices

• Tell the shopper the review is awaiting approval — a 201 here does not mean the review is visible; it is stored as pending.
• Validate the rating before sending — the server rejects anything outside 1–5, and a slider that allows 0 produces a 400 after the shopper has typed a review.
• Send name explicitly — it is optional and is not filled in from the customer's profile, so a review submitted without it displays with an empty author.
• Check the store's review settings before rendering the form — a store with reviews disabled answers 403 on every submission, so the form should not be shown at all.

Related Resources

• Get Product Reviews — a product's reviews, approved only by default
• Update Product Review — edit the customer's own review
• Delete Product Review — remove the customer's own review