Skip to content

Submit a review for an invitation

POST
/public/stores/{storeRef}/review-invitations/{token}/submit
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/public/stores/example/review-invitations/example/submit \
--header 'Content-Type: application/json' \
--header 'x-storefront-api-key: <x-storefront-api-key>' \
--data '{ "rating": 1, "content": "example", "title": "example", "pros": [ "example" ], "cons": [ "example" ], "media": [ {} ] }'

Creates a verified-buyer review for the product the invitation is for and marks the invitation as submitted. The review waits for the merchant’s approval before it is shown. An invitation that is unknown, expired or already used answers 400. The response currently includes merchant-side fields of the review, such as reviewer_email and the moderation fields.

token
required
string

The invitation token, sent to the customer by email.

storeRef
required
string

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

Media typeapplication/json
object
rating
required

Star rating, from 1 to 5.

number
>= 1 <= 5
content
required

Review text, at least 10 characters.

string
>= 10 characters
title

Review title.

string
pros

What the reviewer liked.

Array<string>
cons

What the reviewer disliked.

Array<string>
media

Photos or other media: a list of objects such as { "url": "https://...", "type": "image" }.

Array<object>
object

Example generated

{
"rating": 1,
"content": "example",
"title": "example",
"pros": [
"example"
],
"cons": [
"example"
],
"media": [
{}
]
}
Media typeapplication/json
object
variant_id

ID of the reviewed variant, or null.

number
nullable
variant_name

Name of the reviewed variant, or null.

string
nullable
order_id

ID of the order the review is about, or null.

number
nullable
order_number

Number of the order the review is about, or null.

number
nullable
user_id

ID of the customer account that wrote the review, or null.

string
nullable
reviewer_avatar

URL of the reviewer’s avatar, or null.

string
nullable
title

Review title, or null.

string
nullable
media
required

Photos or other media attached to the review: a list of objects such as { "url": "https://...", "type": "image" }.

Array<object>
object
key
additional properties
any
status
required

Moderation status: PENDING, APPROVED, REJECTED or HIDDEN. Only APPROVED reviews are shown to shoppers.

string
Allowed values: PENDING APPROVED REJECTED HIDDEN
moderation_notes

Internal moderation notes, or null.

string
nullable
approved_by

ID of the user who approved the review, or null.

string
nullable
approved_at

When the review was approved, as an ISO 8601 timestamp, or null.

string
nullable
rejected_reason

Why the review was rejected, or null.

string
nullable
display_order

Position used when sorting by display_order, or null.

number
nullable
external_review_id

The review’s ID on the platform it was imported from, or null.

string
nullable
review_date

The date shown for the review, as an ISO 8601 timestamp, or null. Imported reviews keep their original date here.

string
nullable
deleted_at

When the review was deleted. Always null on reviews you can read.

string
nullable
review_replies

The review’s replies. Present only when replies are requested with include_replies on the list route.

Array<object>
object
deleted_at

When the reply was deleted. Always null on replies you can read.

string
nullable
id
required

Reply ID.

string
review_id
required

ID of the review the reply answers.

string
content
required

Reply text.

string
author_id
required

ID of the user who wrote the reply.

string
author_name
required

Name shown as the reply’s author.

string
is_visible
required

Whether the reply is shown to shoppers.

boolean
created_at
required

When the reply was created, as an ISO 8601 timestamp.

string
updated_at
required

When the reply was last updated, as an ISO 8601 timestamp.

string
id
required

Review ID.

string
product_id
required

ID of the reviewed product.

number
product_name
required

Name of the reviewed product when the review was written.

string
reviewer_name
required

Reviewer’s name.

string
reviewer_email
required

Reviewer’s email.

string
is_verified_buyer
required

Whether the reviewer bought the product from the store.

boolean
rating
required

Star rating, 1 to 5.

number
content
required

Review text.

string
pros
required

What the reviewer liked.

Array<string>
cons
required

What the reviewer disliked.

Array<string>
is_featured
required

Whether the review is featured.

boolean
is_pinned
required

Whether the review is pinned to the top of the list.

boolean
created_at
required

When the review was created, as an ISO 8601 timestamp.

string
updated_at
required

When the review was last updated, as an ISO 8601 timestamp.

string

Example

{
"status": "PENDING"
}

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"
}