OrderReviews

Purpose

The OrderReviews component renders the review page of one order, at /order-reviews/{orderId}. The
product review invitation e-mail links to this page, and so does the Reviews button of an order in
Profile → Orders (canReview on each order of the Orders reusable).

The page requires a signed-in user: a logged-out visitor is sent to log in and brought back. It is kept out
of the sitemap, and robots.txt disallows /order-reviews/.

The component:

shows one of four states: the review form while the review period is open, or a message when the period
has not started, has ended, or the order cannot be reviewed;

lists the order's products while the review period is open, each with whether it can be reviewed and, when
the customer already reviewed it, that review read-only;

submits the reviews of several products in one go, through the Ecom.Shop API below.

The theme's shipped view is a minimal read-only one: it shows the state, the order number and the products.

Inputs (model contract)

Model shape (storefront example)

{
  "state": "Open",
  "orderReview": {
    "orderId": "Order Id",
    "orderCode": "ORD00000027",
    "state": "Open",
    "reviewableFrom": "2026-01-08T00:00:00.0000000+00:00",
    "reviewableUntil": "2026-02-07T00:00:00.0000000+00:00",
    "moderationMode": "Manual",
    "products": [
      {
        "productId": "Product Id",
        "title": "Sample product title",
        "mediaItem": {
          "id": "Media Item Id",
          "link": "https://example.com/media/sample.jpg",
          "alt": "sample.jpg"
        },
        "link": "sample-product-alias",
        "variantIds": ["Variant Id"],
        "status": "Eligible",
        "existingReview": null
      },
      {
        "productId": "Product Id",
        "title": "Sample product title",
        "mediaItem": null,
        "link": "sample-product-alias",
        "variantIds": ["Variant Id"],
        "status": "AlreadyReviewed",
        "existingReview": {
          "id": "Review Id",
          "rating": 5,
          "comment": "Sample text",
          "status": "Pending",
          "createdAt": "2026-01-10T00:00:00.0000000+00:00"
        }
      },
      "..."
    ]
  },
  "name": "OrderReviews",
  "view": "Default",
  "section": "SectionA",
  "settings": {
    "id": "Component Id",
    "section": "SectionA",
    "type": "NoirOrderReviews",
    "name": "OrderReviews",
    "view": "Default",
    "cssClass": "",
    "header": ""
  },
  "translations": {
    "title": "Review your order",
    "notStarted": "Sample text",
    "ended": "Sample text",
    "notAvailable": "Sample text",
    "...": "..."
  }
}

Required fields

state: Open, NotStarted, Ended or NotAvailable.

Optional fields

orderReview

Null when state is NotAvailable: the order has no review request, it belongs to another customer
or store, or the store does not collect reviews. Show a message and no order data.

products is empty unless state is Open.

moderationMode is Manual (a submitted review waits for the merchant) or AutoPublish (it is
published at once). Use it to word the confirmation.

orderReview.products[]

status: Eligible (can be reviewed), AlreadyReviewed (from this order or an earlier one),
ProductUnavailable (no longer sold in the store) or NotInRequest.

title, mediaItem and link are null when the product can no longer be shown.

existingReview is the customer's review of the product, shown read-only.

Enum values are strings. Treat a value you do not know as "cannot review": more may be added.

translations.*

Settings tokens used by the component

model.Settings.Id

model.Settings.CssClass

JavaScript

Global object

Components/OrderReviews/Default.js exposes:

Liquid binds it via Alpine:

<section x-data="orderreviewsdefault.initComponent()">

initComponent

Creates and returns the Alpine state object. The shipped view has no client behaviour.

Services / API calls

The Ecom.Shop endpoints for the page, all for the signed-in user:

GET /api/product-reviews/orders/{orderId} returns the same data as orderReview, or a 404 problem
when the order cannot be reviewed.

POST /api/product-reviews/orders/{orderId}/reviews with
{ "reviews": [{ "productId": "...", "rating": 5, "comment": "..." }] } reviews 1 to 100 products, one
review per product.

rating is 1 to 5. comment is optional plain text, at most 1,000 characters.

It answers 200 with { "orderId": "...", "results": [{ "productId", "outcome", "reviewId", "status" }] }.
outcome is Created, AlreadyReviewed, NotInRequest or ProductUnavailable. When the review
was created, status is Pending or Published.

Each product is stored on its own, so one that cannot be reviewed does not stop the others.

Refusals are problem responses: 400 (invalid rating or comment, or a product sent twice), 401
(not signed in), 404 (the order can no longer be reviewed), 422 (the review period is closed;
state is NotStarted or Ended) and 502 (temporarily unavailable).

Dependencies

Alpine.js

Notes

Comments and author names are written by customers: render them with x-text or | escape, never as
HTML.

The page belongs to the store where the order was placed; another store's user gets NotAvailable.

Extras

Template behavior (Liquid + Alpine)

Shows 4 mutually exclusive states: Open (order number, review end date and products), NotStarted,
Ended and NotAvailable.

A product without a title shows the ProductUnavailable translation.

Loading state

This component has no skeleton loading state: it renders its content directly, and no --loading modifier class is applied.

OrderReviews

Purpose#

Inputs (model contract)#

Model shape (storefront example)#

Required fields#

Optional fields#

Settings tokens used by the component#

JavaScript#

Global object#

initComponent#

Services / API calls#

Dependencies#

Notes#

Extras#

Template behavior (Liquid + Alpine)#

Loading state#