GET /v1/products/{id}

Request

GET https://api.retailerapi.com/v1/products/{id}
Authorization: Bearer rk_live_...

Path parameters

Query parameters

Cost summary

Marketplace fees (referral_fee_usd, wfs_fee_usd) are computed from public rate cards and are always free in the base call — same model as Keepa's referralFeePercentage. include_seller_context only pays for the live-state fields (restricted, wfs_eligibility).

Response

200 OK with a JSON body. Fields below show a UPC lookup with all opt-in flags enabled.

{
  "item_id": "19667262713",
  "upc": "086279195869",
  "ean": null,
  "isbn": null,
  "gtin": "00086279195869",
  "asin": null,
  "mpn": "EP-PC8",
  "model": "EP-PC8",
  "title": "12-in-1 Electric Pressure Cooker 6 QT...",
  "brand": "Cooks Essentials",
  "image_url": "https://i5.walmartimages.com/...",
  "description": "Cook everything from rice to roast...",
  "current_price": 100.56,
  "buybox_price": 100.56,
  "secondary_offer_price": 99.50,
  "msrp": 149.99,
  "weight_lbs": 12.5,
  "weight_assembled_lbs": 12.5,
  "weight_package_lbs": 14.2,
  "dimensions": { "height_in": 13.2, "width_in": 13.0, "length_in": 12.8 },
  "dimensions_assembled": { "height_in": 13.2, "width_in": 13.0, "length_in": 12.8 },
  "dimensions_package": { "height_in": 15.0, "width_in": 14.5, "length_in": 14.0 },
  "offers_count": 4,
  "total_offers": 6,
  "delivery_date": "2026-06-23",
  "fulfillment": {
    "shipping": { "available": true, "cost": 0, "free": true, "date": "2026-06-23" },
    "delivery": { "available": false, "cost": null, "date": null },
    "pickup": { "available": true, "cost": 0, "date": "2026-06-21" }
  },
  "seller_name": "Walmart",
  "seller_id": "F55CDC31AB754BB68FE0B39041159D63",
  "average_rating": 4.3,
  "review_count": 1247,
  "categories": ["Home", "Appliances", "Pressure Cookers"],
  "specs": [
    { "name": "Model", "value": "EP-PC8" },
    { "name": "Capacity", "value": "6 quart" },
    { "name": "Color", "value": "Stainless Steel" }
  ],
  "walmart_url": "https://www.walmart.com/ip/...",
  "in_stock": true,
  "condition": "new",
  "seller_type": "first_party",
  "seller_rating": null,

  /* Walmart marketplace economics — FREE in the base call (Keepa parity), derived
     from the record. Platform/item-wide, not seller-specific. */
  "referral_fee_usd": 15.08,
  "wfs_fee_usd": 11.95,
  "restriction": { "flag": false, "reason": null },
  "wfs_eligibility": { "enabled": true, "reason": null },

  /* top-level UPC-scoped restriction view — present when include_seller_context=true */
  "seller_context": {
    "restricted": { "any": false, "retailers": [], "primary_reason": null }
  },

  /* Price history, from our daily-bar archive — one bar per day.
     days_covered is how many days we actually hold for this item, so every
     figure below can be read against the evidence behind it. */
  "price_history": {
    "first_observed_date": "2026-07-01",
    "last_observed_date": "2026-08-02",
    "days_covered": 29,

    /* series is present only with include_price_series=true (+10). */
    "series": [
      { "date": "2026-08-02", "open": 99.99, "close": 99.99, "low": 99.99, "high": 99.99, "observations": 1 },
      { "date": "2026-08-01", "open": 104.99, "close": 99.99, "low": 99.99, "high": 104.99, "observations": 3 }
    ]
  },

  /* Aggregated price stats — FREE in the base call. One entry per window.
     A window we hold no bars for is null, never a fabricated number, and
     days_covered states the real depth behind each row. */
  "stats": {
    "current_price": 99.99,
    "windows": {
      "30d":  { "low": 89.99, "high": 119.99, "average": 101.42, "days_covered": 28, "observation_count": 28 },
      "60d":  { "low": 89.99, "high": 124.99, "average": 103.10, "days_covered": 29, "observation_count": 29 },
      "90d":  { "low": 89.99, "high": 124.99, "average": 103.10, "days_covered": 29, "observation_count": 29 },
      "180d": { "low": 89.99, "high": 124.99, "average": 103.10, "days_covered": 29, "observation_count": 29 }
    }
  },

  /* free for barcode lookups; absent for item_id */
  "retailer_links": [
    { "retailer": "walmart", "url": "https://walmart.com/ip/...", "found_via": "native_catalog" },
    { "retailer": "amazon",  "url": "https://amazon.com/dp/B0...", "found_via": "amazon_catalog" }
  ],

  /* Map keyed by retailer slug. Only present when include_cross_retailer=true.
     Read-only over our cache — to refresh a specific retailer's data,
     use ?retailer=<retailer>&force_refresh=true. */
  "cross_retailer": {
    "walmart": {
      "retailer": "walmart",
      "status": "ok",
      "price": 100.56,
      "url": "https://www.walmart.com/ip/...",
      "in_stock": true,
      "unavailable": false,
      "sold_tag": "100+ bought",
      "estimated_sales": 1200,
      "is_best_seller": true,
      "pack_count": 1,
      "hazmat": false,
      "seller_context": {
        "referral_fee_usd": 15.08,
        "wfs_fee_usd": 11.95,
        "restricted": { "flag": false, "reason": null },
        "wfs_eligibility": { "enabled": true, "reason": null }
      },
      "_source": "primary",
      "_freshness": { "refreshed_at": "2026-05-16T10:00:00Z" }
    },
    "amazon": {
      "retailer": "amazon",
      "status": "ok",
      "price": 105.99,
      "url": "https://www.amazon.com/dp/...",
      "in_stock": true,
      "unavailable": false,
      "sold_tag": null,
      "estimated_sales": null,
      "is_best_seller": null,
      "pack_count": null,
      "hazmat": null,
      "seller_context": {
        "referral_fee_usd": 15.90,
        "wfs_fee_usd": null,
        "restricted": null,
        "wfs_eligibility": null
      },
      "_source": "secondary",
      "_freshness": { "refreshed_at": "2026-05-16T09:00:00Z" }
    }
    /* + ebay, lowes, target, bestbuy, homedepot */
  },

  /* present when include_offers_reviews=true. offers[] is the full live per-seller
     list (every competing seller), and offers_count reflects its length. Available
     for Walmart (item_id) AND Amazon (ASIN or ?retailer=amazon, via the AOD panel).
     Every offer carries a cross-retailer fulfilled_by_marketplace flag (Walmart
     "wfs" / Amazon "fba"); Amazon offers also carry "fba", and seller_type is "1p"
     (sold by the retailer itself) or "3p" (a marketplace seller), independent of
     fulfillment. condition is a canonical enum shared across retailers. */
  "offers": [
    { "seller_id": "101030561", "seller_id_hex": "C4E1FFE689DE4B388E0EDABC848B3078", "seller_name": "iTech361", "price": 100.56, "is_buy_box": true, "in_stock": true, "wfs": false, "fulfilled_by_marketplace": false, "pro_seller": true, "shipping_cost": 0, "delivery_date": "2026-07-06", "seller_type": "3p", "offer_id": "AB376F76122C494CBE9C13C605A1ADAD", "max_delivery_date": "2026-07-09", "max_order_quantity": 12, "fulfillment_type": "marketplace", "returnable": true, "return_window_days": 30, "free_returns": true, "condition": "new", "quantity_available": 12 },
    /* Amazon (ASIN / ?retailer=amazon) offer shape — the AOD all-sellers list: */
    { "seller_id": "A1JD8CBFFS2JH6", "seller_id_hex": null, "seller_name": "Prime National Distribution", "price": 12.00, "is_buy_box": false, "in_stock": true, "wfs": null, "fba": false, "fulfilled_by_marketplace": false, "seller_type": "3p", "shipping_cost": 0, "delivery_date": "2026-07-08", "condition": "new", "quantity_available": null }
  ],
  "review_summary": {
    "average_rating": 4.3,
    "total_reviews": 1247,
    "rating_distribution": { "5": 812, "4": 234, "3": 98, "2": 53, "1": 50 }
  },
  "reviews": {
    "summary": { "average_rating": 4.3, "total_reviews": 1247, "sentiment": { "positive": 1040, "neutral": 110, "negative": 97 }, "verified_purchases": 1180 },
    "monthly_breakdown": [
      { "month": "2026-05", "total_reviews": 41, "average_rating": 4.4, "sentiment": { "positive": 34, "neutral": 4, "negative": 3 } }
    ],
    "top_reviews": []  /* individual review bodies, when the source exposes them. Walmart currently returns aggregates only, so this is typically empty. */
  },

  /* present when include_offers_history=true (Walmart). offers_history[] is the
     price/seller archive — same per-offer field names as offers[], plus
     observed_at (the snapshot time) and was_price. offers_history_count is the
     total archived rows. Empty array when we have no archive for the item yet. */
  "offers_history_count": 248,
  "offers_history": [
    { "observed_at": "2026-06-21T14:02:00Z", "seller_id": "101030561", "seller_id_hex": "C4E1FFE689DE4B388E0EDABC848B3078", "seller_name": "iTech361", "seller_type": "3p", "price": 104.99, "was_price": 119.99, "shipping_cost": 0, "wfs": false, "pro_seller": true, "condition": "new", "quantity_available": 12, "fulfillment_type": "marketplace", "delivery_date": "2026-06-27", "offer_id": "AB376F76122C494CBE9C13C605A1ADAD", "returnable": true, "return_window_days": 30, "free_returns": true, "seller_rating": 4.6, "seller_review_count": 1820 }
  ],

  "_meta": {
    "title_source": "walmart",
    "weight_lbs_source": "amazon",
    "dimensions_source": "amazon",
    "data_quality_score": 1.0
  },

  "tokens_consumed": 11,
  "tokens_remaining": 856249
}

