# Booksamillion — 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.

> Access Books-A-Million's catalog to retrieve bestseller lists across fiction, nonfiction, manga, YA, and kids' categories, fetch detailed book information and customer reviews, search books by keyword, and look up nearby store locations. Returns structured data including titles, authors, pricing, availability, cover images, and paginated review content.

**Category:** E-commerce | **Website:** [booksamillion.com/](https://booksamillion.com/) | **Docs:** [parse.bot/marketplace/b739c7a3-91c8-400a-82ce-0f4e135f8a6b/booksamillion-com-api](https://parse.bot/marketplace/b739c7a3-91c8-400a-82ce-0f4e135f8a6b/booksamillion-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/booksamillion/`
**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 bestsellers

Fetches the overall bestsellers list from Books-A-Million. Returns all books currently featured on the main bestsellers page, across all categories. Single-page response containing the full list.

**Estimated cost:** Metered

_No parameters required._

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

### Get bestselling fiction

Fetches bestselling fiction books from Books-A-Million. Returns all books currently on the fiction bestsellers list.

**Estimated cost:** Metered

_No parameters required._

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

### Get bestselling kids

Fetches bestselling Kids books from Books-A-Million. Returns all books currently on the kids' bestsellers list.

**Estimated cost:** Metered

_No parameters required._

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

### Get bestselling manga

Fetches bestselling manga books from Books-A-Million. Returns all books currently on the manga bestsellers list.

**Estimated cost:** Metered

_No parameters required._

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

### Get bestselling nonfiction

Fetches bestselling nonfiction books from Books-A-Million. Returns all books currently on the nonfiction bestsellers list.

**Estimated cost:** Metered

_No parameters required._

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

### Get bestselling ya

Fetches bestselling Young Adult books from Books-A-Million. Returns all books currently on the YA bestsellers list.

**Estimated cost:** Metered

_No parameters required._

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

### Get book details

Fetches detailed information for a single book given its full Books-A-Million product page URL. Returns title, author, pricing, ISBN, publisher, dimensions, and other metadata. The URL is obtainable from search_books or any bestseller endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full URL of the book detail page on booksamillion.com. Obtainable from search_books or bestseller endpoint results. |

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

### Get book reviews

Retrieves customer reviews for a book using its ISBN-13. Returns paginated review data from PowerReviews including average rating, review count, and individual reviews with ratings, comments, and reviewer info. The ISBN is obtainable from get_book_details results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `from` | integer | No | Starting index for pagination. |
| `isbn` | string | Yes | ISBN-13 of the book. Obtainable from get_book_details results. |
| `limit` | integer | No | Maximum number of reviews to return per page. |

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

### Get new releases

Fetches new release books from Books-A-Million. Returns all books currently featured on the new releases page.

**Estimated cost:** Metered

_No parameters required._

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

### Get store locator

Retrieves the nearest physical Books-A-Million store location for a given US ZIP code. Geocodes the ZIP and returns the closest store with address, phone, coordinates, and distance.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `zip` | string | Yes | US ZIP code to search near. Leading zeros preserved. |

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

### Search books

Search for books by keyword on Books-A-Million. Returns up to 20 results matching the query against titles and authors.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword or phrase. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/booksamillion/search-books \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"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.