# Best Buy API — search products, fetch product details, live prices, images, and customer reviews from BestBuy.com

> Search Best Buy by keyword → a paginated, sortable, filterable list of products with name, brand, model, current & regular price, savings, star rating + review count, stock status, image gallery, variants, category, seller type (Best Buy itself vs a marketplace seller), and the product link. Narrow with friendly filters: brand, min_price/max_price, min_rating, condition. NOTE: the full category breadcrumb (category_path) is not published on Best Buy's result grid - grid rows carry the product_type labels instead. For the breadcrumb, use product_detail for one product or products_batch for up to 15 at a time.
> ReefAPI engine `bestbuy` · 15 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/bestbuy/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /bestbuy/v1/search — 2 credits
Search Best Buy by keyword → a paginated, sortable, filterable list of products with name, brand, model, current & regular price, savings, star rating + review count, stock status, image gallery, variants, category, seller type (Best Buy itself vs a marketplace seller), and the product link. Narrow with friendly filters: brand, min_price/max_price, min_rating, condition. NOTE: the full category breadcrumb (category_path) is not published on Best Buy's result grid - grid rows carry the product_type labels instead. For the breadcrumb, use product_detail for one product or products_batch for up to 15 at a time.

**Parameters:**
- `query` (string, required) — What to search for on Best Buy (product keywords, brand, or model).
- `max_results` (integer, optional, default 24) — How many products to return. MAXIMUM 240 — that is the published ceiling, so there is nothing to probe for. Spans result pages automatically (24/page, 10 pages). Measured 2026-08-07 on 'laptop': 24/48/96/144/192 came back exact and 240 came back 226, because Best Buy's own grid repeats a few products across deep pages and duplicates are dropped — so treat 240 as an upper bound, not a promise of exactly 240 rows. Above 240 the value is clamped to 240 rather than rejected.
- `page` (integer, optional, default 1) — Result page to start from (1-based; ~24 products/page). Combine with max_results to walk past the 240-per-call ceiling: page=11 starts where a 240-result call ended.
- `sort` (enum, optional, default "relevance") — Result ordering. [one of: relevance, best_selling, best_discount, price_low, price_high, rating, newest]
- `brand` (string, optional) — Filter to one brand (e.g. Apple, HP, Samsung, Sony). Use the exact brand name as Best Buy shows it.
- `min_price` (number, optional) — Lowest price to include (USD). Combine with max_price for a price window.
- `max_price` (number, optional) — Highest price to include (USD).
- `min_rating` (enum, optional) — Only products at or above this customer rating. [one of: 5, 4, 3, 2, top_rated]
- `condition` (enum, optional) — Product condition. [one of: new, open_box, refurbished, pre_owned]
- `category` (string, optional) — Advanced: restrict results with a raw Best Buy facet token (escape hatch for power users). Discover the available facets for a keyword with the `categories` action. Most users want the brand / min_price / max_price / min_rating / condition filters instead.
- `include_sponsored` (boolean, optional, default true) — Best Buy mixes paid placements into its result grid. By default they are returned in their real grid position and marked `sponsored: true` so you can tell them apart. Set to false to return organic results only.

**Returns:** results[]{sku, name, brand, model, sponsored, price{current, regular, savings, savings_pct}, rating{average, review_count}, availability{in_stock, ship_by}, image, images[], variants{types, options[]}, open_box{available, from_price, condition_codes[]} (present when an open-box version is also on sale), seller_type ('1P' = sold by Best Buy itself, '3P' = a marketplace seller) + seller_id + seller (a name only for 1P - Best Buy publishes no name for marketplace sellers on any surface, so 3P rows carry the type and id and a null name), product_type[], url} + meta{page, pages_fetched, sort, filter, grid_size, with_price, incomplete, sponsored_count, has_next}. `has_next` tells you whether another page exists: true means increment `page` for more, false means this was the last page. Requesting a page beyond the last returns NOT_FOUND with has_next:false and is NOT billed - the end-of-results signal, not an error to retry.

**Example request body:**
```json
{
  "query": "laptop"
}
```

