# Product review feed schema - Commerce Platform
Use this product review feed schema to onboard on to our ratings and review system for Shops. The feed should be sent over as a JSON, and contain the fields described below.
## Root Elements
The top-level elements of the JSON response.
| Element | Description |
| --- | --- |
| `aggregator`<br><br>Type: string | **Optional**.<br><br>The reviews aggregator used by the store to manage their review feeds. This field stores the name of the aggregator. |
| `store`<br><br>Type: [`Store`](#store) | **Required**.<br><br>Information about the store for which the product reviews are for. |
| [`reviews`](#review)<br><br>Type: Array<Review> | **Required**.<br><br>Contains the product reviews. |
## Types {#types}
### Store {#store}
| Element | Description |
| --- | --- |
| `name`<br><br>Type: string | **Required**.<br><br>Name of the store the review feed is for. |
| `id`<br><br>Type: string | **Optional**.<br><br>Unique identifier of the store on the aggregator's platform. |
| `storeUrls`<br><br>Type: Array<string> | **Optional**.<br><br>Domains owned by the store where they sell their products. Do not include any third-party seller websites, such as "amazon.com".<br><br>Example: `["www.sephora.com", "www.sephora.de"]` |
### Review {#review}
| Element | Description |
| --- | --- |
| `reviewID`<br><br>Type: string | **Required**.<br><br>Unique identifier for the review. |
| `rating`<br><br>Type: integer | **Required**.<br><br>Rating, from 1–5. |
| `title`<br><br>Type: string | **Required**.<br><br>Review title. |
| `content`<br><br>Type: string | **Required**.<br><br>Review text. Should be a non-empty string. Emojis should be [UTF-8](https://en.wikipedia.org/wiki/UTF-8)-encoded. |
| `createdAt`<br><br>Type: string | **Required**.<br><br>Review creation date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.<br><br>Examples:<br><br>Complete date:<br><br>`YYYY-MM-DD (eg 1997-07-16)`<br><br>Complete date plus hours and minutes:<br><br>`YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00)`<br><br>Complete date plus hours, minutes and seconds:<br><br>`YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)`<br><br>Complete date plus hours, minutes, seconds and a decimal fraction of a second:<br><br>`YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)` |
| `updatedAt`<br><br>Type: string | **Optional**.<br><br>When the review was last updated. |
| `reviewImageUrls`<br><br>Type: Array<string> | **Optional**.<br><br>List of URLs for published images as uploaded by shoppers with the review. |
| `incentivized`<br><br>Type:boolean | **Required**.<br><br>Represents whether the review was obtained via an incentivized promotion run by the merchant. |
| `hasVerifiedPurchase`<br><br>Type:boolean | **Optional**.<br><br>Represents whether the review was left after a verified purchase of the product. |
| `reviewer`<br><br>Type: [Reviewer](#reviewer) | **Required**.<br><br>Review author's information. |
| `product`<br><br>Type: [Product](#product) | **Required**.<br><br>Information about the product the review is associated with. |
| `language`<br><br>Type: string | **Optional**.<br><br>The language used for the written review. The string should be in [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code format.<br><br>Example: `en` |
| `country`<br><br>Type: string | **Optional**.<br><br>Country from where the review was written. The string should be in [ISO 3166 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. See also [glossary for ISO 3166](https://www.iso.org/glossary-for-iso-3166.html).<br><br>Example: `US` |
| `merchantResponse`<br><br>Type: [ReviewResponse](#reviewresponse) | **Optional**.<br><br>A reply to the given review from the merchant. |
| `secondaryRatings`<br><br>Type: Map<string, int> | **Optional**.<br><br>JSON key-value pairs representing secondary review ratings. These can be any other ratings that were collected as part of the review. The value should be an integer between 1 and 5 with 5 being the best and 1 being the worst.<br><br>Example: `{"quality": 5, "shipping speed": 3, "value for price": 1}` |
| `secondaryAttributes`<br><br>Type: Map<string, string> | **Optional**.<br><br>JSON key-value pairs representing secondary review attributes. This can be any other free-form information that was collected as part of the review.<br><br>Example: `{"size": "true to size"}` |
### Reviewer {#reviewer}
| Element | Description |
| --- | --- |
| `name`<br><br>Type: string | **Required**.<br><br>Full name of the reviewer.<br><br>Example: `John Doe` |
| `reviewerID`<br><br>Type: string | **Optional**.<br><br>Unique identifier for the reviewer. |
| `isAnonymous`<br><br>Type: boolean | **Optional**.<br><br>Represents whether the reviewer is anonymous. |
### ReviewResponse {#reviewresponse}
| Element | Description |
| --- | --- |
| `name`<br><br>Type: string | **Required**.<br><br>Full name of the person or merchant replying to the review.<br><br>Example: `Sephora` |
| `id`<br><br>Type: string | **Required**.<br><br>A unique identifier for the reply. |
| `content`<br><br>Type: string | **Required**.<br><br>Reply Text. Should be a non-empty string. Emojis should be UTF-8 encoded. |
| `createdAt`<br><br>Type: string | **Required**.<br><br>Reply Creation Date in ISO8601.<br><br>Examples:<br><br>Complete date:<br>`YYYY-MM-DD (eg 1997-07-16)`<br><br>Complete date plus hours and minutes:<br>`YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00)`<br><br>Complete date plus hours, minutes and seconds:<br>`YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)`<br><br>Complete date plus hours, minutes, seconds and a decimal fraction of a second:<br>`YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)`<br>. |
| `updatedAt`<br><br>Type: string | **Optional**.<br><br>When the reply was updated last. |
| `language`<br><br>Type: string | **Optional**.<br><br>The language reply was written in. The string should be in ISO 639-1 code format.<br><br>Example: `en` |
| `country`<br><br>Type: string | **Optional**.<br><br>Country the reply was written from. The string should be in ISO 3166 Alpha-2 format.<br><br>Example: `US` |
### Product {#product}
| Element | Description |
| --- | --- |
| `name`<br><br>Type: string | **Required**.<br><br>Name of the product. |
| `url`<br><br>Type: string | **Required**.<br><br>Link to the product detail page on the store's website. |
| `imageUrls`<br><br>Type: Array<string> | **Optional**.<br><br>List of image urls associated with the product. |
| `groupID`<br><br>Type: string | **Optional**.<br><br>ID for a group of products that share reviews. You can choose to share the `groupID` or all of the variants directly using the `variants` field. |
| `productIdentifiers`<br><br>Type: [ProductIdentifiers](#product-identifiers) | **Optional**.<br><br>List of all the different identifiers that can be used to match the reviews to a product in the Meta commerce catalog. |
| `variants`<br><br>Type: Array<ProductVariant> | **Optional**.<br><br>Different [variants of this product](#product-variant) that can share the same reviews. |
| `productStatus`<br><br>Type: Enum `{"active", "inactive"}` | **Optional**.<br><br>Status of the product. "active" if the product is still active and "inactive" if the product is no longer being sold. |
### ProductIdentifiers {#product-identifiers}
| Element | Description |
| --- | --- |
| `gtins`<br><br>Type: Array<string> | **Optional**.<br><br>Global trade item numbers (GTINs) associated with the product. |
| `mpn`<br><br>Type: string | **Optional**.<br><br>Manufacturer part number (MPN) associated with the product. |
| `brand`<br><br>Type: string | **Optional**.<br><br>Brand name associated with the product. |
| `shopifyProductID`<br><br>Type: string | **Optional**.<br><br>Shopify Product ID associated with the product. |
| `skus`<br><br>Type: Array<string> | **Optional**.<br><br>Stock keeping units (SKUs) associated with the product. |
### ProductVariant {#product-variant}
| Element | Description |
| --- | --- |
| `name`<br><br>Type: string | **Required**.<br><br>Name of the product variant. |
| `url`<br><br>Type: string | **Required**.<br><br>Link to the product detail page for the variant on the store's website. |
| `variantIdentifiers`<br><br>Type: [ProductIdentifiers](#product-identifiers) | **Optional**.<br><br>List of all the different identifiers for the variant. |
### Sample Feed {#sample-feed}
```
{
"aggregator": "Meta Reviews",
"store": {
"name": "Facebook Reality Labs",
"id": "4d34ferw3sedfs",
"storeUrls": ["https://portal.facebook.com/", "www.oculus.com"]
},
"reviews": [{
"reviewID": "876324222345",
"rating": 5,
"title": "Amazing Experience!",
"content": "The kids love it. So realistic and I can't wait for more games. Beat Saber is our favorite so far. Definitely worth the price.",
"createdAt": "2020-11-03T10:04:37.000Z",
"updatedAt": "2020-11-03T10:04:37.000Z",
"reviewImageUrls": ["www.oculus.com/reviews/img1.png", "www.oculus.com/reviews/img2.png"],
"incentivized": false,
"hasVerifiedPurchase": true,
"reviewer": {
"name": "John D.",
"reviewerID": "1233413412421",
"isAnonymous": false
},
"secondaryRatings": {
"quality": 5,
"shipping speed": 3,
"value for price": 1
},
"product": {
"name": "Quest 2",
"groupID": "43251",
"url": "https://www.oculus.com/quest-2-128gb/",
"productIdentifiers": {
"gtins": ["20884389103321", "48384389103228"],
"mpn": "AQP10012OZ",
"skus": ["AD-0221-48"],
"brand": "Oculus",
"shopifyProductID": "2345234235423"
},
"variants": [{
"name": "Quest 2 - 256 GB",
"url": "https://www.oculus.com/quest-2-256gb/",
"variantIdentifiers": {
"gtins": ["30884389103328"]
}
}]
}
}]
}
```