Field types

• Identifiers: always strings. item_id is Walmart-internal; upc is the GTIN equivalent.
• Prices: USD floats with 2 decimal places. null when out of stock.
• Timestamps: ISO 8601 UTC.
• in_stock: true when at least one retailer reports the product is in stock; false only when every retailer with a known signal reports out-of-stock; null when no retailer has reported yet.
• cross_retailer.<retailer>.status: ok | stale | indexing | not_found | blocked | error
• cross_retailer.<retailer>.seller_context: null permanently for first-party retailers (target, bestbuy, lowes, homedepot) — they don't have a marketplace.
• retailer_links: where the product is found across retailers (URL only). Free on every barcode lookup.

Cross-retailer field semantics

Bucket-1 facts (sold_tag, estimated_sales, is_best_seller, pack_count, hazmat) populate where each retailer supports the concept. Most are populated for Walmart today; other retailers backfill as we add per-retailer parsers. Null doesn't mean "we forgot to fetch" — it means "this retailer doesn't expose this concept".

Top-level weight_lbs, dimensions, description, mpn, model use the best source we have across retailers. When one retailer's payload is missing weight or dimensions, another retailer's value backfills it automatically (Amazon's catalog tends to be most reliable for physical specs because FBA forces sellers to declare them). _meta.weight_lbs_source records which retailer the value came from on every response.

Package vs assembled. Retailers that distinguish the boxed-for-shipping weight from the product's own weight expose both as weight_assembled_lbs + weight_package_lbs (and the parallel dimensions_assembled + dimensions_package). Top-level weight_lbs / dimensions are the derived "best available": assembled wins (it's what the product actually is); package fills in when no assembled value is known. Retailers that only expose one weight populate weight_lbs and leave the explicit pair as null — call weight_assembled_lbs ?? weight_lbs when you need the product weight and don't care about the source.

