How to

Handle product reviews

Submit and fetch product reviews using Geins Merchant API

Overview

Learn how to submit and fetch product reviews. This guide covers fetching reviews for a product and allowing customers to post their own reviews.

Prerequisites

Merchant API key
Product alias for the product you want to review or fetch reviews for

Goal

Submit a new product review
Fetch all reviews for a specific product
Display reviews with pagination

Architecture at a glance

Submit new review → Query reviews → Display to users with pagination

Step-by-step

Submit a new product review

Allow customers to post reviews for products they've purchased.

Try it out in the GraphQL Playground using the query, headers and variables below.

Request example

mutation postProductReview(
  $alias: String!
  $rating: Int
  $comment: String
  $author: String!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  postProductReview(
    alias: $alias
    rating: $rating
    comment: $comment
    author: $author
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  )
}

{
  "Accept": "application/json",
  "X-ApiKey": "{MERCHANT_API_KEY}"
}

{
  "alias": "{PRODUCT_ALIAS}",
  "rating": 5,
  "comment": "Amazing product! Exceeded my expectations.",
  "author": "John Doe",
  "channelId": "{CHANNEL_ID}",
  "languageId": "{LANGUAGE_ID}",
  "marketId": "{MARKET_ID}"
}

curl -X POST https://merchantapi.geins.io/graphql \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-ApiKey: {MERCHANT_API_KEY}" \
  -d '{"query":"mutation postProductReview($alias: String!, $rating: Int, $comment: String, $author: String!, $channelId: String, $languageId: String, $marketId: String) { postProductReview(alias: $alias, rating: $rating, comment: $comment, author: $author, channelId: $channelId, languageId: $languageId, marketId: $marketId) }","variables":{"alias":"{PRODUCT_ALIAS}","rating":5,"comment":"Amazing product! Exceeded my expectations.","author":"John Doe","channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'

Response example

200 OK

response.json

{
  "data": {
    "postProductReview": true
  }
}

Get reviews for a product

Retrieve all reviews for a specific product using the product alias.

Try it out in the GraphQL Playground using the query, headers and variables below.

Request example

query reviews(
  $alias: String
  $skip: Int
  $take: Int
  $channelId: String
  $languageId: String
  $marketId: String
) {
  reviews(
    alias: $alias
    skip: $skip
    take: $take
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  ) {
    reviews {
      rating
      comment
      reviewDate
      author
    }
    count
    averageRating
  }
}

{
  "Accept": "application/json",
  "X-ApiKey": "{MERCHANT_API_KEY}"
}

{
  "alias": "{PRODUCT_ALIAS}",
  "skip": 0,
  "take": 10,
  "channelId": "{CHANNEL_ID}",
  "languageId": "{LANGUAGE_ID}",
  "marketId": "{MARKET_ID}"
}

curl -X POST https://merchantapi.geins.io/graphql \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-ApiKey: {MERCHANT_API_KEY}" \
  -d '{"query":"query reviews($alias: String, $skip: Int, $take: Int, $channelId: String, $languageId: String, $marketId: String) { reviews(alias: $alias, skip: $skip, take: $take, channelId: $channelId, languageId: $languageId, marketId: $marketId) { reviews { rating comment reviewDate author } count averageRating } }","variables":{"alias":"{PRODUCT_ALIAS}","skip":0,"take":10,"channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'

Response example

200 OK

response.json

{
  "data": {
    "reviews": {
      "reviews": [
        {
          "rating": 5,
          "comment": "Excellent product! Highly recommended.",
          "reviewDate": "2025-10-15T12:34:56Z",
          "author": "John Doe"
        },
        {
          "rating": 4,
          "comment": "Very good quality, but a bit expensive.",
          "reviewDate": "2025-10-14T10:20:30Z",
          "author": "Jane Smith"
        }
      ],
      "count": 23,
      "averageRating": 4.5
    }
  }
}

Display reviews with pagination

Use the skip and take parameters to implement pagination for the reviews list.

Options

Pagination

Use skip and take parameters to paginate through reviews:

skip: Number of reviews to skip (default: 0)
take: Number of reviews to return per page (default: 10)
count: Total number of reviews available

Example for page 2 with 10 reviews per page:

{
  "skip": 10,
  "take": 10
}

Multi-market support

All queries and mutations support optional parameters for multi-market functionality:

channelId: Target specific sales channels
languageId: Set content language
marketId: Target specific markets

Read more about channelId, languageId, and marketId in the how-to about using multi-market support.

Handle canonical URLs

Learn how to handle canonical URLs and redirects in Geins Merchant API and Management API.

Authenticate users and obtain Bearer tokens for Geins Merchant API access using Geins Auth Service