Product schema
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 | Product description. |
seller | string | Yes | Name of the seller. Null where the source names none. |
brand | string | Yes | Brand name (cleaned). Null when the platform exposes a seller instead. |
price.current | number | Yes | Current price, in the price currency. |
price.original | number | Yes | Price before any discount, in the price currency. |
price.currency | string | Yes | Currency code of the price. |
rating.average | number | Yes | Average rating, normally out of 5. |
rating.count | number | Yes | Number of ratings behind the average. |
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 | number | Yes | Number of written reviews. |
features | string[] | Yes | Feature bullet points from the product page. Detail only. |
specifications | object[] | Yes | Specification rows from the product page. Detail only. |
variations | object[] | Yes | Other variants of the product, such as colour or size. Detail only. |
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 | Google Shopping product group id used to chain from search to detail, reviews and sellers. |
ext.data_docid | string | Yes | Google Shopping identifier used to look up the product's detail, reviews and sellers. |
ext.pvf | string | Yes | Google Shopping identifier that goes with gid when looking up the product. |
ext.seller_id | string | Yes | The seller's id on the retailer. |
ext.sold_count | number | Yes | Units sold, as the listing reports it. |
ext.bought_past_month | number | Yes | Lower bound of the purchase badge, for example 10000 for '10K+ bought in past month'. Null when there is no count. |
ext.bought_past_month_label | string | Yes | The purchase badge text exactly as Amazon prints it. |
ext.catalog_id | string | Yes | Walmart's alphanumeric catalog id. product.id holds the numeric id from the URL. |
ext.requested_id | string | Yes | The id you asked for, when the retailer rolled a variant up to its parent. Set only when it differs from product.id. |
ext.rating_distribution.star_1 | number | Yes | Reviews that gave 1 star. |
ext.rating_distribution.star_2 | number | Yes | Reviews that gave 2 stars. |
ext.rating_distribution.star_3 | number | Yes | Reviews that gave 3 stars. |
ext.rating_distribution.star_4 | number | Yes | Reviews that gave 4 stars. |
ext.rating_distribution.star_5 | number | Yes | Reviews that gave 5 stars. |
ext.store_inventory | object[] | Yes | Stock at individual stores or fulfilment points. |
ext.promotion.label | string | Yes | The retailer's own label, for example Clearance or Special Buys. |
ext.promotion.amount_off | number | Yes | Amount off the original price, in the price currency. |
ext.promotion.percent_off | number | Yes | Percentage off the original price. |
ext.price_note | string | Yes | Why the retailer shows no price, for example 'see final price in cart'. |
ext.condition | string | Yes | Condition of a marketplace listing, for example Used or Open Box. |
ext.available_quantity | number | Yes | Units the seller currently has listed. eBay only. |
ext.watchers | number | Yes | People watching the listing. eBay only. |
ext.sold_at | string | Yes | When the listing sold, as a UTC midnight ISO 8601 time. Sold and completed searches only. |
ext.sold_caption | string | Yes | The listing's sold ribbon text, for example 'Sold' with a date. Sold and completed searches only. |
ext.buying_format | string | Yes | Sale type of the listing: auction, buy_it_now or accepts_offers. |
ext.seller_reputation.feedback_percentage | number | Yes | Share of the seller's feedback that is positive, as a percentage. |
ext.seller_reputation.feedback_count | number | Yes | Lifetime number of feedback ratings the seller received. |
ext.seller_reputation.top_rated | boolean | Yes | Whether the marketplace gives the seller its top rated status. |
ext.seller_reputation.items_sold | number | Yes | Items the seller has sold. |
ext.seller_reputation.joined | string | Yes | When the seller joined the marketplace, as the marketplace prints it. |
ext.seller_reputation.url | string | Yes | URL of the seller's page. |
ext.seller_reputation.detailed_ratings.accurate_description | number | Yes | Score for how accurately listings describe the item, up to 5. |
ext.seller_reputation.detailed_ratings.reasonable_shipping_cost | number | Yes | Score for how reasonable shipping costs are, up to 5. |
ext.seller_reputation.detailed_ratings.shipping_speed | number | Yes | Score for shipping speed, up to 5. |
ext.seller_reputation.detailed_ratings.communication | number | Yes | Score for the seller's communication, up to 5. |
ext.g2.product_uuid | string | No | G2's unique id for the product. |
ext.g2.solution_type | string | No | Kind of solution, such as All-in-One. |
ext.g2.ai_verified | boolean | No | True when G2 verified the listing with AI. |
ext.g2.g2_reviews_link | string | No | Link to the product's reviews on G2. |
ext.g2.categories | object[] | No | G2 categories the product is listed in. |
ext.g2.comparisons | object[] | No | Head-to-head comparisons G2 offers. |
ext.g2.alternatives | object[] | No | Alternatives G2 suggests. |
ext.g2.pricing_plans | object[] | No | The product's pricing plans. |
ext.g2.pricing_details.free_trial | boolean | No | True when a free trial exists. |
ext.g2.pricing_details.overview | string | No | G2's summary of the pricing. |
ext.g2.pricing_details.last_updated | string | No | When the pricing was last updated, as text. |
ext.g2.pricing_details.faqs | object[] | No | Pricing questions and answers. |
ext.g2.pricing_details.alternatives_pricing | object[] | No | Pricing of alternative products. |
ext.g2.features | object[] | No | Feature groups. |
ext.g2.detailed_features | object[] | No | Feature groups with a description per feature. |
ext.g2.pros | string[] | No | What reviewers like. |
ext.g2.cons | string[] | No | What reviewers dislike. |
ext.g2.pros_details | object[] | No | What reviewers like, with evidence. |
ext.g2.cons_details | object[] | No | What reviewers dislike, with evidence. |
ext.g2.integrations.count | number | No | How many integrations G2 lists. |
ext.g2.integrations.items | object[] | No | The integrations shown. |
ext.etsy.is_handmade | boolean | No | True when the seller marks the item handmade. |
ext.etsy.favorites | number | No | How many people favourited the item. |
ext.etsy.is_bestseller | boolean | No | True when Etsy marks the item a bestseller. |
ext.etsy.is_top_rated | boolean | No | True when Etsy marks the item top rated. |
ext.etsy.materials | string[] | No | Materials the item is made of. |
ext.etsy.taxonomy_path | string | No | Etsy's category path, dot-separated. |
ext.etsy.when_made | string | No | When the item was made, such as made_to_order. |
ext.etsy.user_id | string | No | The seller's user id. |
ext.sephora.sku | string | No | The SKU. |
ext.sephora.size | string | No | Size or volume, such as 3.3 oz/100 mL. |
ext.sephora.ingredients | string | No | The ingredient list as printed. |
ext.sephora.loves_count | number | No | How many shoppers loved the product. |
ext.hm.color | string | No | The colour name. |
ext.hm.category_code | string | No | H&M's category code. |
ext.hm.sizes | string[] | No | Sizes on offer. |
ext.hm.new_arrival | boolean | No | True when H&M marks the item a new arrival. |
ext.kohls.colors | string[] | No | Colours on offer. |
ext.kohls.display_color | string | No | The colour shown for the item. |
ext.kohls.sku | string | No | The SKU. |
ext.kohls.coupon_eligible | boolean | No | True when store coupons apply. |
ext.kohls.ship | boolean | No | True when the item ships. |
ext.gumtree.user_id | string | No | The seller's user id. |
ext.gumtree.public_user_id | string | No | The seller's public id. |
ext.gumtree.account_id | string | No | The seller's account id. |
ext.gumtree.seller_type | string | No | Kind of seller, such as trade. |
ext.gumtree.category_id | string | No | The category's id. |
ext.gumtree.category | string | No | The category's name. |
ext.gumtree.location | string | No | Where the item is. |
ext.gumtree.location_id | string | No | The location's id. |
ext.sku_id | string | Yes | Colour or size variant id. Shipping quotes need it beside the product id. |
ext.aliexpress.commission_rate | string | No | Affiliate commission rate, such as 7.0%. |
ext.aliexpress.discount | string | No | Discount, such as 49%. |
ext.aliexpress.category | string | No | Top-level category. |
ext.aliexpress.subcategory | string | No | Sub-category. |
ext.aliexpress.positive_rate | string | No | Share of positive feedback, such as 90.8%. |
ext.aliexpress.shop_url | string | No | Link to the seller's shop. |
ext.tiktokshop.category | string | No | The product's category. |
ext.tiktokshop.category_id | string | No | The category's id. |
ext.tiktokshop.discount_percent | number | No | Discount as a percentage. |
ext.tiktokshop.stock | number | No | Units in stock. |
ext.tiktokshop.seller_name | string | No | The seller's name. |
ext.tiktokshop.seller_location | string | No | Where the seller is based. |
ext.tiktokshop.seller_rating | number | No | The seller's rating. |
ext.tiktokshop.seller_products_count | number | No | How many products the seller lists. |
ext.tiktokshop.seller_followers | number | No | The seller's follower count. |
ext.tiktokshop.seller_sold_count | number | No | Units the seller has sold. |
ext.tiktokshop.shop_identity | string | No | Kind of shop, such as official. |
ext.tiktokshop.shop_performance_percentile | number | No | Shop performance percentile, 0 to 100. |
ext.tiktokshop.positive_feedback_percent | number | No | Share of positive feedback, 0 to 100. |
ext.tiktokshop.response_rate_24h | number | No | Share of buyers answered within 24 hours, 0 to 100. |
ext.tiktokshop.free_shipping | boolean | No | True when shipping is free. |
ext.tiktokshop.shipping_fee | number | No | Shipping fee. |
ext.tiktokshop.delivery_estimate | string | No | Estimated delivery window, as text. |
ext.tiktokshop.delivery_days_min | number | No | Fewest days delivery takes. |
ext.tiktokshop.delivery_days_max | number | No | Most days delivery takes. |
ext.tiktokshop.shop_id | string | No | The shop's id. |
ext.tiktokshop.shop_name | string | No | The shop's name. |
ext.tiktokshop.shop_url | string | No | Link to the shop. |
ext.tiktokshop.shop_rating | number | No | The shop's rating. |
ext.tiktokshop.shop_region | string | No | The shop's country code. |
ext.tiktokshop.shop_followers | number | No | The shop's follower count. |
ext.tiktokshop.shop_products_count | number | No | How many products the shop lists. |
ext.tiktokshop.shop_reviews_count | number | No | How many reviews the shop has. |
ext.tiktokshop.shop_sold_count | number | No | Units the shop has sold. |
ext.tiktokshop.shop_videos_count | number | No | How many videos the shop has. |
ext.tiktokshop.shop_logo_url | string | No | Link to the shop's logo. |
ext.tiktokshop.trust_label | string | No | TikTok's trust badge, such as most_loved. |
ext.tiktokshop.promotion_labels | string[] | No | Promotion badges on the product. |
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.
| 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 |
Machine-readable schema
Validate responses programmatically against the JSON Schema (2020-12):
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 · Amazon · eBay · Etsy · G2 · Google Shopping · Gumtree · H&M · Home Depot · Klarna · Kohl's · Sephora · Target · TikTok Shop · Walmart · Wayfair
See how the same fields map to each platform's raw upstream names in the cross-platform field equivalence table.
Comment schema
The unified SocialCrawl comment schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
Review schema
The unified SocialCrawl review schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