Diagnostic _meta block

Every barcode lookup includes a _meta object describing which source each top-level field came from and how strongly sources agreed on identity. Safe to ignore for most uses.

{
  "_meta": {
    "title_source": "amazon",
    "brand_source": "walmart",
    "weight_lbs_source": "amazon",
    "dimensions_source": "amazon",
    "data_quality_score": 0.667,
    "disagreements": [
      {
        "retailer": "target",
        "reason": "title-mismatch",
        "similarity": 0.21,
        "their_title": "Different product entirely",
        "consensus_title": "12-in-1 Electric Pressure Cooker 6 QT..."
      }
    ]
  }
}

Errors

• 404 when the identifier doesn't resolve (multiple format fallbacks are attempted before returning 404)
• 400 when the identifier doesn't match any expected format
• 429 when you exceed your throttle or monthly quota
• 503 (offers_unavailable) when live offers are momentarily unavailable for a Walmart item. Returned only for live-offers requests (include_offers_reviews=true) so you never receive non-live offer data. Honor the Retry-After header (seconds) and retry; the request is not billed.

Examples

Walmart item_id

curl -H "Authorization: Bearer rk_live_..." \
  "https://api.retailerapi.com/v1/products/19667262713"

UPC with cross-retailer

curl -H "Authorization: Bearer rk_live_..." \
  "https://api.retailerapi.com/v1/products/194629116676?include_cross_retailer=true"

Reseller full view (cross-retailer + seller context)

curl -H "Authorization: Bearer rk_live_..." \
  "https://api.retailerapi.com/v1/products/194629116676?include_cross_retailer=true&include_seller_context=true"

EAN-13 (international)

curl -H "Authorization: Bearer rk_live_..." \
  "https://api.retailerapi.com/v1/products/5060214160102"

ISBN-13 (book)

curl -H "Authorization: Bearer rk_live_..." \
  "https://api.retailerapi.com/v1/products/9780553213119?format=ISBN"