# Offer

Schemas

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.

- [GETAmazon Offers API`/v1/amazon/offers`](https://socialtap.dev/docs/reference/amazon/offers/index.md)

## Schema

Every endpoint above returns an array of these objects 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 (amazon, …). |
| `id` | `string` | 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_id` | `string` | ID of the product offered (equals product.id of the platform's product endpoints). |
| `url` | `string` (uri) or `null` | 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. |
| `title` | `string` or `null` | 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. |
| `seller` | `object` | The seller (a shop on the platform, or a merchant's site on a comparison platform); fields null when not shown. |
| `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` | The offer's price in major units of currency (58.47), discounts applied; shipping and tax excluded. 0 = free; null when not shown. |
| `original_price` | `number` or `null` | Price before the discount (the struck-through list or earlier price), in major units of currency; null when the offer shows none. |
| `currency` | `string` or `null` | ISO 4217 code of every amount of this offer (USD); null when no amount is shown. |
| `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, Pre-Owned: Good, Renewed). |
| `availability` | `string` or `null` | 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.<br>One of `in_stock`, `out_of_stock`, `pre_order` |
| `is_featured` | `boolean` or `null` | 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_rating` | `number` or `null` | 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. |
| `shipping` | `object` | Delivery terms of this offer; each null when not shown. |
| `shipping.is_offered` | `boolean` or `null` | The seller ships this offer (false: local pickup only); null when not shown. |
| `shipping.fee` | `number` or `null` | 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. |
| `shipping.earliest_delivery_at` | `string` (date-time) or `null` | 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. |
| `shipping.latest_delivery_at` | `string` (date-time) or `null` | 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_code` | `string` or `null` | ISO 3166-1 alpha-2 market the offer is in; its prices, availability and delivery are that market's. |
| `metrics` | `object` | Counts at fetch time; null = not shown, 0 = zero. |
| `metrics.seller_rating_count` | `integer` or `null` | Ratings behind seller_rating, as the platform counts them. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.amazon` | `object` or `null` | An Amazon offer's own fields. |
| `platform_specific.amazon.ships_from` | `string` or `null` | Who ships the offer (Amazon, or the seller), as the offer says; null when not shown. |
| `platform_specific.amazon.is_fulfilled_by_amazon` | `boolean` or `null` | 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. |
| `platform_specific.amazon.seller_positive_percent` | `integer` or `null` | 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). |
| `platform_specific.amazon.condition_note` | `string` or `null` | 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_fields` | `string[]` | 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_fields` | `string[]` | 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](https://socialtap.dev/docs/errors/index.md) every endpoint can return, offer 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. |

---

[HTML version](https://socialtap.dev/resources/offer/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)