Product API: one schema on 3 platforms

Endpoints

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

Schema

Single-item endpoints return this object as data; list endpoints return an array of them as data with a page object. The standard meta comes with every response.

platformstring

Platform ID (tiktokshop, facebook, …).

idstring

Platform-native product or listing ID (string).

urlstring uri

Canonical product page URL.

typestring

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.

One ofproductlisting

titlestring

Product name or listing title, as the seller wrote it.

descriptionstringnullable

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).

categorystringnullable

The platform's most specific category label (Bicycles, Vitamins & Supplements), as shown; not normalized across platforms.

category_idstringnullable

The platform's ID of that category (what its category browsing and filters take).

sellerobjectnullable

The shop or account selling it; null only when the source does not show it.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

pricenumbernullable

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_pricenumbernullable

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_pricenumbernullable

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).

currencystringnullable

ISO 4217 code of every amount of this product (USD); null when no amount is shown.

availabilitystringnullable

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.

One ofin_stockout_of_stockpre_orderpendingsold

conditionstringnullable

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.

One ofnewusedrefurbished

condition_labelstringnullable

The condition as the platform labels it (Used - Like New, Used - Good, Pre-owned).

thumbnail_urlstring urinullable

Main product image URL. Platform CDN URLs can expire within hours.

mediaobject[]

Product images in the platform's order (main image first), then any product video; [] when none.

Show 8 child fields

typestring

Kind of file. New values may be added; treat unknown values as other.

One ofimagevideoaudiogif

urlstring urinullable

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.

expires_atstring date-timenullable

When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire.

thumbnail_urlstring urinullable

Poster or preview image URL.

widthintegernullable

Width in pixels.

heightintegernullable

Height in pixels.

duration_msintegernullable

Duration in milliseconds (video and audio only).

alt_textstringnullable

Accessibility text provided by the author or platform.

attributesobject[]

The product's specifications as name/value pairs, in the platform's order; [] when none.

Show 2 child fields

namestring

Specification name, as shown (Brand, Material, Condition).

valuestring

Its value, as shown.

shippingobject

Delivery terms as shown to a buyer in the product's market; each null when not shown.

Show 2 child fields

is_offeredbooleannullable

The seller ships it (false: local pickup only).

feenumbernullable

Standard shipping fee in major units of the product's currency; 0 = free shipping.

country_codestringnullable

ISO 3166-1 alpha-2 market the product is offered in; prices, stock and shipping are that market's.

platform_specificobject

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.

Show 3 child fields

amazonobjectnullable

An Amazon product's own fields.

Show 14 child fields

brandstringnullable

Brand name, as Amazon shows it; null when it shows none (most books: their authors are contributors).

contributorsobject[]

The people the byline credits (a book's authors, narrators and translators), in Amazon's order; [] when the byline names none.

Show 2 child fields

namestring

The contributor's name, as the byline shows it.

rolestringnullable

Their role, as Amazon words it (Author, Narrator, Translator); null when the byline gives none.

ratingnumbernullable

Average customer rating out of 5 (metrics.rating_count ratings behind it), as Amazon shows it, to one decimal; null when unrated.

metricsobject

Counts at fetch time; null = not shown, 0 = zero.

Show 4 child fields

rating_countintegernullable

Customer ratings behind rating (with or without a written review), exact.

bought_past_month_countintegernullable

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.

offer_countintegernullable

Offers from every seller, new and used, as the other sellers box counts them; null when the page shows no such box.

rating_distributionobjectnullable

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.

Show 5 child fields

one_star_countintegernullable

Reviews rating 1 star.

two_star_countintegernullable

Reviews rating 2 stars.

three_star_countintegernullable

Reviews rating 3 stars.

four_star_countintegernullable

Reviews rating 4 stars.

five_star_countintegernullable

Reviews rating 5 stars.

featuresstring[]

The "About this item" bullet points, in Amazon's order; [] when the page has none (books, most media).

is_sponsoredbooleannullable

The product is a paid placement among a search's results (Amazon labels it Sponsored); null outside search results.

categoriesobject[]

The product's category path, from the department down to category (the last one); [] when the page shows none.

Show 2 child fields

idstringnullable

Amazon's browse node ID of the category (what its category pages take as node=); null when the link names none.

namestring

Category name, as shown.

best_sellers_ranksobject[]

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.

Show 3 child fields

rankinteger

The product's sales rank in the category (1 is the best seller).

categorystring

Category name, as shown.

category_idstringnullable

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.

rankintegernullable

Position in the requested Best Sellers or other ranked list (1 = top); null off a list.

parent_asinstringnullable

ASIN of the variation family this product belongs to (every color and size of it shares it); null for a product without variations.

variantsobject[]

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.

Show 8 child fields

idstring

Platform-native variant (SKU) ID; review.variant_id names it.

titlestringnullable

Variant name as shown, else its options joined (Color: Black, Size: M).

optionsobject[]

The option values that make this variant (Color: Black); [] for a product's only variant.

Show 2 child fields

namestring

Option name, as shown (Color, Size).

valuestring

The variant's value of it (Black, M).

pricenumbernullable

Current price of this variant, in major units of the product's currency.

original_pricenumbernullable

This variant's price before the discount; null when no earlier price is shown.

availabilitystringnullable

Whether this variant can be bought now; null when not shown. New values may be added; treat unknown values as null.

One ofin_stockout_of_stockpre_order

stock_countintegernullable

Units in stock as the platform reports them (platforms may cap the number they show); null when hidden.

image_urlstring urinullable

Image of this variant (its color swatch or photo). Platform CDN URLs can expire within hours.

availability_labelstringnullable

The buy box's stock line, as Amazon words it (Only 1 left in stock - order soon.); null when the page shows none.

ships_fromstringnullable

Who ships the featured offer (Amazon, or the seller), as the buy box says; null when not shown.

dealobjectnullable

The deal Amazon's deals list shows the product with: its type, badge, end time, share claimed and coupon; null outside a deals list.

Show 11 child fields

idstringnullable

Amazon's ID of the deal; null for a product listed for its coupon alone.

typestring

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.

statusstringnullable

The deal's state, as Amazon names it, lowercased (available: it can be bought at the deal price now); null for a coupon alone.

badgestringnullable

The deal's badge, as shown (23% off, Up to 40% off); null when it shows none.

labelstringnullable

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.

ends_atstring date-timenullable

When the deal ends, RFC 3339 UTC, from the badge's countdown; null when the badge shows none (most deals but lightning deals).

claimed_percentnumbernullable

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).

