About reviews metadata

🚧

Important:

You can display metadata regardless of the eCommerce platform you are using. However, metadata filtering is currently available exclusively to merchants using non-hosted custom or generic eCommerce platforms. Please contact your Yotpo representative if you'd like to start leveraging orders metadata in reviews.

Review-related metadata takes 6 hours to appear in Yotpo Reviews and on-site.

Leverage metadata collected upon order creation to allow shoppers to filter reviews according to customer, order, and/or product-related fields such as membership type, location, delivery type, order history, and more!

Using Yotpo's new order creation schema, you can configure predefined or custom properties to collect and leverage as filters right in your reviews widget. You can also choose whether to reflect this data in-line within each review. Learn more

Widget pre-sorting

Pre-sorting your widget allows you to surface certain reviews based on your sorting criteria. The widget will load in a pre-sorted state according to the metadata parameters defined upon order creation.

To pre-sort your Reviews Widget according to metadata params, add the snippet below to your Reviews Widget snippet:

data-presorting='[
{"type": "customer_property", "key": "state", "value": "New York"},
{"type": "customer_custom_property", "key": "age", "value": 22},
{"type": "customer_custom_property", "key": "still_alive", "value": true}
]'

Widget pre-filtering

Pre-filtering your widget allows you to display only certain reviews based on your filtering criteria. The widget will load in a pre-sorted state according to the metadata parameters defined upon order creation.

To pre-filter your Reviews Widget according to metadata params, add the snippet below to your Reviews Widget:

data-prefilter='{
"order_properties":{"year":["2017"]},
"customer_properties":{"state": ["New York"]},
"customer_custom_properties":null}'

Pre-sorted, pre-filtered widget

The snippet below reflects the Yotpo Reviews Widget with pre-filtered and pre-sorted fields:

<div class="yotpo yotpo-main-widget"
data-product-id="{{ product.id }}"
data-name="{{ product.title | escape }}"
data-url="{{ shop.url }}{{ product.url }}"
data-image-url="{{ product.featured_image | product_img_url: "large" |replace: '?', '%3F' | replace: '&','%26'}}"
data-description="{{ product.description | escape }}"
data-prefilter='{"order_properties":{"year":["2017"]},"customer_properties":{"state": ["New York"]},"customer_custom_properties":null}'
data-presorting='[{"type": "customer_property", "key": "state", "value": "New York"},{"type": "customer_property", "key": "age", "value": 22},{"type": "customer_property", "key": "still_alive", "value": true}]'>
</div>

👍

Additional metadata fields are available!

You can include product properties such as color, size, and material, order properties such as delivery type, or customer properties such as country, address, and phone number.

Reviews metadata endpoints

EndpointDescription
Create an order within the Yotpo systemUse this endpoint to create orders within the Yotpo system. For metadata fields and properties, see the Create Order + Order Metadata body sample.
Create reviewUse this endpoint to asynchronously create reviews in the Yotpo system. For metadata fields and properties, see the Create Review + Metadata body sample.
Add metadata to an existing reviewUse this endpoint to add metadata to an existing review. The review_id can be retrieved using the Retrieve All Reviews endpoint.
Get review metadataUse this endpoint to retrieve a review's order, customer, and product metadata by review_id. The review_id can be retrieved using the Retrieve All Reviews endpoint.
Update existing review metadataUse this endpoint to update or remove metadata associated with an existing review. The review_id can be retrieved using the Retrieve All Reviews endpoint.
Retrieve review filters and valuesIf you're collecting orders metadata properties, this call can be used to retrieve all possible filter-types, and their corresponding values, for a specific product.

For example, hair_type and straight,curly,short,damaged, etc.

Important: In order to retrieve filters and values, the product (domain_key) defined must have at least one review published to the Reviews Widget.

Metadata properties

📘

Tip:

The predefined and custom metadata properties below can be leveraged to pre-sort and/or pre-filter your Reviews Widget according to the properties you configure. Learn more

PropertiesDescription
Predefined PropertiesYotpo supports several predefined fields on products, orders, and customers:

- product_properties: Color, Size, Vendor, Material, Model, Coupon Used
- order_properties: Coupon Used, Delivery type
- customer_properties: State, Country, Address, Phone Number

These fields are all optional.

Note: You can use order_properties only for reviews that have the order_id attached to them. If there is no order_id, you can use only custom_order_properties.
Custom PropertiesCustom properties can be included in orders and retrieved as part of reviews.

There are three types of custom fields:
- custom_product_properties
- custom_customer_properties
- custom_order_properties

These fields are all optional.
Validations & ErrorsField names are not case sensitive and can contain numbers & symbols.
Two fields cannot have the same name.
There’s a limit of 10 custom fields per type (order/customer/product).
GeneralFields are case sensitive everywhere they’re configured.

🚧

Country codes for customer.country param:

To comply with Google Seller Ratings conventions, the customer.country param requires
two-letter uppercase country code values from this list of compatible codes. Default country code: US