主题
Marketplace Offer Object
offers[] 是 Product Object 的子对象，每个元素代表 Amazon 上的一个真实在售 / 历史 offer（含卖家、状态、价格 / 运费 / 库存历史等）。它是做 Buy Box 竞争分析、第三方卖家追踪、库存监控 的主要数据来源。
对应 Keepa 官方：Marketplace Offer Object
何时返回
| 条件 | 是否返回 offers[] |
|---|---|
请求 /api/keepa/product 且带 offers=N（N = 20 / 50 / 100） | ✅ |
不带 offers 参数 | ❌（offers 字段为 null 或缺失） |
detailLevel=summary | ❌ 即使带了 offers 参数，pickSummary 也会剔除 offers 整段 |
detailLevel=lite | ✅ 但 couponHistory / stockCSV 等历史数组保留（仅 Product 级历史会被 strip） |
detailLevel=full | ✅ 完整 |
⚠️ 关键提醒（来自 Keepa 文档原文）
- Keepa 不会给一个产品下的全部 offer 都拉历史。
offers=N决定每次 拉取的 offer 数上限；若产品的真实 offer 数超过 N，多出来的不会被采集- offer 排名变化频繁，不同请求拉到的 offer 集合可能不同。必读
lastSeen字段，过滤掉过期 offer；或直接用 Product Object 的liveOffersOrder拿当前 live 的索引序列- 单个 offer 的历史数组（
offerCSV/stockCSV）几乎一定有空洞——历史完整度依赖你请求的频次。完整覆盖请定期重复请求，并配合 Product Object 的csv[28]（EXTRA_INFO_UPDATES）确认实际更新时间- 卖家 / 条件 / 配送方式都相同的「孪生 offer」只会保留最低价那一条，其它的并入
offerDuplicates
字段表
| 字段 | 类型 | 说明 |
|---|---|---|
offerId | int | offer 在该 product 内的唯一 ID（Keepa 自己分配，非 Amazon 的 offerListingId）。可用于跨请求识别同一 offer |
lastSeen | int | 最后一次抓取/更新该 offer 的 KeepaTime。只关心当前在售时务必校验该字段 |
sellerId | string | 卖家 ID（Amazon Marketplace seller ID，如 A2L77EE7U53NWQ = Amazon Warehouse Deals）。可传给 /keepa/seller 拉卖家详情 |
isPrime | boolean | 是否走 Prime 配送。Keepa 无法可靠识别 SFP（Seller-Fulfilled Prime），SFP 可能被标为 false |
isFBA | boolean | 是否 FBA（Amazon 仓配） |
isMAP | boolean | 是否受 MAP（Minimum Advertised Price）限制——商品页面隐藏价格。即便如此，Keepa 仍会在 offerCSV 里给出真实价格 + 运费 |
isShippable | boolean | 当前是否可发货（缺货 / 预售时为 false） |
isPreorder | boolean | 是否预售 |
isWarehouseDeal | boolean | 是否 Amazon Warehouse Deal |
isAmazon | boolean | 卖家是否为 Amazon 主账号。注意 Warehouse Deals 等关联账号在此为 false |
isPrimeExcl | boolean | 是否 Prime 专享折扣价 offer |
coupon | int | 当前一次性优惠券（None = undefined）。正数 = 绝对金额（cents，如 500 = $5）；负数 = 百分比折扣（如 -15 = 15% off） |
couponHistory | int[] | 优惠券历史，[keepaTime, coupon, ...] |
condition | int | 商品状况，见下方 condition 取值。Open Box 归入 Used |
conditionComment | string | 卖家填写的状况描述文本（如 "Open Box, works great"）；无则 undefined |
minOrderQty | int | 起购量。仅当 > 1 时才会出现该字段 |
lastStockUpdate | int | 最近一次更新 stock 的 KeepaTime |
offerCSV | int[] | 该 offer 的价格 + 运费历史，3 元一组：[keepaTime, price, shipping, ...]。详见 offerCSV 解读 |
stockCSV | int[] | 该 offer 的库存历史，[keepaTime, stock, ...]。仅在请求带 stock=1 时返回；Keepa 也未必能拿到准确库存（per-customer 限购等场景会失真） |
primeExclCSV | int[] | Prime 专享价历史，[keepaTime, price, ...]。无值时为 null 或 -1 |
offerDuplicates | object[] | 同卖家 / 同状况 / 同配送的「重复 offer」（已被合并的更高价副本）。每项 { price, shipping, conditionComment } |
condition 取值
| 值 | 含义 |
|---|---|
0 | Unknown |
1 | New |
2 | Used - Like New |
3 | Used - Very Good |
4 | Used - Good |
5 | Used - Acceptable |
6 | Refurbished |
7 | Collectible - Like New |
8 | Collectible - Very Good |
9 | Collectible - Good |
10 | Collectible - Acceptable |
11 | Rental |
Open Box 状况会按等级映射到对应的 Used 值。
offerCSV 解读
offerCSV 与 Product Object 的 csv 时-值数组 不同：每组 3 个整数 而非 2 个。
text
[ keepaTime, price, shipping, keepaTime, price, shipping, ... ]price/shipping单位：Centsprice、shipping取-2= 该时刻无法确定shipping取0= 免运费shipping取-1= 不可配送 / 运费未知- 当前最新价 =
offerCSV[length - 2]，当前最新运费 =offerCSV[length - 1]
stockCSV 解读
格式 [keepaTime, stock, ...]。仅在请求 /api/keepa/product?...&stock=1 时返回。库存数据本身可能不精确（per-customer 限购、隐藏库存等），用于趋势判断比绝对值更可靠。
primeExclCSV 解读
格式 [keepaTime, price, ...]，price 单位为 cents。最新值 = primeExclCSV[length - 1]。无 Prime 专享时该字段为 null，或最末值为 -1。
与 Product Object 中字段的联动
liveOffersOrder（int[]）：Product Object 字段，给出当前 live offer 在offers[]中的下标顺序，与 Amazon 商品页的展示顺序一致buyBoxSellerIdHistory/buyBoxUsedHistory：Product Object 上的 Buy Box 卖家变更历史，与offers[].sellerId可关联csv[28]（EXTRA_INFO_UPDATES）：每次 Keepa 实际刷新该产品 offer 数据的时间，用于判断 offer 历史的覆盖密度
上层 / 关联对象
- 上层对象：Product Object（
offers[]） - 关联接口：
/api/keepa/product（带offers=N才返回） - 关联端点：
/api/keepa/seller（用sellerId拉卖家详情） - 公共约定：字段速查 · 公共约定（KeepaTime / cents / 缺失值）