# Product

Schemas

Products and listings for sale, with their price, seller, images, specifications, condition, availability and shipping.

## Endpoints

9 endpoints return products on Amazon, Facebook Marketplace and TikTok Shop.

- [GETAmazon Deals API`/v1/amazon/deal_products`](https://socialtap.dev/docs/reference/amazon/deal_products/index.md)
- [GETAmazon Product API`/v1/amazon/product`](https://socialtap.dev/docs/reference/amazon/product/index.md)
- [GETAmazon Product Search API`/v1/amazon/search_products`](https://socialtap.dev/docs/reference/amazon/search_products/index.md)
- [GETAmazon Best Sellers API`/v1/amazon/top_products`](https://socialtap.dev/docs/reference/amazon/top_products/index.md)
- [GETFacebook Marketplace Listing API`/v1/facebook/listing`](https://socialtap.dev/docs/reference/facebook/listing/index.md)
- [GETFacebook Marketplace Search API`/v1/facebook/search_listings`](https://socialtap.dev/docs/reference/facebook/search_listings/index.md)
- [GETTikTok Shop Product API`/v1/tiktokshop/product`](https://socialtap.dev/docs/reference/tiktokshop/product/index.md)
- [GETTikTok Shop Store Products API`/v1/tiktokshop/products`](https://socialtap.dev/docs/reference/tiktokshop/products/index.md)
- [GETTikTok Shop Search API`/v1/tiktokshop/search_products`](https://socialtap.dev/docs/reference/tiktokshop/search_products/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them 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, facebook, …). |
| `id` | `string` | Platform-native product or listing ID (string). |
| `url` | `string` (uri) | Canonical product page URL. |
| `type` | `string` | product: a catalog product a shop sells in many units, often in variants (TikTok Shop, Instagram and YouTube shopping); listing: a single item a person or business lists for sale (Facebook Marketplace). New values may be added; treat unknown values as product.<br>One of `product`, `listing` |
| `title` | `string` | Product name or listing title, as the seller wrote it. |
| `description` | `string` or `null` | Description as plain text (paragraphs separated by blank lines); null when it has none or the source does not show it (lists and search results). |
| `category` | `string` or `null` | The platform's most specific category label (Bicycles, Vitamins & Supplements), as shown; not normalized across platforms. |
| `category_id` | `string` or `null` | The platform's ID of that category (what its category browsing and filters take). |
| `seller` | `object` or `null` | The shop or account selling it; null only when the source does not show it. |
| `seller.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `seller.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `seller.display_name` | `string` or `null` | Display name shown on the profile. |
| `seller.url` | `string` (uri) or `null` | Canonical profile URL. |
| `seller.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `seller.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `price` | `number` or `null` | Current price in major units of currency (58.47), discounts applied; for a product whose variants cost different amounts, the lowest (the platform's "from" price). Coupons and shipping excluded. 0 = free; null when not shown. |
| `max_price` | `number` or `null` | Highest current variant price, in major units of currency; equal to price when every variant costs the same; null when unknown (a source that shows one price). |
| `original_price` | `number` or `null` | Price before the discount (the struck-through list price), in major units of currency; null when the platform shows no earlier price (not discounted, or not shown). |
| `currency` | `string` or `null` | ISO 4217 code of every amount of this product (USD); null when no amount is shown. |
| `availability` | `string` or `null` | in_stock: can be bought now; out_of_stock: sold out for now (a product can be restocked); pre_order: ships later; pending: a listing with a sale pending; sold: a listing marked sold. Null when the platform does not say. New values may be added; treat unknown values as null.<br>One of `in_stock`, `out_of_stock`, `pre_order`, `pending`, `sold` |
| `condition` | `string` or `null` | Item condition, coarse: new, used (any grade) or refurbished; null when the platform does not say. The platform's own grade is condition_label. New values may be added; treat unknown values as used.<br>One of `new`, `used`, `refurbished` |
| `condition_label` | `string` or `null` | The condition as the platform labels it (Used - Like New, Used - Good, Pre-owned). |
| `thumbnail_url` | `string` (uri) or `null` | Main product image URL. Platform CDN URLs can expire within hours. |
| `media` | `object[]` | Product images in the platform's order (main image first), then any product video; \[\] 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. |
| `attributes` | `object[]` | The product's specifications as name/value pairs, in the platform's order; \[\] when none. |
| `attributes[].name` | `string` | Specification name, as shown (Brand, Material, Condition). |
| `attributes[].value` | `string` | Its value, as shown. |
| `shipping` | `object` | Delivery terms as shown to a buyer in the product's market; each null when not shown. |
| `shipping.is_offered` | `boolean` or `null` | The seller ships it (false: local pickup only). |
| `shipping.fee` | `number` or `null` | Standard shipping fee in major units of the product's currency; 0 = free shipping. |
| `country_code` | `string` or `null` | ISO 3166-1 alpha-2 market the product is offered in; prices, stock and shipping are that market's. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>): TikTok Shop's brand, rating, variants, stock and units sold; Marketplace's location and listing date. Each null when unknown. |
| `platform_specific.amazon` | `object` or `null` | An Amazon product's own fields. |
| `platform_specific.amazon.brand` | `string` or `null` | Brand name, as Amazon shows it; null when it shows none (most books: their authors are contributors). |
| `platform_specific.amazon.contributors` | `object[]` | The people the byline credits (a book's authors, narrators and translators), in Amazon's order; \[\] when the byline names none. |
| `platform_specific.amazon.contributors[].name` | `string` | The contributor's name, as the byline shows it. |
| `platform_specific.amazon.contributors[].role` | `string` or `null` | Their role, as Amazon words it (Author, Narrator, Translator); null when the byline gives none. |
| `platform_specific.amazon.rating` | `number` or `null` | Average customer rating out of 5 (metrics.rating_count ratings behind it), as Amazon shows it, to one decimal; null when unrated. |
| `platform_specific.amazon.metrics` | `object` | Counts at fetch time; null = not shown, 0 = zero. |
| `platform_specific.amazon.metrics.rating_count` | `integer` or `null` | Customer ratings behind rating (with or without a written review), exact. |
| `platform_specific.amazon.metrics.bought_past_month_count` | `integer` or `null` | Units bought in the past month as Amazon's badge rounds them (10K+ is 10000): a lower bound; null when the page shows no badge. |
| `platform_specific.amazon.metrics.offer_count` | `integer` or `null` | Offers from every seller, new and used, as the other sellers box counts them; null when the page shows no such box. |
| `platform_specific.amazon.metrics.rating_distribution` | `object` or `null` | Ratings per star, from the histogram's whole percentages times rating_count (so each can be off by half a percent of rating_count); null when unrated. |
| `platform_specific.amazon.metrics.rating_distribution.one_star_count` | `integer` or `null` | Reviews rating 1 star. |
| `platform_specific.amazon.metrics.rating_distribution.two_star_count` | `integer` or `null` | Reviews rating 2 stars. |
| `platform_specific.amazon.metrics.rating_distribution.three_star_count` | `integer` or `null` | Reviews rating 3 stars. |
| `platform_specific.amazon.metrics.rating_distribution.four_star_count` | `integer` or `null` | Reviews rating 4 stars. |
| `platform_specific.amazon.metrics.rating_distribution.five_star_count` | `integer` or `null` | Reviews rating 5 stars. |
| `platform_specific.amazon.features` | `string[]` | The "About this item" bullet points, in Amazon's order; \[\] when the page has none (books, most media). |
| `platform_specific.amazon.is_sponsored` | `boolean` or `null` | The product is a paid placement among a search's results (Amazon labels it Sponsored); null outside search results. |
| `platform_specific.amazon.categories` | `object[]` | The product's category path, from the department down to category (the last one); \[\] when the page shows none. |
| `platform_specific.amazon.categories[].id` | `string` or `null` | Amazon's browse node ID of the category (what its category pages take as node=); null when the link names none. |
| `platform_specific.amazon.categories[].name` | `string` | Category name, as shown. |
| `platform_specific.amazon.best_sellers_ranks` | `object[]` | The product's sales rank in each category Amazon ranks it in (#49 in Electronics, #7 in Earbud & In-Ear Headphones), department first; \[\] when the page shows none. |
| `platform_specific.amazon.best_sellers_ranks[].rank` | `integer` | The product's sales rank in the category (1 is the best seller). |
| `platform_specific.amazon.best_sellers_ranks[].category` | `string` | Category name, as shown. |
| `platform_specific.amazon.best_sellers_ranks[].category_id` | `string` or `null` | Amazon's ID of the ranking: a browse node ID, or a department's slug (electronics) for a department's rank; null when the row links none. |
| `platform_specific.amazon.rank` | `integer` or `null` | Position in the requested Best Sellers or other ranked list (1 = top); null off a list. |
| `platform_specific.amazon.parent_asin` | `string` or `null` | ASIN of the variation family this product belongs to (every color and size of it shares it); null for a product without variations. |
| `platform_specific.amazon.variants` | `object[]` | Every variation of the product (its colors, sizes, styles), each an ASIN with its options, in Amazon's order; prices and stock are this product's only, so they are null on variants. \[\] for a product without variations. |
| `platform_specific.amazon.variants[].id` | `string` | Platform-native variant (SKU) ID; review.variant_id names it. |
| `platform_specific.amazon.variants[].title` | `string` or `null` | Variant name as shown, else its options joined (Color: Black, Size: M). |
| `platform_specific.amazon.variants[].options` | `object[]` | The option values that make this variant (Color: Black); \[\] for a product's only variant. |
| `platform_specific.amazon.variants[].options[].name` | `string` | Option name, as shown (Color, Size). |
| `platform_specific.amazon.variants[].options[].value` | `string` | The variant's value of it (Black, M). |
| `platform_specific.amazon.variants[].price` | `number` or `null` | Current price of this variant, in major units of the product's currency. |
| `platform_specific.amazon.variants[].original_price` | `number` or `null` | This variant's price before the discount; null when no earlier price is shown. |
| `platform_specific.amazon.variants[].availability` | `string` or `null` | Whether this variant can be bought now; null when not shown. New values may be added; treat unknown values as null.<br>One of `in_stock`, `out_of_stock`, `pre_order` |
| `platform_specific.amazon.variants[].stock_count` | `integer` or `null` | Units in stock as the platform reports them (platforms may cap the number they show); null when hidden. |
| `platform_specific.amazon.variants[].image_url` | `string` (uri) or `null` | Image of this variant (its color swatch or photo). Platform CDN URLs can expire within hours. |
| `platform_specific.amazon.availability_label` | `string` or `null` | The buy box's stock line, as Amazon words it (Only 1 left in stock - order soon.); null when the page shows none. |
| `platform_specific.amazon.ships_from` | `string` or `null` | Who ships the featured offer (Amazon, or the seller), as the buy box says; null when not shown. |
| `platform_specific.amazon.deal` | `object` or `null` | The deal Amazon's deals list shows the product with: its type, badge, end time, share claimed and coupon; null outside a deals list. |
| `platform_specific.amazon.deal.id` | `string` or `null` | Amazon's ID of the deal; null for a product listed for its coupon alone. |
| `platform_specific.amazon.deal.type` | `string` | The kind of deal, as Amazon names it, lowercased: lightning_deal (a limited number of units for a few hours), best_deal (a limited time deal), others as Amazon adds them; coupon when the product is listed for its coupon alone. |
| `platform_specific.amazon.deal.status` | `string` or `null` | The deal's state, as Amazon names it, lowercased (available: it can be bought at the deal price now); null for a coupon alone. |
| `platform_specific.amazon.deal.badge` | `string` or `null` | The deal's badge, as shown (23% off, Up to 40% off); null when it shows none. |
| `platform_specific.amazon.deal.label` | `string` or `null` | The deal's label, as shown (Limited time deal, Early Black Friday Deal, Limited Prime deal); null when the badge shows a countdown instead (see ends_at) or nothing. |
| `platform_specific.amazon.deal.ends_at` | `string` (date-time) or `null` | When the deal ends, RFC 3339 UTC, from the badge's countdown; null when the badge shows none (most deals but lightning deals). |
| `platform_specific.amazon.deal.claimed_percent` | `number` or `null` | Share of the deal's units already claimed, in percent (0 to 100) as Amazon rounds it; null when Amazon shows none (most deals but lightning deals). |
| `platform_specific.amazon.deal.original_price_label` | `string` or `null` | What original_price is: list (the list price), typical (the typical price of the last 90 days), rrp (the recommended retail price) or was (the price before the deal); null when no earlier price is shown or Amazon labels it otherwise. New values may be added; treat unknown values as null.<br>One of `list`, `typical`, `rrp`, `was` |
| `platform_specific.amazon.deal.department_ids` | `string[]` | The browse nodes Amazon's deals list files the deal under, in no particular order (one to several, from a department down to a sub-category): each is a category the Amazon Deals API takes. Empty when it names none. |
| `platform_specific.amazon.deal.coupon_price` | `number` or `null` | The price after the product's clippable coupon, in major units of the product's currency; null when it has no coupon or the coupon shows no price. |
| `platform_specific.amazon.deal.coupon_id` | `string` or `null` | Amazon's ID of the coupon's promotion (its page is amazon.com/promo/\<id>); null when the product has no coupon. |
| `platform_specific.facebook` | `object` or `null` | A Facebook Marketplace listing's own fields. |
| `platform_specific.facebook.location` | `string` or `null` | Where the item is (a city or area, Austin, TX), as Marketplace shows it; null when not shown. |
| `platform_specific.facebook.location_id` | `string` or `null` | Marketplace's ID of the city the item is in: a Marketplace search takes it as its location; null when not shown. |
| `platform_specific.facebook.published_at` | `string` (date-time) or `null` | When it was listed, RFC 3339 UTC; null when not shown. |
| `platform_specific.facebook.is_local_pickup` | `boolean` or `null` | The buyer can pick it up from the seller in person. |
| `platform_specific.facebook.latitude` | `number` or `null` | WGS 84 latitude of the listing's area in degrees (Facebook shows an area, not the seller's address: always listed in approximate_fields); set together with longitude. |
| `platform_specific.facebook.longitude` | `number` or `null` | WGS 84 longitude of the listing's area in degrees (always listed in approximate_fields); set together with latitude. |
| `platform_specific.facebook.delivery_types` | `string[]` | How the item changes hands, as Marketplace lists it: in_person (local pickup), shipping, door_pickup, door_dropoff, public_meetup. \[\] when not shown (listed in unknown_fields). New values may be added. |
| `platform_specific.facebook.is_buy_now_enabled` | `boolean` or `null` | The item can be bought on Facebook with Marketplace checkout (Buy now); false: the buyer arranges payment with the seller. |
| `platform_specific.facebook.seller_rating` | `number` or `null` | The seller's average Marketplace rating as a seller, 1 to 5 stars; null when the seller's ratings are private or there are none. |
| `platform_specific.facebook.seller_rating_count` | `integer` or `null` | Ratings behind seller_rating; null when the seller's ratings are private. |
| `platform_specific.facebook.price_period` | `string` or `null` | The period price pays for: month for a property rental's monthly rent (Marketplace shows $914 / Month); null for a sale price. New values may be added.<br>One of `month` |
| `platform_specific.facebook.postal_code` | `string` or `null` | Postal code of the listing's area, as Marketplace shows it (homes and rentals); null when not shown. |
| `platform_specific.facebook.seller_joined_at` | `string` (date-time) or `null` | When the seller joined Facebook, RFC 3339 UTC; null when not shown. |
| `platform_specific.tiktokshop` | `object` or `null` | A TikTok Shop product's own fields. |
| `platform_specific.tiktokshop.brand` | `string` or `null` | Brand name, as TikTok Shop shows it; null when it shows none. |
| `platform_specific.tiktokshop.rating` | `number` or `null` | Average review score out of 5 (metrics.review_count reviews behind it); null when unrated. |
| `platform_specific.tiktokshop.variants` | `object[]` | The purchasable variants (SKUs: a color, a size, a bundle), in TikTok Shop's order; \[\] for a product without variants (listed in unknown_fields when the source cannot see them). |
| `platform_specific.tiktokshop.variants[].id` | `string` | Platform-native variant (SKU) ID; review.variant_id names it. |
| `platform_specific.tiktokshop.variants[].title` | `string` or `null` | Variant name as shown, else its options joined (Color: Black, Size: M). |
| `platform_specific.tiktokshop.variants[].options` | `object[]` | The option values that make this variant (Color: Black); \[\] for a product's only variant. |
| `platform_specific.tiktokshop.variants[].options[].name` | `string` | Option name, as shown (Color, Size). |
| `platform_specific.tiktokshop.variants[].options[].value` | `string` | The variant's value of it (Black, M). |
| `platform_specific.tiktokshop.variants[].price` | `number` or `null` | Current price of this variant, in major units of the product's currency. |
| `platform_specific.tiktokshop.variants[].original_price` | `number` or `null` | This variant's price before the discount; null when no earlier price is shown. |
| `platform_specific.tiktokshop.variants[].availability` | `string` or `null` | Whether this variant can be bought now; null when not shown. New values may be added; treat unknown values as null.<br>One of `in_stock`, `out_of_stock`, `pre_order` |
| `platform_specific.tiktokshop.variants[].stock_count` | `integer` or `null` | Units in stock as the platform reports them (platforms may cap the number they show); null when hidden. |
| `platform_specific.tiktokshop.variants[].image_url` | `string` (uri) or `null` | Image of this variant (its color swatch or photo). Platform CDN URLs can expire within hours. |
| `platform_specific.tiktokshop.delivery_min_days` | `integer` or `null` | Fewest days TikTok Shop estimates delivery takes in the product's market. |
| `platform_specific.tiktokshop.delivery_max_days` | `integer` or `null` | Most days TikTok Shop estimates delivery takes in the product's market. |
| `platform_specific.tiktokshop.metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `platform_specific.tiktokshop.metrics.sold_count` | `integer` or `null` | Units sold across every market since the product was listed, as TikTok Shop counts them; null when not shown. |
| `platform_specific.tiktokshop.metrics.review_count` | `integer` or `null` | Reviews behind rating. |
| `platform_specific.tiktokshop.metrics.stock_count` | `integer` or `null` | Units in stock across every variant, as TikTok Shop reports them (it may cap the number it shows); null when hidden. |
| `platform_specific.tiktokshop.metrics.rating_distribution` | `object` or `null` | Reviews per star rating; null when TikTok Shop does not show the breakdown. |
| `platform_specific.tiktokshop.metrics.rating_distribution.one_star_count` | `integer` or `null` | Reviews rating 1 star. |
| `platform_specific.tiktokshop.metrics.rating_distribution.two_star_count` | `integer` or `null` | Reviews rating 2 stars. |
| `platform_specific.tiktokshop.metrics.rating_distribution.three_star_count` | `integer` or `null` | Reviews rating 3 stars. |
| `platform_specific.tiktokshop.metrics.rating_distribution.four_star_count` | `integer` or `null` | Reviews rating 4 stars. |
| `platform_specific.tiktokshop.metrics.rating_distribution.five_star_count` | `integer` or `null` | Reviews rating 5 stars. |
| `platform_specific.tiktokshop.shop` | `object` or `null` | The selling shop's rating and counts (seller names the shop); null when the page shows none. |
| `platform_specific.tiktokshop.shop.rating` | `number` or `null` | The shop's average review score out of 5, shown to one decimal; null when the shop is unrated. |
| `platform_specific.tiktokshop.shop.metrics` | `object` | The shop's counts at fetch time; null = not shown, 0 = zero. |
| `platform_specific.tiktokshop.shop.metrics.follower_count` | `integer` or `null` | Accounts following the shop. |
| `platform_specific.tiktokshop.shop.metrics.sold_count` | `integer` or `null` | Units the shop has sold across all its products and markets, as TikTok Shop counts them. |
| `platform_specific.tiktokshop.shop.metrics.product_count` | `integer` or `null` | Products the shop has on sale. |
| `platform_specific.tiktokshop.shop.metrics.review_count` | `integer` or `null` | Reviews of the shop's products, behind its rating. |
| `approximate_fields` | `string[]` | JSON paths of values rounded by the platform or parsed from display text ("10K+ sold"), and of Facebook's coarse listing coordinates. \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a list or search result that does not show attributes or variants); 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, product 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/product/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)