### POST /bestbuy/v1/product_detail — 2 credits
Get the full product card for one Best Buy item by its product number, URL, or product-id → name, brand, model, current/regular price + savings, clearance/sale flags & special offers, stock status, star rating with a 5★-to-1★ breakdown, what customers like/dislike, image gallery, color/storage/carrier variants, and the category breadcrumb.

**Parameters:**
- `sku` (string, optional) — Best Buy product number. Accepts the 7-digit SKU (e.g. 6565837), OR the product-id from the page URL (the code like JJGCQ8VCFQ), OR a full bestbuy.com product link — any of the three works.
- `url` (string, optional) — A full bestbuy.com product page URL (alternative to the product number).

**Returns:** product{sku, name, brand, model, price{current, regular, savings, savings_pct, pricing_type, offers[]}, availability{in_stock, button_text}, rating{average, review_count, breakdown, verified_purchase_count}, customers_say{pros[], cons[]}, image, images[], variants{types, options[]}, category_path[] (the full breadcrumb, root first: Computers & Tablets > Laptops > All Laptops > Chromebooks > Touchscreen Chromebooks), product_type[], url, condition, open_box{available, from_price, condition_codes[]} (present when Best Buy also sells this product open-box; null when it does not), seller_type ('1P' = sold by Best Buy itself, '3P' = a marketplace seller) + seller_id + seller (the seller's NAME, which Best Buy publishes only for its own 1P listings - a 3P listing returns its type and id and a null name, never a made-up one), upc (the product's barcode), weight (as printed, e.g. '3.99 pounds'), weight_value + weight_unit (the same weight as a number plus its unit, e.g. 3.99 + 'POUND' — units seen in a 381-product sample: POUND, OUNCE, GRAM; both are null, never guessed, if the printed string cannot be parsed), dimensions{Product Height/Width/Depth}, specifications[]{name, value, group}, spec_count, description, features[], included_items[], manufacturer, reviews[] (the top-5 customer reviews inline: rating, author, pros, cons, helpful_count, photos, verified/incentivized flags - the full feed is on the `reviews` action)}. SHIPPING WEIGHT: `weight` is Best Buy's own printed string and is unchanged; `weight_value` (number) and `weight_unit` (POUND | OUNCE | GRAM | KILOGRAM) are the parsed pair for rate calculations. Whenever a printed weight exists the pair is present too — null if the string could not be parsed with certainty, because a wrong unit is worse than no weight.

**Example request body:**
```json
{
  "sku": "6571043"
}
```

### POST /bestbuy/v1/products_batch — 5 credits
Look up MANY Best Buy products in ONE call by product number — up to 15 per request → each product's barcode (UPC), name, brand, price, rating, images, full technical specifications, shipping weight and package dimensions. Built for enriching a whole catalogue or price list at once instead of one product at a time.

**Parameters:**
- `skus` (array, required) — Best Buy product numbers to look up — up to 15 per call. Accepts a list, or a comma-separated string. Anything Best Buy does not resolve comes back in `not_found` rather than being silently dropped.

**Returns:** products[]{sku, upc, name, brand, price{current, regular}, rating{average, review_count}, images[], url, condition, weight, weight_value, weight_unit, dimensions, specifications[]{name, value, group}, spec_count, description, features[], included_items[], manufacturer} + not_found[] (skus Best Buy did not resolve)

### POST /bestbuy/v1/reviews — 1 credit
Get customer reviews for a Best Buy product → each review's star rating, title, full text, author, date, pros & cons, verified-purchase / incentivized flags, how long they've owned it, helpful-vote counts, and any customer photos. Paginated.

**Parameters:**
- `sku` (string, optional) — Best Buy product number. Accepts the 7-digit SKU (e.g. 6565837), OR the product-id from the page URL (the code like JJGCQ8VCFQ), OR a full bestbuy.com product link — any of the three works.
- `url` (string, optional) — A full bestbuy.com product page URL (alternative to the product number).
- `page` (integer, optional, default 1) — Page of reviews to return.
- `page_size` (integer, optional, default 20) — Reviews per page (max 100).
- `sort` (enum, optional, default "MOST_RECENT") — How to order the reviews. [one of: MOST_RECENT, MOST_HELPFUL, HIGHEST_RATING, LOWEST_RATING]

