# Bestbuy — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search Best Buy's entire product catalog and get instant autocomplete suggestions while browsing, then pull up detailed pricing, availability, and stock information for any item. Easily sort through results, look up multiple products at once, and discover what's trending in real-time.

**Category:** E-commerce | **Website:** [www.bestbuy.com/](https://www.bestbuy.com/) | **Docs:** [parse.bot/marketplace/21ffadd1-f248-4337-a212-e56b0fbf34fe/bestbuy-com-api](https://parse.bot/marketplace/21ffadd1-f248-4337-a212-e56b0fbf34fe/bestbuy-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/bestbuy/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get popular searches

Get the current popular/trending search terms on Best Buy. Returns a list of the most popular search queries currently being searched by users. Useful for discovery, understanding current consumer trends, and finding products to search for.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/bestbuy/get-popular-searches \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get product details

Get product information for specific SKU IDs. Accepts comma-separated SKU IDs (up to 50). Returns product name, URL, image, rating, and review count. SKU IDs can be obtained from search_products or search_suggestions results. Pricing fields may be null depending on upstream availability.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sku_ids` | string | Yes | Comma-separated SKU IDs (e.g., '6559890,6551114'). Maximum 50 SKUs per request. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/bestbuy/get-product-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sku_ids":"<string>"}'
```

### Search products

Search for products on Best Buy by keyword. Returns product details including name, rating, reviews, image, and URL. Results are sourced from Best Buy's suggest system which returns the most relevant products for a query. Also returns spell-check information and related search suggestions. Pricing fields (current_price, regular_price, savings_amount) may be null for some products depending on upstream availability.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of products to return (1-50) |
| `query` | string | Yes | Search keyword (e.g., 'laptop', 'samsung tv', 'macbook air') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/bestbuy/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","query":"<string>"}'
```

### Search suggestions

Get search autocomplete suggestions for a query. Returns suggested search terms with associated categories and product SKU IDs. Each suggestion includes a list of relevant SKU IDs and a product count. Useful for building search-as-you-type functionality or discovering related search terms.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `count` | integer | No | Number of suggestions to return (1-20) |
| `query` | string | Yes | Search query to get suggestions for |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/bestbuy/search-suggestions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"count":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.