canonical: https://jentic.com/apis/kroger.com/kroger

# Kroger API

Jentic publishes the only available OpenAPI specification for Kroger API, keeping it validated and agent-ready. The Kroger Public API exposes 8 endpoints for searching products, looking up store locations across the Kroger family of supermarket banners, adding items to a shopper's cart, and reading the authenticated customer profile. Authentication uses OAuth 2.0 with both client-credentials and authorization-code flows, plus HTTP Basic for the token endpoint, so partner apps can mix anonymous product browsing with authenticated cart and identity calls. Kroger operates more than 2,700 stores in the United States, and the location endpoints accept ZIP, latitude/longitude, and chain filters.

## For AI agents

Search Kroger products, find nearby stores, look up the authenticated shopper's profile, and add items to their cart through OAuth-protected endpoints.

## Scope

Does not handle order checkout, payment, delivery routing, or loyalty redemption - use for product search, store location, identity, and cart-add only.

## Capabilities

- Search the Kroger product catalogue by term, location, brand, and fulfillment method
- Retrieve detailed product information by product ID including pricing per store location
- Search store locations by ZIP code, latitude/longitude, chain, or department availability
- Get full details for a single store location including services and operating hours
- Add one or more product UPCs to the authenticated customer's Kroger cart
- Read the authenticated customer's profile identifier for personalised experiences

## Use cases

### Recipe-to-cart shopping experience

A meal-planning app converts a recipe into Kroger UPCs by searching the product catalogue with /products, then uses PUT `/cart/add` to drop the matched items into the authenticated shopper's cart for pickup or delivery. Kroger handles inventory, pricing, and fulfilment options. The integration is typically built in 3-5 days once OAuth client credentials are issued.

Example prompt: Call GET /products?filter.term=organic+spinach&filter.locationId=01400376 to find a UPC, then PUT `/cart/add` with that UPC and quantity 1.

### Store locator for delivery and pickup

A retail app uses /locations to render a list of nearby Kroger banners - Kroger, Ralphs, King Soopers, Fred Meyer, and others - filtered by ZIP, distance, and available services such as pharmacy or fuel. The `/locations/{locationId}` endpoint returns hours and amenity flags so the app can pick the right pickup window. This pattern serves the bulk of the API's external traffic.

Example prompt: Call GET /locations?filter.zipCode.near=45202&filter.radiusInMiles=10 and return the names, addresses, and pharmacy availability of the matching stores.

### Personalised product browsing

An authenticated shopping experience reads the shopper profile from `/identity/profile` and combines it with location-scoped product searches to surface store-specific pricing, promotions, and availability. The OAuth authorization-code flow links the shopper's Kroger identity to the partner app while keeping credentials on Kroger.

Example prompt: After completing the OAuth authorization-code flow, call GET `/identity/profile` and use the returned profileId to scope subsequent product queries.

### Agent-driven grocery ordering via Jentic

An assistant agent searches Jentic for 'add items to grocery cart' and is matched to PUT `/cart/add` along with the product search and location operations needed to resolve UPCs. Jentic handles the OAuth token refresh on the agent's behalf so the agent can compose 'find the nearest Kroger, search for these items, add them to my cart' as a single workflow.

Example prompt: Use the Jentic MCP tool kroger_add_to_cart to add UPCs ['0001111041700','0007003820027'] with quantity 2 each to the authenticated shopper's cart.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/connect/oauth2/token` | Issue an OAuth access token |
| GET | `/connect/oauth2/authorize` | Start the authorization-code flow |
| GET | `/products` | Search products by term and location |
| GET | `/products/{productId}` | Get product details by ID |
| GET | `/locations` | Search store locations |
| GET | `/locations/{locationId}` | Get a specific store location |
| PUT | `/cart/add` | Add items to the authenticated cart |
| GET | `/identity/profile` | Get the authenticated customer profile |

## Key resources

- **OAuth** — Token issuance and authorization endpoints for client-credentials and authorization-code flows
- **Products** — Search the Kroger product catalogue and retrieve per-product details
- **Locations** — Search Kroger store locations and read per-store details and services
- **Cart** — Add items to the authenticated shopper's cart
- **Identity** — Read the authenticated customer's profile identifier

## Why Jentic

- **Setup:** Wiring the Kroger API by hand means running the OAuth2 flow, base64-encoding client_id:client_secret for the token request, tracking scopes like product.compact and cart.basic:write, and refreshing access tokens against api.kroger.com yourself. Through Jentic you install once, import the Kroger API from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** Kroger gates access by OAuth scope and its write targets travel in the request body, so scope the agent to the operations it needs, such as searching products and finding store locations. You choose that set, so the cart-add operation is not included unless you add it.
- **Credential handling:** Your Kroger client id, client secret, and refresh tokens are stored once, encrypted, by your own Jentic One instance, which refreshes access tokens at execution time. The secrets never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find nearby Kroger stores' or 'search grocery products', and Jentic returns the matching Kroger operation with its required scopes and parameters so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Walmart** — Larger US grocery and general retail catalogue with comparable product and location APIs
- **Shopify** — Generic e-commerce storefront API used by independent grocery merchants
- **Stripe** — Handles payment authorisation for partner experiences that bridge to a checkout outside Kroger
- **Mailchimp** — Email platform used to deliver receipts and pickup notifications to Kroger shoppers

## FAQ

### Why is there no official OpenAPI spec for Kroger API?

Kroger does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Kroger API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Kroger API use?

Kroger uses OAuth 2.0 with both client-credentials and authorization-code grants - product and location search work with client credentials, while `/cart/add` and `/identity/profile` require authorization-code tokens scoped to the shopper. The token endpoint authenticates with HTTP Basic. Jentic stores the client secret and refresh tokens encrypted in your Jentic One instance.

### Can I add items to a Kroger shopper's cart with the Kroger API?

Yes. PUT `/cart/add` accepts a list of items, each with a UPC and quantity, against the OAuth token of the authorised shopper. The shopper must have completed the authorization-code flow first so the token carries the cart.basic:write scope.

### What are the rate limits for the Kroger API?

Kroger enforces a daily call limit per developer application - typically 10,000 calls per day for the standard tier - with separate ceilings for product search, location search, and cart endpoints. Refer to developer.kroger.com for exact figures and design batched calls where possible.

### How do I search for products in a specific store through Jentic?

Search Jentic for 'kroger product search', load GET /products, and execute it with filter.term and filter.locationId. The locationId can be sourced from a prior call to GET /locations. Install with pip install jentic.

### Does the Kroger API support placing a final order or checkout?

No. The Public API stops at adding items to the cart. Final checkout, payment, fulfilment selection, and order tracking happen inside the Kroger app or website - there is no public endpoint that submits an order.

### Can I limit what my agent is allowed to do with the Kroger API?

Yes. Because you run Jentic One yourself, you decide which Kroger operations the agent may call, so you can grant only product search (GET /products) and store lookup (GET /locations) while withholding the cart-add operation (PUT `/cart/add`). Kroger enforces this at the OAuth scope level and its write targets travel in the request body, so the agent never gets the cart or identity operations unless your own rules add them. Your Kroger client id, secret, and refresh tokens stay under your control and are never placed in the agent's prompt or context.