Skip to content

Import reviews in bulk

POST
/stores/{storeRef}/reviews/bulk-import
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/reviews/bulk-import \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "reviews": [ { "product_external_id": "example", "variant_name": "example", "external_review_id": "example", "rating": 1, "content": "example", "reviewer_name": "example", "reviewer_avatar": "example", "images": [ "example" ], "helpful": 1, "created_at": "example" } ], "options": { "auto_approve": true, "skip_duplicates": true, "update_duplicates": false, "update_stats": true } }'

Imports up to 500 reviews collected from another platform. Each review is matched to a product by product_external_id; reviews whose product is not found are skipped. Reviews already imported, recognised by external_review_id, are skipped; options.update_duplicates does not update them yet and only skips them too. Setting options.skip_duplicates to false without it imports them again as new reviews. Imported reviews are approved unless options.auto_approve is false, are never marked as verified buyers, and product rating statistics are recalculated unless options.update_stats is false. The response counts what happened to each review; a 201 does not mean every review was imported.

Required scopes: write:reviews

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typeapplication/json
object
reviews
required

The reviews to import, from 1 to 500.

Array<object>
object
product_external_id
required

External ID of the product the review belongs to, matched against the product’s external ID. Reviews with no matching product are skipped.

string
variant_name

Name of the variant the review is about.

string
external_review_id
required

The review’s ID on the source platform, used to detect duplicates.

string
rating
required

Star rating, 1 to 5.

number
>= 1 <= 5
content
required

Review text.

string
reviewer_name
required

Reviewer’s display name.

string
reviewer_avatar

URL of the reviewer’s avatar.

string
images

URLs of images attached to the review.

Array<string>
helpful

How many people found the review helpful on the source platform. It is kept in the review’s moderation notes.

number
created_at

The review’s original date, as an ISO 8601 timestamp. An unparseable value is ignored with a warning.

string
options

Options for this import.

object
auto_approve

Approve imported reviews straight away. When false they are imported as PENDING.

boolean
default: true
skip_duplicates

Skip reviews whose external_review_id was already imported. When false they are imported again as new reviews.

boolean
default: true
update_duplicates

Not implemented yet: duplicates are skipped, not updated.

boolean
update_stats

Recalculate product rating statistics after the import.

boolean
default: true
Media typeapplication/json
object
success
required

Number of reviews imported.

number
failed
required

Number of reviews that could not be imported.

number
skipped
required

Number of reviews skipped, as duplicates or because their product was not found.

number
errors
required

One message for each review that failed.

Array<string>
warnings
required

Notes about reviews that were imported or skipped with a caveat.

Array<string>

Example generated

{
"success": 1,
"failed": 1,
"skipped": 1,
"errors": [
"example"
],
"warnings": [
"example"
]
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}