# 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, and the product link. Narrow with friendly filters: brand, min_price/max_price, min_rating, condition.
> 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, and the product link. Narrow with friendly filters: brand, min_price/max_price, min_rating, condition.

**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 (1–240). Spans multiple result pages automatically (24/page).
- `page` (integer, optional, default 1) — Result page to start from (1-based; ~24 products/page).
- `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.

**Returns:** results[]{sku, name, brand, model, price{current, regular, savings, savings_pct}, rating{average, review_count}, availability{in_stock, ship_by}, image, images[], variants{types, options[]}, category_path[], product_type[], url} + meta{page, pages_fetched, sort, filter, grid_size}

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

### POST /bestbuy/v1/product_detail — 1 credit
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[], product_type[], url, condition, open_box}

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

### 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[]}}

### 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–40).

**Returns:** {query, suggestions[]{value, type, sku}, 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, pricing_type, offers[], button}}

**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 — 1 credit
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, specifications[]{name, value}, spec_count}

### POST /bestbuy/v1/similar — 1 credit
Get the products Best Buy recommends as similar to a given product (by SKU) → each recommended product's SKU, name, current price and link.

**Parameters:**
- `sku` (string, optional) — The Best Buy product SKU to find similar products for.
- `url` (string, optional) — A full bestbuy.com /product/ URL (alternative to the SKU).
- `limit` (integer, optional, default 20) — How many similar products to return (1–40).

**Returns:** {sku, similar[]{sku, name, price, url}}

### 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 (1–240; ~24/page).
- `page` (integer, optional, default 1) — Result page to start from (1-based; ~24/page).

**Returns:** results[]{sku, name, brand, price{current, regular, savings, savings_pct}, rating{average, review_count}, availability, image, url} + meta{record_count, with_savings, sort, 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
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt