# Best Buy

> Best Buy is a multinational consumer electronics retailer. Its developer program, the Best Buy
> Open API, exposes the product catalog, store network, product taxonomy, recommendation signals
> and open-box inventory over a read-only REST API at https://api.bestbuy.com/v1, plus a
> separately-gated Commerce API for authorized partners. This file was GENERATED by API
> Evangelist from the artifacts in github.com/api-evangelist/best-buy — Best Buy does not
> publish an llms.txt of its own (probed 2026-08-27: 404 on developer.bestbuy.com and
> bestbuyapis.github.io; www.bestbuy.com returned no response to this crawler).

## What an agent needs to know first

- Base URL: `https://api.bestbuy.com/v1`
- Auth: a single unscoped API key in the QUERY STRING — `?apiKey=YourAPIKey`. No OAuth, no scopes, no bearer token.
- Get a key: https://developer.bestbuy.com (free, self-serve, email activation).
- Ask for JSON explicitly: `&format=json`. The historical default is XML.
- Hard limits: **5 requests/second** and **50,000 requests/day** per key. Exceeding either returns **HTTP 403** — the same status returned for a bad key. There are no rate-limit response headers and no Retry-After. Self-meter.
- The whole public surface is GET. Nothing here mutates anything.
- Terms cap caching of returned content at **72 hours**; response links expire after **7 days**; attribution to Best Buy is required.

## APIs

- [Products API](https://bestbuyapis.github.io/api-documentation/#products-api): Over one million current and historical products with pricing, availability, specs, images, reviews and categorisation. Operations: `listProducts` (GET /products), `getProductBySku` (GET /products/{sku}).
- [Stores API](https://bestbuyapis.github.io/api-documentation/#stores-api): 1,587+ US and Puerto Rico locations with hours, addresses, services and coordinates. Operations: `listStores` (GET /stores), `getStoreById` (GET /stores/{storeId}).
- [Recommendations API](https://bestbuyapis.github.io/api-documentation/#recommendations-api): Behaviour-derived product lists. Operations: `getTrendingProducts` (GET /products/trendingViewed), `getMostViewedProducts` (GET /products/mostViewed), `getAlsoViewedProducts` (GET /products/{sku}/alsoViewed), `getAlsoBoughtProducts` (GET /products/{sku}/alsoBought).
- [Categories API](https://bestbuyapis.github.io/api-documentation/#categories-api): 4,328+ product categories as a hierarchical tree. No OpenAPI captured.
- [Buying Options (Open Box) API](https://bestbuyapis.github.io/api-documentation/#buying-options-api): Discounted open-box and Geek Squad certified refurbished stock with condition ratings, refreshed every five minutes. Batch queries up to 100 SKUs. No OpenAPI captured.
- [Commerce API](https://bestbuyapis.github.io/api-documentation/#commerce-api): GATED. Availability and delivery dates, shipping cost estimation, order creation, order retrieval, order modification and cancellation. Requires a separate CAPI key from https://developer.bestbuy.com/contact-us?topic=commerce-api; full documentation is released only after the key is issued.

## Machine-readable contracts

- [Products OpenAPI 3.0.3](openapi/best-buy-products-api-openapi.yml)
- [Stores OpenAPI 3.0.3](openapi/best-buy-stores-api-openapi.yml)
- [Recommendations OpenAPI 3.0.3](openapi/best-buy-recommendations-api-openapi.yml)

## Querying

Filters are embedded in the path inside parentheses, not passed as ordinary query parameters:

    GET https://api.bestbuy.com/v1/products(salePrice<100&manufacturer=samsung)?apiKey=KEY&format=json

- Operators: `=`, `!=`, `<`, `>`, `<=`, `>=`, `in(...)`
- Use `in(sku in(6354884,6354885,...))` to batch lookups — this is the documented way to stay under 5 req/sec instead of issuing one request per SKU.
- Sparse fields: `show=sku,name,salePrice` (or `show=all`) — cuts payload weight materially.
- Paging: `page` + `pageSize` (max 100), with `from`/`to`/`total`/`currentPage`/`totalPages` in the envelope. For deep paging use `cursorMark` and follow `nextCursorMark`.
- Sorting: `sort=salePrice.asc`

## Errors

Ad-hoc JSON, NOT RFC 9457. The wire shape is `{"errorCode":"403","errorMessage":"..."}` — errorCode is a string. The OpenAPI declares `{status,error,message}` and declares 401 for auth failure, but the live API returns **403**. No request-id or trace header exists in any response.

- 400 — malformed request (unknown query parameters are ignored, not rejected, since 2016)
- 403 — invalid key **or** quota exhausted; indistinguishable
- 404 — unknown sku, storeId, or a retired endpoint
- 405 — method not allowed (the catalog surface is GET-only)
- 500 / 501 / 503 — Best Buy server error

Full catalog: [errors/best-buy-problem-types.yml](errors/best-buy-problem-types.yml)

## Client libraries

All first-party SDKs live under https://github.com/BestBuyAPIs and all are dormant.

- JavaScript/Node — npm `bestbuy` 2.4.1 (2021-02-10) — the newest first-party release of any kind
- PHP — Packagist `bestbuy/bestbuy` v1.0.4 (2017-09-08)
- Ruby — RubyGems `bestbuy` 0.0.0 (2015-07-12)
- CLI — npm `bestbuy-cli` 1.1.1 (2017-11-21), bulk catalog extraction
- Java, .NET, Groovy — source only, no registry artifact

There is no first-party Python client. The actively-maintained option is the community package `bestbuyapi` on PyPI, which is not published by Best Buy.

## Agent surfaces

- MCP server: **none published by Best Buy.** Third-party wrappers exist (Composio, Apify) and are not endorsed. A candidate tool list derived from the OpenAPI is at [mcp/best-buy-mcp.yml](mcp/best-buy-mcp.yml).
- A2A agent card: none. `/.well-known/agent-card.json` and `/.well-known/agent.json` 404 on every Best Buy host.
- Webhooks / events: none. Consumers poll.
- Sandbox / test mode: none published.
- Agent skills: [skills/_index.yml](skills/_index.yml)

## Operational reality

- Change log: https://github.com/BestBuyAPIs/api-release-notes/blob/master/CHANGELOG.md — last entry **R17.4, 2017-10-01**. `developer.bestbuy.com/changelog` now 404s.
- Versioning: URL path, currently `v1`. A `v2` moving path parameters into the query string was signalled in 2017 and has never shipped.
- Status page: none.
- SLA: none. The Terms disclaim any warranty that the service will be uninterrupted or error-free, and reserve termination with or without notice.
- Deprecation: announced historically in the change log with stated removal windows; no Sunset/Deprecation header support.
- Security: a real vulnerability disclosure program runs at https://hackerone.com/bestbuy, but no `security.txt` advertises it.

## Support

- Contact: https://developer.bestbuy.com/contact-us
- Issues: https://github.com/BestBuyAPIs/api-documentation/issues
- Terms: https://developer.bestbuy.com/legal
- Query Builder (browser): https://bestbuyapis.github.io/bby-query-builder/