Reviews API overview

🚧

These endpoints are in beta and are subject to change

A beta revision header (2024-07-15.pre) is required to use these beta APIs. Klaviyo APIs in beta are not intended for use in production. See our versioning and deprecation policy for more information.

Before you begin

Check out our general API overview to make sure you’re ready to get started with specific endpoints.

🚧

Note that Klaviyo Reviews is billed separately from Klaviyo email and SMS and is not included with your Klaviyo email or SMS plan.

Our Reviews API allows you to query your product reviews so that you can ensure that your product experience puts customers first. For example, you may want to write a script that queries all negative reviews (1 or 2 stars) and checks if they have been addressed thoughtfully, i.e., a public reply has been sent for each negative review. Or, you may want to source quotes from 5-star product reviews for use in future email marketing. Use the Reviews API to identify areas for product improvements and provide a high-quality customer experience.

Use cases

Here are some example use cases supported by the Reviews API:

• Fetch all positive and/or negative reviews for a specific product given its catalog ID (item.id). See Querying reviews.
• Get all "verified" reviews, i.e., ones that have been submitted by authors who have a verified purchase.
• Fetch a specific review by review ID.
• Query negative reviews based on a rating threshold (1 or 2 stars) and check whether or not a public reply exists for each review.
• Query reviews based on specific content, e.g., reviews that include “arrived quickly.”

Data model

A review has the following structure:

• id

  The ID of the review.

• attributes

  • email

    The email address of the review’s author.

  • status

    The status of the review ("published","unpublished","featured","pending",or "rejected").

  • verified

    Whether or not the review is verified, i.e., the review author is a true purchaser of the product .

  • review_type

    The type of review, whether it includes written content with a rating ("review"), an answer to a question about the product ("question"), or a rating without written content ("rating").

  • created

    The timestamp of when the metric was created.

  • updated

    The timestamp of when the metric was last updated.

  • images

    Images of the product included in the review.

  • product

    • url

      The URL of the product.

    • name

      The name of the product.

    • image_url

      The image URL of the product.

  • rating

    The rating of the product (must be an integer from 1-5).

  • author

  • The author of the review, e.g., "Jane Doe."

  • content

    The written content of the review, e.g., “Arrived in great condition.”

  • title

    The title of the review.

  • smart_quote

    A quote sourced from the review’s content, which may be used to display in emails marketing the product.

  • public_reply

    • content

      The written content of a public reply to the review.

    • author

      The author, or company, of the public reply.

    • updated

      The timestamp of when the reply was last updated.

Get Reviews

The Get Reviews endpoint is useful for retrieving information including review content and ratings provided for catalog items. Similarly, the Get Review endpoint fetches the same information for a specified review ID.

The example request to Get Reviews below uses filters and sparse fieldsets to request the product, author, content, and rating for each review that includes the word “great”:

curl --request GET \
     --url 'https://a.klaviyo.com/api/reviews/?filter=contains(content,"great")&fields[review]=product,author,content,rating' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2024-07-15.pre'

{
    "data": [
        {
            "type": "review",
            "id": "3319486",
            "attributes": {
                "product": {
                    "url": "https://craft-supplies-monthly.myshopify.com/products/zinnia-seeds",
                    "name": "Zinnia Seeds",
                    "image_url": "https://cdn.shopify.com/s/files/1/0284/3128/6351/products/zinnia-preciosa-mix.jpg?v=1621447394"
                },
                "author": "kaylak",
                "content": "Arrived quickly and the packaging is great! ",
                "rating": 5
            },
            "relationships": {
                "events": {
                    "links": {
                        "self": "https://a.klaviyo.com/api/reviews/3319486/relationships/events/",
                        "related": "https://a.klaviyo.com/api/reviews/3319486/events/"
                    }
                },
                "item": {
                    "data": {
                        "type": "catalog-item",
                        "id": "$shopify:::$default:::6569395126351"
                    }
                }
            },
            "links": {
                "self": "https://a.klaviyo.com/api/reviews/3319486/"
            }
        },
        {
            "type": "review",
            "id": "82650",
            "attributes": {
                "product": {
                    "url": "https://craft-supplies-monthly.myshopify.com/products/magnolia-tree-4-5ft",
                    "name": "Magnolia tree, 4-5ft",
                    "image_url": "https://cdn.shopify.com/s/files/1/0284/3128/6351/products/magnolia.jpg?v=1621447133"
                },
                "author": "sarah.mason",
                "content": "Arrived quickly and in great condition! ",
                "rating": 5
            },
            "relationships": {
                "events": {
                    "links": {
                        "self": "https://a.klaviyo.com/api/reviews/82650/relationships/events/",
                        "related": "https://a.klaviyo.com/api/reviews/82650/events/"
                    }
                },
                "item": {
                    "data": {
                        "type": "catalog-item",
                        "id": "$shopify:::$default:::6569393061967"
                    }
                }
            },
            "links": {
                "self": "https://a.klaviyo.com/api/reviews/82650/"
            }
        }
    ],
    "links": {
        "self": "https://a.klaviyo.com/api/reviews?filter=contains(content,%22great%22)&fields[review]=product,author,content,rating",
        "next": null,
        "prev": null
    }
}

Querying reviews

Querying reviews with the Reviews API can help you achieve many use cases. Check out the supported query parameters below and test them with our latest Postman collection. Note that support for given operators and fields is endpoint-specific. Review the API reference documentation for more information on allowed fields and query parameters.

📘

Note: The catalog ID is a composite ID, e.g., "$shopify:::$default:::8020637942075". For custom integrations, use $custom for integration_type in the example format shown in the filter` example above.

Limitations

These private-key APIs are primarily intended for data analysis and export purposes. You cannot use them to directly power an onsite or in-app reviews widget. Never use a Klaviyo private key on your website or app, as it may be intercepted and used to request sensitive data from your account.

Additional resources

• Getting started with Klaviyo Reviews
• Use advanced CSS to style Klaviyo Reviews widgets
• Klaviyo Reviews CSS class reference