# Review

Schemas

Buyers' public reviews of a product, with their star rating, text, photos, the variant bought and whether the purchase was verified.

## Endpoints

2 endpoints return reviews on Amazon and TikTok Shop.

- [GETAmazon Reviews API`/v1/amazon/reviews`](https://socialtap.dev/docs/reference/amazon/reviews/index.md)
- [GETTikTok Shop Reviews API`/v1/tiktokshop/reviews`](https://socialtap.dev/docs/reference/tiktokshop/reviews/index.md)

## Schema

Every endpoint above returns an array of these objects as `data`, with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (tiktokshop, …). |
| `id` | `string` | Platform-native review ID (string). |
| `product_id` | `string` or `null` | ID of the product reviewed (equals product.id); null only for a review of something other than a product. |
| `url` | `string` (uri) or `null` | Permalink, when the platform has one (TikTok Shop reviews have none). |
| `rating` | `integer` or `null` | Star rating, 1 to 5; null when the review gives none. |
| `title` | `string` or `null` | The review's headline; null when it has none. |
| `text` | `string` or `null` | Review body as plain text; null for a rating without text. |
| `language` | `string` or `null` | BCP-47 language of text, when the platform states it. |
| `author` | `object` | The reviewing account, as the platform shows it (some platforms mask the name, e.g. G\*\*a, and show no handle); every field null for an anonymous review. |
| `author.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `author.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `author.display_name` | `string` or `null` | Display name shown on the profile. |
| `author.url` | `string` (uri) or `null` | Canonical profile URL. |
| `author.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `author.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `variant_id` | `string` or `null` | ID of the variant bought: one of the product's variants (TikTok Shop: product.platform_specific.tiktokshop.variants\[\].id). |
| `variant_title` | `string` or `null` | The variant bought, as the platform labels it (Color: Black). |
| `media` | `object[]` | Photos and videos attached to the review; \[\] when none. |
| `media[].type` | `string` | Kind of file. New values may be added; treat unknown values as other.<br>One of `image`, `video`, `audio`, `gif` |
| `media[].url` | `string` (uri) or `null` | Direct file URL; null when the platform withholds it, or when the link would only work from SocialTap's network or with a login. Often signed and expiring: see expires_at. |
| `media[].expires_at` | `string` (date-time) or `null` | When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire. |
| `media[].thumbnail_url` | `string` (uri) or `null` | Poster or preview image URL. |
| `media[].width` | `integer` or `null` | Width in pixels. |
| `media[].height` | `integer` or `null` | Height in pixels. |
| `media[].duration_ms` | `integer` or `null` | Duration in milliseconds (video and audio only). |
| `media[].alt_text` | `string` or `null` | Accessibility text provided by the author or platform. |
| `country_code` | `string` or `null` | ISO 3166-1 alpha-2 country the review was written in, as the platform states it. |
| `is_verified_purchase` | `boolean` or `null` | The platform marks the reviewer as having bought the product through it. |
| `is_incentivized` | `boolean` or `null` | The platform marks the review as written in exchange for a free product or reward. |
| `published_at` | `string` (date-time) or `null` | When the review was posted, RFC 3339 UTC. |
| `metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `metrics.helpful_count` | `integer` or `null` | Readers who marked the review helpful; null when the platform shows no such count. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `approximate_fields` | `string[]` | JSON paths of values rounded by the platform or parsed from display text (a date-only time). \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see a review's photos); null already means unknown for every other field. \[\] when every list is known. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, review endpoints return:

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |
| `private_or_unavailable` | 403 | No | The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. | Only public items can be fetched. Do not retry. |

---

[HTML version](https://socialtap.dev/resources/review/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)