# Product schema (/docs/schema/product)

The unified SocialCrawl product schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.

Every SocialCrawl endpoint that returns a product gives you this exact shape, whatever the source platform. Write your parser once and the same code reads product data from every platform below. That is the unified schema: one contract instead of a dozen raw upstream formats.

## Field reference

| Field | Type | Nullable | Description |
| ----- | ---- | -------- | ----------- |
| `id` | `string` | No | Platform product ID (Amazon ASIN / Google Shopping product id) |
| `url` | `string` | Yes | Direct URL to the product page |
| `title` | `string` | Yes | Product title |
| `description` | `string` | Yes |  |
| `seller` | `string` | Yes |  |
| `brand` | `string` | Yes | Brand name (cleaned). Null when the platform exposes a seller instead. |
| `price.current` | `integer` | Yes |  |
| `price.original` | `integer` | Yes |  |
| `price.currency` | `string` | Yes |  |
| `rating.average` | `integer` | Yes |  |
| `rating.count` | `integer` | Yes |  |
| `image_urls` | `string` or `string[]` | Yes | Primary image URL, or an array of image URLs for products with a gallery. |
| `availability` | `string` | Yes | Stock/availability string when surfaced |
| `reviews_count` | `integer` | Yes |  |
| `features` | `string[]` | Yes |  |
| `specifications` | `object[]` | Yes |  |
| `variations` | `object[]` | Yes |  |

## Extension fields (`ext`)

Platform-specific passthrough. Each field is present only on the platforms that expose it and is absent everywhere else, so treat every `ext.*` field as optional. These carry the richer, per-platform signals the unified leaves cannot hold, and the join keys that chain endpoints together.

| Field | Type | Nullable | Description |
| ----- | ---- | -------- | ----------- |
| `ext.gid` | `string` | Yes |  |
| `ext.data_docid` | `string` | Yes |  |
| `ext.pvf` | `string` | Yes |  |
| `ext.seller_id` | `string` | Yes |  |
| `ext.sold_count` | `integer` | Yes |  |
| `ext.bought_past_month` | `integer` | Yes |  |
| `ext.bought_past_month_label` | `string` | Yes |  |
| `ext.catalog_id` | `string` | Yes |  |
| `ext.requested_id` | `string` | Yes |  |
| `ext.rating_distribution.star_1` | `integer` | Yes |  |
| `ext.rating_distribution.star_2` | `integer` | Yes |  |
| `ext.rating_distribution.star_3` | `integer` | Yes |  |
| `ext.rating_distribution.star_4` | `integer` | Yes |  |
| `ext.rating_distribution.star_5` | `integer` | Yes |  |
| `ext.store_inventory` | `object[]` | Yes |  |
| `ext.promotion.label` | `string` | Yes |  |
| `ext.promotion.amount_off` | `integer` | Yes |  |
| `ext.promotion.percent_off` | `integer` | Yes |  |
| `ext.price_note` | `string` | Yes |  |
| `ext.condition` | `string` | Yes |  |
| `ext.available_quantity` | `integer` | Yes |  |
| `ext.watchers` | `integer` | Yes |  |
| `ext.sold_at` | `string` | Yes |  |
| `ext.sold_caption` | `string` | Yes |  |
| `ext.buying_format` | `string` | Yes |  |
| `ext.seller_reputation.feedback_percentage` | `integer` | Yes |  |
| `ext.seller_reputation.feedback_count` | `integer` | Yes |  |
| `ext.seller_reputation.top_rated` | `boolean` | Yes |  |
| `ext.seller_reputation.items_sold` | `integer` | Yes |  |
| `ext.seller_reputation.joined` | `string` | Yes |  |
| `ext.seller_reputation.url` | `string` | Yes |  |
| `ext.seller_reputation.detailed_ratings.accurate_description` | `integer` | Yes |  |
| `ext.seller_reputation.detailed_ratings.reasonable_shipping_cost` | `integer` | Yes |  |
| `ext.seller_reputation.detailed_ratings.shipping_speed` | `integer` | Yes |  |
| `ext.seller_reputation.detailed_ratings.communication` | `integer` | Yes |  |
| `ext.g2` | `string` | Yes |  |
| `ext.etsy` | `string` | Yes |  |
| `ext.sephora` | `string` | Yes |  |
| `ext.hm` | `string` | Yes |  |
| `ext.kohls` | `string` | Yes |  |
| `ext.gumtree` | `string` | Yes |  |
| `ext.sku_id` | `string` | Yes |  |
| `ext.aliexpress` | `string` | Yes |  |
| `ext.tiktokshop` | `string` | Yes |  |
## Platform availability