original_price_labelstringnullable

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.

One oflisttypicalrrpwas

department_idsstring[]

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.

coupon_pricenumbernullable

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.

coupon_idstringnullable

Amazon's ID of the coupon's promotion (its page is amazon.com/promo/<id>); null when the product has no coupon.

facebookobjectnullable

A Facebook Marketplace listing's own fields.

Show 13 child fields

locationstringnullable

Where the item is (a city or area, Austin, TX), as Marketplace shows it; null when not shown.

location_idstringnullable

Marketplace's ID of the city the item is in: a Marketplace search takes it as its location; null when not shown.

published_atstring date-timenullable

When it was listed, RFC 3339 UTC; null when not shown.

is_local_pickupbooleannullable

The buyer can pick it up from the seller in person.

latitudenumbernullable

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.

longitudenumbernullable

WGS 84 longitude of the listing's area in degrees (always listed in approximate_fields); set together with latitude.

delivery_typesstring[]

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.

is_buy_now_enabledbooleannullable

The item can be bought on Facebook with Marketplace checkout (Buy now); false: the buyer arranges payment with the seller.

seller_ratingnumbernullable

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.

seller_rating_countintegernullable

Ratings behind seller_rating; null when the seller's ratings are private.

price_periodstringnullable

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.

One ofmonth

postal_codestringnullable

Postal code of the listing's area, as Marketplace shows it (homes and rentals); null when not shown.

seller_joined_atstring date-timenullable

When the seller joined Facebook, RFC 3339 UTC; null when not shown.

tiktokshopobjectnullable

A TikTok Shop product's own fields.

Show 7 child fields

brandstringnullable

Brand name, as TikTok Shop shows it; null when it shows none.

ratingnumbernullable

Average review score out of 5 (metrics.review_count reviews behind it); null when unrated.

variantsobject[]

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).

Show 8 child fields

idstring

Platform-native variant (SKU) ID; review.variant_id names it.

titlestringnullable

Variant name as shown, else its options joined (Color: Black, Size: M).

optionsobject[]

The option values that make this variant (Color: Black); [] for a product's only variant.

Show 2 child fields

namestring

Option name, as shown (Color, Size).

valuestring

The variant's value of it (Black, M).

pricenumbernullable

Current price of this variant, in major units of the product's currency.

original_pricenumbernullable

This variant's price before the discount; null when no earlier price is shown.

availabilitystringnullable

Whether this variant can be bought now; null when not shown. New values may be added; treat unknown values as null.

One ofin_stockout_of_stockpre_order

stock_countintegernullable

Units in stock as the platform reports them (platforms may cap the number they show); null when hidden.

image_urlstring urinullable

Image of this variant (its color swatch or photo). Platform CDN URLs can expire within hours.

delivery_min_daysintegernullable

Fewest days TikTok Shop estimates delivery takes in the product's market.

delivery_max_daysintegernullable

Most days TikTok Shop estimates delivery takes in the product's market.

metricsobject

Counts at fetch time; null = hidden or not exposed, 0 = zero.

Show 4 child fields

sold_countintegernullable

Units sold across every market since the product was listed, as TikTok Shop counts them; null when not shown.

review_countintegernullable

Reviews behind rating.

stock_countintegernullable

Units in stock across every variant, as TikTok Shop reports them (it may cap the number it shows); null when hidden.

rating_distributionobjectnullable

Reviews per star rating; null when TikTok Shop does not show the breakdown.

Show 5 child fields

one_star_countintegernullable

Reviews rating 1 star.

two_star_countintegernullable

Reviews rating 2 stars.

three_star_countintegernullable

Reviews rating 3 stars.

four_star_countintegernullable

Reviews rating 4 stars.

five_star_countintegernullable

Reviews rating 5 stars.

shopobjectnullable

The selling shop's rating and counts (seller names the shop); null when the page shows none.

Show 2 child fields

ratingnumbernullable

The shop's average review score out of 5, shown to one decimal; null when the shop is unrated.

metricsobject

The shop's counts at fetch time; null = not shown, 0 = zero.

Show 4 child fields

follower_countintegernullable

Accounts following the shop.

sold_countintegernullable

Units the shop has sold across all its products and markets, as TikTok Shop counts them.

product_countintegernullable

Products the shop has on sale.

review_countintegernullable

Reviews of the shop's products, behind its rating.

approximate_fieldsstring[]

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_fieldsstring[]

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 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.