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
| Endpoint | Description |
|---|---|
| Create an order within the Yotpo system | Use this endpoint to create orders within the Yotpo system. For metadata fields and properties, see the Create Order + Order Metadata body sample. |
| Create review | Use 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 review | Use this endpoint to add metadata to an existing review. The review_id can be retrieved using the Retrieve All Reviews endpoint. |
| Get review metadata | Use 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 metadata | Use 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 values | If 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
| Properties | Description |
|---|---|
| Predefined Properties | Yotpo 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 NumberThese 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 Properties | Custom 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_propertiesThese fields are all optional. |
| Validations & Errors | Field 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). |
| General | Fields are case sensitive everywhere they’re configured. |
Country codes for
customer.countryparam:To comply with Google Seller Ratings conventions, the
customer.countryparam requires
two-letter uppercase country code values from this list of compatible codes. Default country code:US