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

> Retrieve product data from Walmart.com including pricing, descriptions, availability, reviews, and category listings. Access real-time product information to search by keyword, look up items by ID or URL, and browse department categories.

**Category:** E-commerce | **Website:** [walmart.com/](https://walmart.com/) | **Docs:** [parse.bot/marketplace/0f0af915-be8d-4993-b785-a2ed9308d984/walmart-com-api](https://parse.bot/marketplace/0f0af915-be8d-4993-b785-a2ed9308d984/walmart-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-walmart-com-api-0f0af915/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_category_listings

Browse products within a specific Walmart category or department. Returns paginated product listings identical in shape to search_products. Category IDs are numeric identifiers from Walmart's taxonomy (e.g. '976759' for food, '1115193' for electronics).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Walmart category ID (e.g. '976759' for food, '1115193' for electronics) |
| `filters` | string | No | Facet filter string to narrow results |
| `page` | integer | No | Page number for pagination |
| `slug` | string | No | Category URL slug used in the browse URL path |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-walmart-com-api-0f0af915/get_category_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","filters":"<string>","page":"<integer>","slug":"<string>"}'
```

### get_product_details

Retrieve full product detail for a single Walmart item including price, brand, description, specifications, images, variants, fulfillment options, and seller. Provide either product_id (usItemId) or a full Walmart product URL; at least one is required.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | No | Walmart product/item ID (usItemId). Either product_id or url must be provided. |
| `url` | string | No | Full Walmart product URL (alternative to product_id). Either product_id or url must be provided. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-walmart-com-api-0f0af915/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>","url":"<string>"}'
```

### get_product_reviews

Retrieve paginated customer reviews for a specific Walmart product. Returns individual reviews with ratings, text, reviewer info, and pagination metadata. Use product_id (usItemId) from search_products or get_product_details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for review pagination |
| `product_id` | string | Yes | Walmart product/item ID (usItemId) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-walmart-com-api-0f0af915/get_product_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","product_id":"<string>"}'
```

### get_store_locations

Retrieve all Walmart store locations in a US state. Returns store name, type, full address, phone number, weekly operating hours, and available services/departments. Fetches data from Walmart's store directory by iterating city pages for the given state; response time scales with the number of cities in the state.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `state` | string | Yes | 2-letter US state abbreviation (e.g. 'TX', 'CA', 'VT') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-walmart-com-api-0f0af915/get_store_locations \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":"<string>"}'
```

### search_grocery_products

Search Walmart grocery products by keyword, scoped to a specific Walmart store for store-specific availability and pricing. Provide either zip_code (to let Walmart assign the nearest store) or store_id (to lock results to that exact physical store). When store_id is provided, results include only products from that store; if the store cannot be matched, an empty product list is returned rather than falling back to another store. Returns paginated product listings with name, brand, package size, current price, price per unit, item ID, product URL, and a store object identifying the specific Walmart physical store whose inventory and pricing was used. Each page returns up to ~40 products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination |
| `query` | string | Yes | Grocery search keyword (e.g. 'boneless skinless chicken breast', 'organic milk') |
| `store_id` | string | No | Walmart store ID (e.g. '3081') to lock search results to a specific physical store. Obtainable from get_store_locations. When provided, only products priced and available at that exact store are returned; if the store cannot serve results, an empty list is returned. Either store_id or zip_code must be provided. |
| `zip_code` | string | No | 5-digit US ZIP code for store-specific results (e.g. '27401'). Either zip_code or store_id must be provided. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-walmart-com-api-0f0af915/search_grocery_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>","store_id":"<string>","zip_code":"<string>"}'
```

### search_products

Full-text search over Walmart product catalog. Returns paginated product summaries with price, rating, and availability badges. Supports sorting and facet filtering. Each ProductSummary can be drilled into via get_product_details for full specifications.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `filters` | string | No | Facet filter string to narrow results (e.g. 'brand:Samsung') |
| `page` | integer | No | Page number for pagination |
| `query` | string | Yes | Search keyword (e.g. 'laptop', 'wireless headphones') |
| `sort` | string | No | Sort order for results |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-walmart-com-api-0f0af915/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":"<string>","page":"<integer>","query":"<string>","sort":"<string>"}'
```