Reviews API

REST API endpoints for reading product reviews and submitting verified buyer reviews.

Reviews are ratings (1-5 stars) and text written by customers who bought the product. A review needs a review token that proves the purchase, and it is created pending approval (approved: false). YNS decides which reviews are published, so the store API is read-only for moderation: store credentials can list and read reviews but cannot approve, unpublish, or delete them. Only approved reviews appear on the storefront.

List Reviews

GET /api/v1/reviews

Returns the store's reviews, including those waiting for YNS approval. Read-only. To submit a review, use POST /api/v1/products/{idOrSlug}/reviews.

Query Parameters

curl -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/reviews?approved=false"

Response (200)

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "productId": "0191abc0-0000-7000-8000-000000000200",
      "author": "Jane Doe",
      "email": "jane@example.com",
      "content": "Great quality, fits perfectly.",
      "rating": 5,
      "orderId": "0191abc0-0000-7000-8000-000000000300",
      "verified": true,
      "approved": false,
      "createdAt": "2024-06-15T10:30:00.000Z",
      "updatedAt": "2024-06-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 10
  }
}

Get Review

GET /api/v1/reviews/{id}

Returns a single review by UUID. orderId is the paid order behind a verified review; it is null (and verified is false) for reviews written before purchase verification.

curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/reviews/0191abc0-1234-7def-8000-000000000001

Response (200)

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "productId": "0191abc0-0000-7000-8000-000000000200",
  "author": "Jane Doe",
  "email": "jane@example.com",
  "content": "Great quality, fits perfectly.",
  "rating": 5,
  "orderId": "0191abc0-0000-7000-8000-000000000300",
  "verified": true,
  "approved": false,
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T10:30:00.000Z"
}

List Product Reviews

GET /api/v1/products/{idOrSlug}/reviews

Returns approved reviews for a single product, with pagination and summary statistics (average rating and total review count). verified is true for a review written from a paid order; reviews from before purchase verification are false. The product can be referenced by UUID or slug. When translations are enabled, pass ?lang= to resolve a translated slug.

Query Parameters

curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/products/classic-tee/reviews

Response (200)

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "author": "Jane Doe",
      "content": "Great quality, fits perfectly.",
      "rating": 5,
      "createdAt": "2024-06-15T10:30:00.000Z",
      "verified": true
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 10
  },
  "summary": {
    "averageRating": 4.8,
    "reviewCount": 1
  }
}

Create Product Review

POST /api/v1/products/{idOrSlug}/reviews

Submits a buyer's review. Only customers who bought the product can review it, so the request must carry a review token. The reviewer's email is taken from the order. Each purchase can be reviewed once per product. Reviews are created with approved: false and appear publicly after YNS approves them.

Get a token from the ?token= parameter of the review link in the delivered-order email, or, for a signed-in buyer, from the storefront's same-origin GET /checkout/api/review-token?product={productId}.

Request Body

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "review_token_from_email",
    "author": "Jane Doe",
    "content": "Great quality, fits perfectly.",
    "rating": 5
  }' \
  https://your-store.yns.store/api/v1/products/classic-tee/reviews

Response (201)

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "author": "Jane Doe",
  "content": "Great quality, fits perfectly.",
  "rating": 5,
  "createdAt": "2024-06-15T10:30:00.000Z",
  "verified": true
}

Errors