**Returns:** {sku, total_reviews, total_pages, page, rating_breakdown, reviews[]{rating, title, text, author, submitted_at, recommended, pros, cons, days_of_ownership, helpful_count, verified_purchaser, incentivized, photos[]}}

**Example request body:**
```json
{
  "sku": "6565837"
}
```

### POST /bestbuy/v1/review_summary — 1 credit
Get the review snapshot for a Best Buy product → average rating, total review count, verified-purchase count, the full 5★-to-1★ rating breakdown, and a 'what customers say' summary of the most-mentioned pros and cons — in a single call.

**Parameters:**
- `sku` (string, optional) — Best Buy product number. Accepts the 7-digit SKU (e.g. 6565837), OR the product-id from the page URL (the code like JJGCQ8VCFQ), OR a full bestbuy.com product link — any of the three works.
- `url` (string, optional) — A full bestbuy.com product page URL (alternative to the product number).

**Returns:** {sku, total_reviews, average_rating, verified_purchase_count, rating_breakdown{5,4,3,2,1}, customers_say{pros[], cons[]}}

**Example request body:**
```json
{
  "sku": "6565837"
}
```

### POST /bestbuy/v1/search_suggestions — 1 credit
Get Best Buy search autocomplete suggestions for a partial query → the suggested search terms (with spell-correction), just like the dropdown under the search box.

**Parameters:**
- `query` (string, required) — The partial search text to autocomplete (e.g. 'lapt').
- `limit` (integer, optional, default 11) — How many suggestions to return (1–20).

**Returns:** {query, suggestions[]{term, categories[]{name, id}, product_skus[]}, corrected_query, correctly_spelled}

**Example request body:**
```json
{
  "query": "laptop"
}
```

### POST /bestbuy/v1/popular_terms — 1 credit
Get Best Buy's currently trending / most-popular search terms (no input needed).

**Parameters:** none

**Returns:** {terms[]}