16 platforms return the `Product` shape. `id` are never null on any platform. The fields below vary: **yes** means the platform populates it (the value may still be null); a blank means the platform never provides it, so it is always null.

<div className="overflow-x-auto">

| Platform | `image_urls` | `reviews_count` | `seller` | `price.currency` | `price.original` | `brand` | `description` | `price.current` | `rating.average` | `rating.count` | `availability` | `features` |
| -------- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| AliExpress |  |  | yes | yes | yes |  |  | yes |  |  |  |  |
| Amazon | yes |  |  | yes | yes | yes | yes | yes | yes | yes |  |  |
| eBay |  | yes | yes | yes | yes | yes | yes | yes | yes | yes |  |  |
| Etsy | yes | yes | yes | yes | yes |  | yes | yes | yes | yes |  |  |
| G2 | yes | yes | yes |  |  | yes | yes |  | yes | yes |  |  |
| Google Shopping |  | yes | yes | yes | yes | yes | yes | yes | yes | yes |  |  |
| Gumtree | yes |  | yes | yes |  |  | yes | yes |  |  |  |  |
| H&M |  |  |  |  |  | yes |  |  |  |  |  |  |
| Home Depot |  | yes |  |  | yes | yes | yes | yes | yes | yes |  | yes |
| Klarna |  | yes | yes | yes |  | yes | yes | yes | yes | yes | yes |  |
| Kohl's |  |  |  |  |  |  |  |  | yes | yes |  |  |
| Sephora |  |  |  |  |  | yes | yes | yes | yes | yes |  |  |
| Target |  | yes |  |  | yes | yes | yes | yes | yes | yes |  |  |
| TikTok Shop | yes | yes | yes | yes | yes |  | yes | yes | yes | yes |  |  |
| Walmart | yes |  | yes | yes | yes | yes | yes | yes | yes | yes | yes |  |
| Wayfair | yes | yes |  | yes | yes | yes | yes | yes | yes | yes |  | yes |

</div>

## Machine-readable schema

Validate responses programmatically against the JSON Schema (2020-12):

[`/schemas/product.json`](/schemas/product.json)

Point a validator (Ajv, `jsonschema`, or your framework's) at that URL, or hand it to an agent so it can check the shape without a live call.

## Returned by

Endpoints with the `Product` / `ProductList` archetype return this shape:

[AliExpress](/platforms/aliexpress) · [Amazon](/platforms/amazon) · [eBay](/platforms/ebay) · [Etsy](/platforms/etsy) · [G2](/platforms/g2) · [Google Shopping](/platforms/google_shopping) · [Gumtree](/platforms/gumtree) · [H&M](/platforms/hm) · [Home Depot](/platforms/home_depot) · [Klarna](/platforms/klarna) · [Kohl's](/platforms/kohls) · [Sephora](/platforms/sephora) · [Target](/platforms/target) · [TikTok Shop](/platforms/tiktokshop) · [Walmart](/platforms/walmart) · [Wayfair](/platforms/wayfair)

See how the same fields map to each platform's raw upstream names in the [cross-platform field equivalence table](/docs/schema/field-equivalence.md).