> ## Documentation Index
> Fetch the complete documentation index at: https://developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating Ratings and Reviews

<Warning>
  This feature is in **beta**. This means it might at any time be changed, withdrawn from your account, or become part of a paid add-on module. You might also experience interruptions of this service, degradation of user experience or faulty behavior even in critical processes such as automations and sendouts. Voyado welcomes feedback on beta features, and encourages you to try them, but you should *not* build business critical logic on beta features. Only when a feature reaches its full release can you trust it to function reliably with no further breaking changes.
</Warning>

Your pre-existing review data can be imported into Voyado Customer Engagement as a CSV with semicolon separators like this:

<Accordion title="See example export CSV">
  ```csv theme={null}
  ReviewGroupId;ProductFeedId;ProductGroupId;ProductId;ProductVariantId;Rating;ReviewText;OriginalLocale;UserType;UserDetail;IsVerifiedBuyer;ReviewCreatedOn;ReviewApprovedOn;UpvoteCount;DownvoteCount;MetadataJson;TranslationsJson;Comment;CommentTranslationsJson;CommentCreatedOn;CommentUpvoteCount;CommentDownvoteCount;CommentUserDetail;CommentApprovedOn;CustomDataJson
  107;107-blue-xl;107;107-blue;107-blue-xl;4;Great product, highly recommended!;en-GB;Email;john.doe@example.com;True;01/15/2025 10:30:00 +00:00;01/16/2025 08:00:00 +00:00;3;0;"{""importId"":""abc123"",""contactName"":""John D""}";"{""translations"":[{""locale"":""en-GB"",""text"":""Great product, highly recommended!""},{""locale"":""es-ES"",""text"":""Great product, highly recommended!""},{""locale"":""sv-SE"",""text"":""Utmärkt produkt, rekommenderas varmt!""}]}";Thanks for your review!;"{""translations"":[{""locale"":""es-ES"",""text"":""Thanks for your review!""},{""locale"":""sv-SE"",""text"":""Tack för din recension!""}]}";01/16/2025 08:00:00 +00:00;1;0;Admin User;01/16/2025 08:15:00 +00:00;"{""trueToSize"":{""value"":0.5},""quality"":{""value"":0.8}}"
  124;124-red-l;124;124-red;124-red-l;3;Decent quality but could be improved.;en-GB;ContactId;4a190c10-4603-4dc1-adc6-24ace525c850;False;02/01/2025 14:00:00 +00:00;;0;0;"{""importId"":""abc124""}";"{""translations"":[{""locale"":""en-GB"",""text"":""Decent quality but could be improved.""}]}";We appreciate your feedback!;"{""translations"":[{""locale"":""es-ES"",""text"":""We appreciate your feedback!""}]}";02/02/2025 10:30:00 +00:00;0;0;Support Agent;;
  139;139-green-l;139;139-green;139-green-l;2;Decent, would not buy again.;en-GB;Guest;User Guest 139;True;02/01/2025 14:00:00 +00:00;;0;0;"{""importId"":""abc139""}";"{""translations"":[{""locale"":""en-GB"",""text"":""Decent, would not buy again.""}]}";;;;;;;;
  service;service;service;service;service;4;Great company;en-GB;Email;john.doe@example.com;True;01/15/2025 10:30:00 +00:00;01/16/2025 08:00:00 +00:00;3;0;"{""importId"":""abc382"",""contactName"":""John D""}";"{""translations"":[{""locale"":""en-GB"",""text"":""Great company""},{""locale"":""es-ES"",""text"":""Great company!""},{""locale"":""sv-SE"",""text"":""Utmärkt företag!""}]}";Thanks for your review!;"{""translations"":[{""locale"":""es-ES"",""text"":""Thanks for your review!""},{""locale"":""sv-SE"",""text"":""Tack för din recension!""}]}";01/16/2025 08:00:00 +00:00;1;0;Admin User;01/16/2025 08:15:00 +00:00;
  ```
</Accordion>

## Required fields

These are the compulsory fields in the CSV:

<ResponseField name="ReviewGroupId" type="string" required>
  Used to groups reviews that belong together so they are shown and aggregated as one set.

  In the example CSV this value equals `ProductGroupId`.

  Group: "Product"\
  Example: “107”
</ResponseField>

<ResponseField name="ProductFeedId" type="string" required>
  Identifier of the product feed which the product comes from.

  In the example it equals the `ProductVariantId` value.

  Group: "Product"\
  Example: “107-blue-xl”
</ResponseField>

<ResponseField name="ProductGroupId" type="string" required>
  The parent product shared by all the various colour and size variants. Matches `data-product-group-id` in the widget.

  In the example it equals `ReviewGroupId`.

  Group: "Product"\
  Example: “107”
</ResponseField>

<ResponseField name="ProductId" type="string" required>
  Product within the group. Matches `data-product-id` in the widget.

  Group: "Product"\
  Example: “107-blue”
</ResponseField>

<ResponseField name="ProductVariantId" type="string" required>
  The sellable variant (SKU, size or colour level). Matches `data-variant-id` in the widget.

  Group: "Product"\
  Example: “107-blue-xl”
</ResponseField>

<ResponseField name="Rating" type="integer 1-5" required>
  The star rating (1-5).

  Group: "Review"\
  Example: “4”
</ResponseField>

<ResponseField name="OriginalLocale" type="string" required>
  The language and market the review was written in (as a *BCP 47* language tag string).

  Group: "Review"\
  Example: “en-GB”
