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

> Find Kroger grocery store locations across the US organized by state, city, and search parameters. Get detailed store information including directories and specifics for any Kroger location in your area.

**Category:** Food & Dining | **Website:** [www.kroger.com/stores/grocery](https://www.kroger.com/stores/grocery) | **Docs:** [parse.bot/marketplace/9df31a3b-8dbe-41a3-94c3-c11ce52668b7/kroger-com-api](https://parse.bot/marketplace/9df31a3b-8dbe-41a3-94c3-c11ce52668b7/kroger-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/kroger/`
**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 all stores

Get the complete directory of all Kroger grocery stores grouped by state. Returns all states with their cities and store counts. The optional state filter narrows results to matching states (partial, case-insensitive). Returns a single Directory object, not a list.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `state` | string | No | Filter by state name (partial match, case-insensitive). Omitting returns all states. |

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

### Get stores by city

Get detailed store information for all Kroger grocery stores in a specific city. Returns full store records including address, phone, hours, departments, and coordinates. The city and state combination must match a valid entry in the Kroger store directory.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | Yes | City name, lowercased (e.g. 'acworth', 'atlanta', 'little rock') |
| `state` | string | Yes | Two-letter state abbreviation, lowercased (e.g. 'ga', 'oh', 'tx') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/kroger/get-stores-by-city \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","state":"<string>"}'
```

### Search stores

Search for Kroger stores by location query (city name, zip code, or address). Returns stores near the searched location. Results include all store types in the Kroger family (grocery, fuel, shell). Pagination via page_size and page_offset.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page_offset` | integer | No | Pagination offset (number of results to skip) |
| `page_size` | integer | No | Number of results per page |
| `query` | string | Yes | Search query - city name, zip code, or address (e.g. 'Atlanta', '30301') |

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