About reviews metadata

🚧

Important:

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.

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

Endpoints

Yotpo leverage metadata within the following 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 reviews

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 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 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_properties

These 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.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