retailerapi / docs

GET /v1/products/{id}

The primary product-lookup endpoint. Resolves any UPC, EAN, ISBN, GTIN, or Walmart item_id.

Request

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

Path parameters

NameRequiredDescription
idyesUPC-12, EAN-13, ISBN-10/13, GTIN-14, or Walmart item_id (6-12 digits)

Query parameters

NameTypeDefaultDescription
formatstringauto-detectOne of UPC, EAN, ISBN, item_id. Set when input could be ambiguous.
include_offers_reviewsbooleanfalseLive marketplace sellers + review summary + top 5 reviews. Costs +5 tokens.
include_cross_retailerbooleanfalseCross-retailer cells (Amazon, eBay, Lowe's, Target, Best Buy, Home Depot). Costs +2 tokens.
force_refreshbooleanfalseBypass cache, fetch fresh from upstream. +3 tokens.
include_history + include_stats are accepted for 90-day backward compat but the data they returned is now part of the base call (free). include_offers is an alias for include_offers_reviews.

Cost summary

  • Base lookup: 1 token
  • + include_offers_reviews: 6 tokens
  • + include_cross_retailer: 3 tokens
  • Full (offers + cross-retailer): 8 tokens
  • Full + force_refresh: 11 tokens

Response

200 OK with a JSON body:

{
  "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,
  "dimensions": { "height_in": 13.2, "width_in": 13.0, "length_in": 12.8 },
  "offers_count": 4,
  "seller_name": "Walmart",
  "seller_id": "F55CDC31AB754BB68FE0B39041159D63",
  "average_rating": 4.3,
  "review_count": 1247,
  "categories": ["Home", "Appliances", "Pressure Cookers"],
  "walmart_url": "https://www.walmart.com/ip/...",
  "in_stock": true,
  "price_history": [
    { "recorded_at": "2026-04-09T12:00:00Z", "price": 99.99, "in_stock": true }
  ],
  "stats": { "sales_rank_30d": 142, "price_low_90d": 89.99, "price_high_90d": 119.99 },

  /* present when include_offers_reviews=true */
  "offers": [
    { "seller_id": "...", "seller_name": "Walmart", "price": 100.56, "is_buy_box": true, "in_stock": true },
    { "seller_id": "...", "seller_name": "Big Easy Mart", "price": 99.50, "is_buy_box": false, "in_stock": true }
  ],
  "review_summary": {
    "average_rating": 4.3,
    "total_reviews": 1247,
    "rating_distribution": { "5": 812, "4": 234, "3": 98, "2": 53, "1": 50 }
  },

  /* present when include_cross_retailer=true */
  "cross_retailer": [
    { "retailer": "amazon", "status": "ok", "price": 105.99, "url": "https://...", "in_stock": true },
    { "retailer": "ebay", "status": "ok", "price": 100.71, "url": "https://...", "in_stock": true },
    { "retailer": "target", "status": "not_found" }
  ],

  "tokens_consumed": 1,
  "tokens_remaining": 856249
}

Field types

  • Identifiers: always strings. item_id is Walmart-internal; upc is the GTIN equivalent.
  • Prices: USD as floats with 2 decimal places. null when out of stock.
  • Timestamps: ISO 8601 with timezone. UTC.
  • cross_retailer.status: ok | stale | indexing | not_found | blocked | error

Errors

  • 404 when the identifier doesn't resolve in our catalog (we try multiple format fallbacks before returning 404)
  • 400 when the identifier doesn't match any expected format
  • 429 when you exceed your throttle or monthly quota

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"

EAN-13 (international)

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

ISBN-13 (book)

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

See also