# Walmart (/docs/walmart)

Walmart product, review, category, and marketplace seller data through one unified API

Walmart keyword search, category browsing, product detail, customer reviews, and marketplace seller offers behind the same canonical commerce schema as Amazon, Target and Google Shopping, so one parser handles all of them.

Base URL: `/v1/walmart/...`

Products are keyed on the **product id**, the number at the end of a product URL. In `walmart.com/ip/AirPods-Pro-3/17835006350` the id is `17835006350`. Walmart's alphanumeric catalog id (`34J2GQ9D9TFM`) works in the same parameter, and every response returns both so you can join on whichever your system already stores.

  Walmart prices and stock are genuinely store-level. Without `zip_code`,
  `state`, or `store_id` you get a national catalogue figure rather than what a
  shopper standing in a store sees.

## Quickstart

### Resolve a keyword to product ids

`search` is the keyword-to-product-id resolver for the rest of the platform. Everything except `category` takes the id it returns.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/walmart/search?query=airpods%20pro" \
  -H "x-api-key: YOUR_API_KEY"
```

### Read the product, its reviews, and its other sellers

Already holding product ids? Start here instead.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/walmart/product?product_id=17835006350" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://www.socialcrawl.dev/v1/walmart/reviews?product_id=17835006350&limit=50" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://www.socialcrawl.dev/v1/walmart/offers?product_id=17835006350" \
  -H "x-api-key: YOUR_API_KEY"
```

## Search and browse

| Endpoint                   | Credits | What it returns                                                                                             | Key parameters                                                                                                                      |
| -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/walmart/search`   | 5       | Title, product id, URL, image, price, rating, review count, availability, seller, shipping and pickup flags | `query` (required), `page`, `sort_by`, `min_price`, `max_price`, `zip_code`, `state`, `store_id`, `facet`, `country`                |
| `GET /v1/walmart/category` | 5       | The same rows for a whole category, up to 100 a call, with current and original price on every one          | `category_id` (required), `limit`, `page`, `sort_by`, `min_price`, `max_price`, `zip_code`, `state`, `store_id`, `facet`, `country` |

Both take the same filters, so a filtered keyword search and a filtered category walk are the same call shape. Category ids appear in the category URLs on any product detail response, for example `3944` for Electronics.

Browsing beats searching for price monitoring across a fixed product set: `category` carries real prices on every row and pages up to 100 at a time.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/walmart/search?query=airpods%20pro&zip_code=90210&max_price=200" \
  -H "x-api-key: YOUR_API_KEY"
```

## Products and sellers

| Endpoint                  | Credits | What it returns                                                                                                                                           | Key parameters                     |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `GET /v1/walmart/product` | 5       | Title, brand, model, UPC, both descriptions, price, rating with its 1-5 breakdown, images, specifications, availability, seller, condition, return window | `product_id` (required), `country` |
| `GET /v1/walmart/offers`  | 5       | Every marketplace offer: seller name and id, price, stock, condition, pickup, return window, including Walmart's own                                      | `product_id` (required), `country` |

## Reviews

| Endpoint                  | Credits | What it returns                                                                                     | Key parameters                                                        |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `GET /v1/walmart/reviews` | 5       | Full review text, star rating, author, date, helpful votes, verified-purchase flag, reviewer photos | `product_id` (required), `page`, `limit`, `sort`, `rating`, `country`, `label`, `judgments` |

`limit` runs 1 to 50 and defaults to 10. `rating` filters to one star value and is applied exactly.

## All endpoints

## Platform notes

**Search rows carry prices, with a small null minority.** Most search results include `price.current`, but a few in-stock rows come back with no price at all. Those report `price.current` as `null` rather than a misleading `0`, so a null means Walmart did not publish one here, not that the item is free. Call `product` with that row's id when you need a guaranteed price.

**Category rows carry real prices, product rows carry more fields.** `category` returns `price.current` and `price.original` on every row, which is why it beats search for price monitoring. It does not populate `brand`, so read that from `product` when you need it. Its `sort_by` is applied loosely and does not guarantee a globally ordered page.

**The review `sort` parameter selects, it does not order.** Measured against the live source, `rating_high_low` and `rating_low_high` return the same set, and `recent` is not strictly newest-first. Sort the rows yourself if order matters.

**Review pages can overlap.** Walmart's review feed shifts between calls, so consecutive pages occasionally repeat a review. Every row carries a stable `id`, so de-duplicate by it when crawling.

**The offer count can exceed the offers returned.** Walmart reports a total that is sometimes larger than the list; the remainder is not exposed upstream, so treat the returned offers as the complete set you can act on.

**Marketplaces are separate catalogues.** Pass `country=US` (default, walmart.com) or `country=CA` (walmart.ca) on any endpoint. Product ids are marketplace-specific, so an id from one correctly returns a not-found against the other rather than resolving to the wrong product.

**Walmart-specific extras ride on `ext`.** `ext.catalog_id` carries the alphanumeric catalog id and `ext.seller_id` carries the seller identifier. The rest of the payload uses the shared commerce objects documented under [Schema](/docs/schema.md).

**Paginate until a page comes back empty.** The upstream's own result counter is not a reliable total. Empty results and not-found ids are refunded automatically and never billed.

## Labels

`/v1/walmart/reviews` labels each review by default, at no extra credit: `sentiment` (read from the words, never the stars, with `rating_mismatch` when the two clearly disagree) and `issue` (the main problem the review reports) on `computed.labels`. Send `judgments=off` for the page without them. See [Labels](/docs/labels.md) for the field shapes and the labels you can add with `label=`, such as `label=reports&reports=the battery drains quickly`.

## Next steps

- [Pagination](/docs/pagination.md): The universal cursor, and how to walk a category to the end.
- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [API reference](/docs/api-reference.md): Every Walmart parameter and response field.
- [Amazon](/docs/amazon.md): The same product, review and seller shapes for amazon.com.
- [Target](/docs/target.md): Category browsing and store locations for target.com.