Kroger API Skill

Kroger/QFC API Skill

Overview

Skill for searching Kroger/QFC products, managing cart, checking pickup availability, and creating pickup orders. Uses official Kroger API. QFC chain ID: 213.

Setup

1. Sign up at developer.kroger.com, create app.
2. Add redirect URI e.g. http://localhost
3. Scopes: product.compact locations.read fulfillment.readwrite orders.pickup.create
4. Edit state.json: add client_id, client_secret, chain_id: "213"
5. OAuth:
   • python3 scripts/client.py --state state.json oauth-url
   • Visit URL, login, authorize.
   • Copy code from redirect (e.g. http://localhost?code=ABC123)
   • python3 scripts/client.py --state state.json oauth-exchange ABC123

Usage (via exec)

Run from workspace root:

Search products

python3 kroger-api.skill/scripts/client.py search \"milk\" --chain-id 213 --limit 5

Output: JSON products with id (UPC), attributes.description, attributes.brand etc.

Find locations

python3 kroger-api.skill/scripts/client.py locations 98101 --chain-id 213

Output: locations with id, attributes.address.addressLine1 etc.

Cart (local)

python3 kroger-api.skill/scripts/client.py cart-add 0001111101001 2  # UPC qty
python3 kroger-api.skill/scripts/client.py cart-get
python3 kroger-api.skill/scripts/client.py cart-clear

Check availability

python3 kroger-api.skill/scripts/client.py availability LOC123 --items '[{"upc":"UPC","quantity":1}]'

Create order

python3 kroger-api.skill/scripts/client.py order-create LOC123 \"2026-02-14T10:00:00Z\" --items '[{"upc":"UPC","quantity":1}]'

Grocery list integration

Create grocery-list.txt:

milk
bread
eggs

python3 kroger-api.skill/scripts/client.py grocery --zip 98101

Lists items & locations. Agent: for each item search, pick UPC (e.g. first result), add_to_cart, then availability, order.

Agent Workflow Example

1. User: "Add milk and eggs to Kroger cart"
2. Search "milk", pick UPC1, cart-add
3. Search "eggs", pick UPC2, cart-add
4. User: "Find QFC near 98101" → locations
5. Set location-set LOC
6. cart-get → items
7. availability → pick slot
8. order-create with slot time.

State

state.json: tokens, cart, location_id.

Notes

• Endpoints based on Kroger API docs. Verify at developer.kroger.com/reference
• UPC from products.id
• Pickup datetime: ISO 8601 UTC
• Errors: check API response
• Token auto-refreshes.

Package as kroger-api.skill/