</ResponseField>

<ResponseField name="UserType" type="enum" required>
  How the reviewer is identified in `UserDetail`, either:

  * Guest (display name)
  * Email (email address)
  * ContactId (Customer Engagement contact ID)

  Group: "Reviewer"\
  Example: “Email”
</ResponseField>

<ResponseField name="UserDetail" type="string" required>
  The reviewer, interpreted by `UserType` (either display name, email address or contact GUID).

  Group: "Reviewer"\
  Example: “john.doe@​example.com"
</ResponseField>

<ResponseField name="IsVerifiedBuyer" type="boolean" required>
  Whether the reviewer is a confirmed purchaser. Controls the `verified-buyer badge` in the Reviews widget.

  Group: "Reviewer"\
  Example: “True”
</ResponseField>

<ResponseField name="ReviewCreatedOn" type="timestamp (UTC)" required>
  When the review was originally written on the original platform.

  Group: "Review"\
  Example: “01/15/2025 10:30:00 +00:00”
</ResponseField>

<ResponseField name="ReviewApprovedOn" type="timestamp (UTC)" required>
  When the review was approved or published. Migrated reviews should already be approved by the previous provider and are not re-moderated.

  Group: "Review"\
  Example: “01/16/2025 08:00:00 +00:00”
</ResponseField>

## Optional fields

These are the optional fields in the CSV:

<ResponseField name="ReviewText" type="string">
  The review text in its original language.

  Group: "Review"\
  Example: “Great product, highly recommended!”
</ResponseField>

<ResponseField name="UpvoteCount" type="integer ≥ 0">
  Number of "helpful" votes carried over.

  Group: "Review"\
  Example: “3”
</ResponseField>

<ResponseField name="DownvoteCount" type="integer ≥ 0">
  Number of "dislike" votes carried over.

  Group: "Review"\
  Example: “0”
</ResponseField>

<ResponseField name="MetadataJson" type="JSON object">
  Free-form metadata. The samples use `importId` (unique row id for tracing) and `contactName`.

  Group: "Review"\
  Example: “\{"importId":"abc123","contactName":"John D"}”
</ResponseField>

<ResponseField name="TranslationsJson" type="JSON">
  Existing translations of `ReviewText`, with the original locale first. Supplying them avoids the separately priced migration translation.

  Group: "Review"\
  Example: “\{"translations":\[\{"locale":"en-GB","text":"Great product, highly recommended!"},\{"locale":"es-ES","text":"Great product, highly recommended!"},\{"locale":"sv-SE","text":"Utmärkt produkt, rekommenderas varmt!"}]}”
</ResponseField>

<ResponseField name="Comment" type="string">
  The merchant's reply to the review.

  Group: "Reply"\
  Example: “Thanks for your review!”
</ResponseField>

<ResponseField name="CommentTranslationsJson" type="JSON">
  Translations of the reply, same structure as `TranslationsJson`.

  Group: "Reply"\
  Example: “\{"translations":\[\{"locale":"es-ES","text":"Thanks for your review!"},\{"locale":"sv-SE","text":"Tack för din recension!"}]}”
</ResponseField>

<ResponseField name="CommentCreatedOn" type="timestamp (UTC)">
  When the reply was written.

  Group: "Reply"\
  Example: “01/16/2025 08:00:00 +00:00”
</ResponseField>

<ResponseField name="CommentUpvoteCount" type="integer ≥ 0">
  "Helpful" votes on the reply.

  Group: "Reply"\
  Example: “1”
</ResponseField>

<ResponseField name="CommentDownvoteCount" type="integer ≥ 0">
  "Dislike" votes on the reply.

  Group: "Reply"\
  Example: “0”
</ResponseField>

<ResponseField name="CommentUserDetail" type="string">
  Who replied, shown as the author of the reply.

  Group: "Reply"\
  Example: “Admin User”
</ResponseField>

<ResponseField name="CommentApprovedOn" type="timestamp (UTC)">
  When the reply was approved or published.

  Group: "Reply"\
  Example: “01/16/2025 08:15:00 +00:00”
</ResponseField>

<ResponseField name="CustomDataJson" type="JSON">
  Free-form custom attributes. Matches `id` in the widget for custom data.

  Group: "Extension"\
  Example: “\{"size":\{"value":0.5},"quality":\{"value":0.8}}”
</ResponseField>

## Service reviews

A service review is about the *company* rather than a *product*.

In the migration file a service review will have a normal review row, using the same column format as a product reviews. The difference is in the *product references*.

For a service review, the following attributes must all have the literal string value of "service":

* `ReviewGroupId`
* `ProductFeedId`
* `ProductGroupId`
* `ProductId`
* `ProductVariantId`

That's how the import distinguishes a service review from a product review.

You can see a service review in the example CSV above (the last row):

```csv Beginning of service review row theme={null}
service;service;service;service;service;4;... 
```

<Warning>
  Do *not* map service reviews to a real product ID.
</Warning>

### Everything else

The other fields in a service review work as they do for product reviews. That covers rating, text, locale, reviewer (`UserType` and `UserDetail`), verified-buyer flag, dates, votes, translations and merchant replies.

### Approval

Migrated reviews need to be already approved by the previous provider, because moderation is not re-run on them.

### Presentation

In the widgets, service reviews are shown using the same review widgets as product reviews.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.