Listing

commerce.listingUnifiedSoon

One product page on one marketplace: what it costs, how it ranks, what buyers say and how much it sells, with the shop and company behind it.

11 marketplaces5 planned calls53 fieldskey marketplace + listing IDAmazon and TikTok Shop first

Where Listing sits

ProductThe same item on every marketplace
linked, with a confidence score
ListingOne page on one marketplaceholds Variant and Offer
sold by
ShopA seller account on that marketplace
run by
OrganizationThe company, also the brand owner or supplier
  • sold under Brand
  • filed in Category
  • ranks for Keyword
  • featured in a Video or LiveStream by a Creator
  • may touch an IPRight
  • shop named in a Case

5 calls plannedSoon

Calls from commerce API design 0.1.0-draft, written as REST paths. Each call returns this entity in one shape on the platforms it lists, and none is deployed yet.

  • GET/v1/e-commerce/listings/{listingId}One listing with the Variants and Offers the source returnedTikTok Shop · AmazonDesigned
  • GET/v1/e-commerce/listings/searchSearch listings on one marketplace; each platform has its own filtersTikTok Shop · AmazonDesigned
  • GET/v1/e-commerce/listings/search-by-imageFind candidate listings from a product photo, without assuming they are the same itemTikTok Shop · AmazonDesigned
  • GET/v1/e-commerce/listings/rankingsBest-seller rankings by category and dateTikTok Shop · AmazonDesigned
  • GET/v1/e-commerce/tiktok-shop/listings/{listingId}/videosVideos that promote one listingTikTok ShopDesigned

Fields

The main fields by type. Observable ones use the contract's keys; the full contract follows.

Filter fields by type

Observable

A fresh snapshot, else a live read, else the next sourceBilled: When it comes back

Estimated

One estimator by default, up to three side by sideBilled: Per query

Verifiable

One source at a time, until an answer passes a checkBilled: Once it passes

Lists & risk

Pooled from several sources; one hit is enough to flagBilled: Per row

45 fields in the field contractDesign 0.1.0-draft · listing-contract-v3.2

Field keys and how each value is written, as the design defines them. Only fields a source actually returned come back.

Identity5

AIsa's ID, the platform, the site and the platform's own ID
  • entity.iduuid
  • entity.kindstring
  • entity.platformstring
  • entity.scopestring
  • entity.native_idstring

Page11

Title, link, images and what the page shows
  • titlestring
  • urlurl
  • imagesobject[]
  • image.cover_urlurl
  • description.blocksobject[]
  • attributes.listobject[]
  • status.availabilitystring
  • lifecycle.launch_datedate
  • badgesstring[]
  • affiliate.commission_ratedecimal
  • option_groupsobject[]

Ratings5

Rating and review counts, kept apart
  • rating.scoredecimal
  • rating.countinteger
  • rating.distributionobject[]
  • review.summarystring
  • review.countinteger

Metrics17

Sales, GMV and engagement, each over its source's period
  • metrics.sales_countdecimal
  • metrics.gmvdecimal
  • metrics.gmv_totaldecimal
  • metrics.creator_countinteger
  • metrics.video_countinteger
  • metrics.live_countinteger
  • metrics.video_view_countinteger
  • metrics.creator_order_ratedecimal
  • metrics.gmv_trendobject
Show 8 more fields
  • metrics.video_average_views_reporteddecimal
  • metrics.video_gpm_reporteddecimal
  • metrics.video_conversion_reporteddecimal
  • metrics.live_average_viewers_reporteddecimal
  • metrics.ad_gmv_reporteddecimal
  • metrics.ad_cost_reporteddecimal
  • metrics.seller_creator_sales_count_30ddecimal
  • metrics.seller_creator_gmv_30ddecimal

Links7

AIsa IDs of the entities it points at
  • relation.shop_iduuid
  • related.variantsuuid[]
  • related.variant_listingsuuid[]
  • related.parent_listingsuuid[]
  • related.child_listingsuuid[]
  • related.offersuuid[]
  • related.categoriesuuid[]

decimal and integer values arrive as strings to keep precision. A key ending in _reported is the source's own figure, method unconfirmed; _raw keeps the source's raw code. uuid fields point at other AIsa entities.

By marketplace

Where five or more estimators exist, sales come back side by side and get calibrated first. Elsewhere it starts with two compared, or one source labeled as one.

MarketplaceListing keyLive readsEstimatorsSales estimatesStatus
Amazonamazon:US · ASIN46Side by side, calibratedLive
TikTok Shoptiktok-shop:US · product_id15Side by side, calibratedLive
Temutemu:US · goods_id—3Side by sideSoon
Walmartwalmart:US · item ID12Two comparedSoon
Shopeeshopee:SG · item_id12Two comparedSoon
Ozonozon:RU · SKU—2Two comparedSoon
Mercado Libremercadolibre:BR · item ID—2Two comparedSoon
Etsyetsy:US · listing_id11One source, labeledSoon
Shopifyshopify:{store} · product ID—1One source, labeledSoon
eBayebay:US · item ID1—Live reads onlySoon
16881688:CN · offerId—2Supplier lists, mergedSoon

Counts come from the phase-one supplier list. Fill rate per field shows here once each marketplace is live.

What stays fixed

AIsa can swap the sources behind a field at any time. These stay put.

  1. The marketplace's own ID is the key, stored exactly as the marketplace issued it.
  2. An ID AIsa hands out is never changed or reused.
  3. Two sources that count differently stay two metrics, and the raw values are kept.
  4. Fields are only ever added. A changed meaning ships as a new version, with the old one kept for a while.

Next to Listing

Every link from a listing is a field you can ask for in the same call.

Search the catalog

Platforms, unified entities, vendor APIs, endpoints and connectors.