StatusSupportGet API keyDashboard
SchemasOffers

Schemas

Offer

Use with AI

Every seller's offer of a product: price, condition, availability, shipping fee and delivery estimate, and the seller with its rating.

Endpoints

1 endpoint returns offers on Amazon.

Schema

Every endpoint above returns an array of these objects as data, with a page object. The standard meta comes with every response.

platformstring

Platform ID (amazon, …).

idstring

The offer's ID: the platform's own where it is stable across fetches, else derived from the product, the seller and the condition (B0FQFB8FMG:ALAQLAKJ574UN:new), with ~2, ~3 for a seller's further offers in one condition, counted across the list's pages in the platform's order. A derived ID is stable while the seller's offers in that condition keep their order; two of them can swap IDs when their order changes.

product_idstring

ID of the product offered (equals product.id of the platform's product endpoints).

urlstring urinullable

The offer's own page (the merchant's page, the listing, or the product page with this seller selected); null when the platform has none.

titlestringnullable

The seller's own title for the product, where offers carry one (an eBay listing's, a shop's on Google Shopping); null where every offer shares the product's title.

sellerobject

The seller (a shop on the platform, or a merchant's site on a comparison platform); fields null when not shown.

ShowHide 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

The offer's price in major units of currency (58.47), discounts applied; shipping and tax excluded. 0 = free; null when not shown.

original_pricenumbernullable

Price before the discount (the struck-through list or earlier price), in major units of currency; null when the offer shows none.

currencystringnullable

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

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, Pre-Owned: Good, Renewed).

availabilitystringnullable

in_stock: can be bought now; out_of_stock: sold out for now; pre_order: ships later. Null when the platform does not say. New values may be added; treat unknown values as null.

One ofin_stockout_of_stockpre_order

is_featuredbooleannullable

The offer the product page shows by default (the buy box); at most one offer of a product is. Null where the platform features none.

seller_ratingnumbernullable

The seller's average rating out of 5 (metrics.seller_rating_count ratings behind it), as the platform shows it (rounded ones in approximate_fields); null when the seller is unrated or the platform does not show it.

shippingobject

Delivery terms of this offer; each null when not shown.

ShowHide 4 child fields
is_offeredbooleannullable

The seller ships this offer (false: local pickup only); null when not shown.

feenumbernullable

Standard shipping fee of this item alone, in major units of the offer's currency; 0 = free shipping; null when it depends on the order (free over a threshold) or is not shown.

earliest_delivery_atstring date-timenullable

First day of the standard delivery estimate, as that date at 00:00:00Z (date-only: approximate_fields); equal to latest_delivery_at for a one-day estimate; null when the platform gives no start.

latest_delivery_atstring date-timenullable

Last day of the standard delivery estimate, as that date at 00:00:00Z (date-only: approximate_fields); null when the platform gives no estimate.

country_codestringnullable

ISO 3166-1 alpha-2 market the offer is in; its prices, availability and delivery are that market's.

metricsobject

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

ShowHide 1 child field
seller_rating_countintegernullable

Ratings behind seller_rating, as the platform counts them.

platform_specificobject

Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.

ShowHide 1 child field
amazonobjectnullable

An Amazon offer's own fields.

ShowHide 4 child fields
ships_fromstringnullable

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

is_fulfilled_by_amazonbooleannullable

Amazon ships the offer from its own warehouses (Fulfillment by Amazon, or sold by Amazon); false when the seller ships it; null when not shown.

seller_positive_percentintegernullable

Share of the seller's ratings in the last 12 months that were positive, a whole percent (77); over the seller's lifetime for a seller Amazon shows that for (a new one); null when not shown (Amazon's own retail shows none).

condition_notestringnullable

The seller's or Amazon's notes on the item's condition (Item will come in original packaging.), as shown under it; null when none is shown, as on new offers.

approximate_fieldsstring[]

JSON paths of values rounded by the platform or parsed from display text (a seller rating in half stars, a date-only delivery estimate). [] when all exact.

unknown_fieldsstring[]

JSON paths of lists whose [] means unknown rather than none; null already means unknown for every other field. [] when every list is known.

Item errors

Besides the request-level errors every endpoint can return, offer endpoints return:

CodeHTTPRetryMeaningWhat to do
not_found404NoThe 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.

Last updated