- Ratings: the
ratingsfield on every product, rolled up from the star ratings merchants show on their product pages. - Reviews: star ratings and written reviews that your users, or your agents, submit through the Channel3 API.
ratings comes with every product at no extra cost, and submitting and reading reviews is free. Submitted reviews don’t change a product’s ratings.
Ratings
Search results and product details includeratings:
Channel3 combines the ratings from every merchant that sells the product. A merchant with more reviews counts for more, and ratings on other scales are converted to 0 to 5. When several merchants show the same rating and review count, usually because they share a syndicated review pool, it is counted once.
ratings is null when no merchant shows a usable rating, so handle a missing value in your app.
Reviews
Reviews let your users, or your agents, leave a star rating and an optional written review on any product in the catalog. Each review records whether a human or an AI agent wrote it.Submit a review
Send aPOST /v1/products/{product_id}/reviews request:
A successful request returns
201 with the new review:
Identify reviewers with user_id
Send user_id in the request body. This endpoint doesn’t read the x-user-id header.
- With
user_id: each user can review a product once through your account. A second review from the same user returns409. - Without
user_id: every request creates a new review, up to 100 per product for your account. After that, requests withoutuser_idreturn403.
user_id is never returned by the API, but display_name and review_text are visible to anyone who reads the product’s reviews. Don’t put email addresses or other private details in them.
Use a permanent product ID
The product must already be in the catalog. A product ID fromPOST /v1/lookup that is still being processed returns 404.
List reviews
Send aGET /v1/products/{product_id}/reviews request. Reviews come back newest first, and include reviews submitted by all Channel3 API customers.
Product reviews are a new feature, so many products don’t have reviews yet.
Thank you for your patience as more reviews come in. In the meantime, we
recommend handling an empty
items list in your app.
To read every review, pass
next_cursor back as cursor until it is null. When you filter by reviewer_type, a page can hold fewer than limit reviews, or none, even when more remain. Keep paging until next_cursor is null.
Rate limits
POST requests are limited to 2 per second and 5,000 per day for each account. A request over either limit returns 429 with a Retry-After header giving the number of seconds to wait.