### POST /bestbuy/v1/price — 1 credit
Get the live pricing for a Best Buy product by SKU → current price, regular price, savings, clearance/sale flags and special offers (from Best Buy's pricing API).

**Parameters:**
- `sku` (string, required) — The Best Buy product SKU (7-digit number, e.g. 6565837).

**Returns:** {sku, pricing{current, regular, savings, savings_pct, pricing_type, currency, button_state, button_text, in_stock, condition, offers[], name, brand}}

**Example request body:**
```json
{
  "sku": "6571043"
}
```

### POST /bestbuy/v1/gifts — 1 credit
Get the Gift-With-Purchase offers for a Best Buy product by SKU → each promotional offer (e.g. 'Apple TV Up to 1 Month GWP') and the free gift SKUs that come with it.

**Parameters:**
- `sku` (string, required) — The Best Buy product SKU to check for gift-with-purchase.

**Returns:** {sku, offers[]{offer_id, name}, gifts[]{sku, quantity, name, offer_id}}

**Example request body:**
```json
{
  "sku": "6571043"
}
```

### POST /bestbuy/v1/description — 2 credits
Get a Best Buy product's full description and complete technical specifications by SKU → the marketing description plus every spec (name/value pairs: connectivity, dimensions, features, etc.). The deep product detail that lives on the product page.

**Parameters:**
- `sku` (string, optional) — The Best Buy product SKU (7-digit, e.g. 6505727).
- `url` (string, optional) — A full bestbuy.com /product/ URL (alternative to the SKU).

**Returns:** {sku, description, description_short, features[], included_items[], specifications[]{name, value, group}, spec_count, weight, weight_value, weight_unit, dimensions, upc}

### POST /bestbuy/v1/deals — 1 credit
Browse Best Buy's current deals — on-sale and clearance products site-wide, sorted by biggest discount by default → each product's name, brand, current & regular price, the amount and percent saved, star rating, stock status, image and link. Great for a 'today's best deals' / price-drop feed. (To find deals within a category, use search with sort=best_discount.)

**Parameters:**
- `sort` (enum, optional, default "best_discount") — How to order the deals (default: biggest discount). [one of: best_discount, best_selling, price_low, price_high, rating, newest]
- `max_results` (integer, optional, default 24) — How many deal products to return. MAXIMUM 240 (24/page, 10 pages), the same published ceiling as search. Measured 2026-08-07: 96 returned 96, 240 returned 180 — the deals grid is a finite list, so 240 is an upper bound rather than a guarantee. Above 240 the value is clamped, not rejected.
- `page` (integer, optional, default 1) — Result page to start from (1-based; ~24/page).
- `include_sponsored` (boolean, optional, default true) — Keep Best Buy's paid placements (marked `sponsored: true`) in the results. Set to false for organic deals only.

**Returns:** results[]{sku, name, brand, sponsored, price{current, regular, savings, savings_pct}, rating{average, review_count}, availability, image, url} + meta{record_count, with_savings, with_price, sponsored_count, sort, page, has_next (true = increment page for more; false = last page)}

### POST /bestbuy/v1/trending — 1 credit
Get Best Buy's trending-right-now search terms — what shoppers are searching for at the moment (distinct from popular_terms, which is all-time most-popular). No input needed.

**Parameters:** none

**Returns:** {terms[]}

### POST /bestbuy/v1/qa — 1 credit
Get the customer questions & answers for a Best Buy product → each question with its author, date, and every answer (text, author, date, helpful-vote count, and which answer was voted best). Great for pre-purchase research. Paginated.

**Parameters:**
- `sku` (string, optional) — Best Buy product number. Accepts the 7-digit SKU (e.g. 6565837), OR the product-id from the page URL (the code like JJGCQ8VCFQ), OR a full bestbuy.com product link — any of the three works.
- `url` (string, optional) — A full bestbuy.com product page URL (alternative to the product number).
- `page` (integer, optional, default 1) — Page of questions to return.
- `page_size` (integer, optional, default 10) — Questions per page (max 100).
- `sort` (enum, optional, default "MOST_RECENT") — How to order the questions. [one of: MOST_RECENT, MOST_HELPFUL]

**Returns:** {sku, total_questions, page, page_size, questions[]{id, question, detail, author, submitted_at, answer_count, helpful_count, is_featured, photos[], answers[]{id, text, author, submitted_at, helpful_count, is_best_answer, is_brand, from_best_buy_member}}}

**Example request body:**
```json
{
  "sku": "6565837"
}
```

### POST /bestbuy/v1/store_availability — 1 credit
Check whether a Best Buy product (by SKU) is available to buy for a given ZIP code (and optionally a specific store) → an available flag plus the live buy-button status (e.g. Add to Cart / Sold Out / Pre-Order). Useful for retail-arbitrage and local-stock checks.

**Parameters:**
- `sku` (string, required) — The Best Buy product SKU (7-digit number, e.g. 6505727).
- `zip` (string, optional, default "10001") — The US ZIP code to check availability for (defaults to 10001 / New York if omitted).
- `store_id` (string, optional) — Optional Best Buy store number to check a specific store. Omit to check general availability for the ZIP.

**Returns:** {sku, zip, store_id, available, button_state, status_text}

**Example request body:**
```json
{
  "sku": "6505727",
  "zip": "10001"
}
```

### POST /bestbuy/v1/categories — 1 credit
Discover the categories and filter facets available for a Best Buy keyword search → the category sub-paths (each with a category id you can browse) plus every filterable facet (Brand, Price, Customer Rating, and category-specific attributes) with their values and product counts. Use it to learn what you can filter by before calling search.

**Parameters:**
- `query` (string, required) — The keyword to discover categories & filters for (e.g. 'laptop', 'tv', 'headphones').
- `category` (string, optional) — Advanced: narrow to a sub-category first (raw facet token) to discover its deeper facets.

**Returns:** {query, categories[]{name, category_path, count}, filters[]{field, display_name, values[]{value, count, category_path}}}

**Example request body:**
```json
{
  "query": "laptop"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=bestbuy
- Human docs page: https://reefapi.com/docs/bestbuy
- Overview page: https://reefapi.com/bestbuy-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt