Product Reviews with the GraphQL Storefront API

BigCommerce's GraphQL Storefront API allows you to create and query product reviews (opens in a new tab) through the built-in comment system.

Store settings

There are a few store settings to consider when creating a product review:

Overall enable product reviews

The merchant must enable this overall setting for the review submission process. Turning off this setting cancels any attempts to submit reviews.

Only accept product reviews from past customers

When the merchant enables the 'Only accept product reviews from past customers' setting, only logged-in customers (not guest shoppers) can submit a review, and they must have at least one previous order placed in the store. This setting ensures the merchant has a genuine customer to contact if needed. You can use the login mutation to log in a customer. After a purchase, customers can review any item in the store. The order doesn't have to include the reviewed product.

When the merchant turns off the setting, guest shoppers can also submit reviews but they must provide an email. Since guests do not log in, they must supply the email in the request as an input parameter. Logged-in customers don't need to provide the email through the input parameter, as the system will use the email from the customer's account. If the logged-in customer provides an email as input, BigCommerce will validate the email against the email associated with the shopper's account. If the email doesn't match, the submission will fail.

In all cases, you can create only one review per product an email address.

Enable reCAPTCHA

If a merchant enables the reCAPTCHA setting (opens in a new tab) on the storefront, you need to send a reCAPTCHA token with the request.

Mutation

The following mutation creates a product review for a store.

Example request: Create a product review

mutation {
  catalog {
    addProductReview (
      reCaptchaV2: "12345"
      input: {
        productEntityId: 81
          review: {
            title: "Great product"
            text: "Would recommend"
            author: "example author"
            rating: 4  # integer value between 1 and 5
            email: "name@example.com"
        }
      }
    ){
      errors {
        ...on NotAuthorizedToAddProductReviewError {
          message
        }
        ...on CustomerAlreadyReviewedProductError {
          message
        }
        ...on ProductIdNotFoundError {
          message
        }
        ...on InvalidInputFieldsError {
          message fields
        }
        ...on Error{
          message
        }
      }
    }
  }
}

Query

You can query the product review with the products GraphQL node.

Example request: Query a product review

query {
  site {
    products (entityIds: [81]) {
      edges {
        node {
          reviews {
            edges {
              node {
                entityId
                author {
                  name
                }
                title
                text
                rating
                createdAt {
                  utc
                }
              }
            }
          }
        }
      }
    }
  }
}

Resources

Did you find what you were looking for?

Orders Routes and content