| name | waitrose-cli |
| description | Manage Waitrose grocery shopping using the waitrose CLI. Use when users mention Waitrose, grocery shopping, delivery slots, trolley/cart management, or order history. |
Waitrose CLI
CLI tool for interacting with Waitrose & Partners grocery API.
Important: Always Use JSON Output
Always prefix commands with WAITROSE_JSON_OUTPUT=true for comprehensive, parseable output:
WAITROSE_JSON_OUTPUT=true waitrose <command>
Authentication
Always check waitrose status first. If already logged in, skip login.
waitrose status
waitrose login -u email@example.com -p password
waitrose logout
Session stored in ~/.waitrose/session.json and auto-refreshes.
Searching Products
Search for products before adding to trolley:
waitrose search "organic eggs" --json
waitrose search "sirloin steak" -l 5 --json
The search results include:
id: The product-id needed for adding to trolley (e.g., "468390-810671-810672")
lineNumber: First part of the product-id
name: Product name
displayPrice: Price display (e.g., "£3.50" or "per kg")
size: Package size
Product Details
Get full product details (ingredients, nutrition, attributes, etc.):
waitrose product get <lineNumber> --json
Useful fields in the JSON payload:
contents.marketingDescBop: Long description
contents.ingredients: Ingredients list (HTML)
contents.nutrients: Nutrition data
attributes: Dietary/allergen-related flags
Quick jq filters
waitrose product get <lineNumber> --json | jq -r '.contents.marketingDescBop, .contents.ingredients'
waitrose product get <lineNumber> --json | jq -r '.contents.nutrients.nutrientsData[] | "\(.name): \(.valuePerUnit) (\(.valuePerServing))"'
waitrose product get <lineNumber> --json | jq -r '.categories[] | "\(.id) - \(.name)"'
waitrose product get <lineNumber> --json | jq -r '.barCodes[]'
waitrose product get <lineNumber> --json | jq -r '.attributes | to_entries[] | select(.value==true) | .key'
Trolley Management
View Trolley
waitrose trolley
waitrose trolley --json
Add Items
Add items using the product-id from search results:
waitrose trolley add <product-id>
waitrose trolley add 468390-810671-810672 --qty 2
waitrose search "organic broccoli" --json
waitrose trolley add 477602-428563-67380
| Flag | Default | Description |
|---|
--qty | 1 | Quantity to add |
--uom | C62 | Unit of measure (C62=each, KGM=per kg) |
Update Item Quantity
waitrose trolley update 468390-810671-810672 --qty 2
waitrose trolley update 468390-810671-810672 --qty 0.5 --uom KGM
| Flag | Default | Description |
|---|
--qty | required | New quantity to set |
--uom | C62 | Unit of measure (C62=each, KGM=per kg) |
Remove Items
waitrose trolley remove 468390-810671-810672
waitrose trolley remove 468390-810671-810672 --qty 1
waitrose trolley remove 468390-810671-810672 --qty 0.5 --uom KGM
| Flag | Default | Description |
|---|
--qty | 0 | Quantity to remove (0 = remove all) |
--uom | item's UOM | Unit of measure |
Addresses
Get address IDs before working with delivery slots:
waitrose address list
Delivery Slots
For delivery slots, --address is required:
waitrose slot list --address <address-id>
waitrose slot list --address <address-id> --days 7 --from 2025-01-01
waitrose slot book <slot-id> --address <address-id>
waitrose slot get
waitrose slot cancel
waitrose slot cancel <reservationId>
Slot List Flags
| Flag | Default | Description |
|---|
--address | - | Delivery address ID (required for delivery) |
--days | 7 | Number of days to fetch (max 7) |
--from | today | Start date (YYYY-MM-DD) |
--slot-type | DELIVERY | Slot type |
--grid | DEFAULT_GRID | Slot grid type |
Orders
waitrose order list -l 10
waitrose order get <order-number>
Version
waitrose version
Global Flags
| Flag | Description |
|---|
--api-key | Waitrose API key (or WAITROSE_API_KEY env) |
-j, --json | Output in JSON format |
Environment Variables
| Variable | Description |
|---|
WAITROSE_API_KEY | API key (optional, has default) |
WAITROSE_USERNAME | Email for login |
WAITROSE_PASSWORD | Password for login |
WAITROSE_JSON_OUTPUT | Set to "true" for JSON output by default |
Troubleshooting
"failed to add item: item may be out of stock or unavailable for delivery (500)"
This error occurs when:
- Item is out of stock - Search for alternatives
- Variable weight item - Items priced "per kg" (whole lamb legs, fish counters) often fail. Look for fixed-weight packaged alternatives instead
- No delivery slot booked - Some items require an active slot reservation
"invalid product-id format"
Product IDs must be in format lineNumber-xxx-xxx (e.g., 468390-810671-810672). Get the full ID from search results with --json flag.
Items not appearing in trolley
After adding, verify with waitrose trolley --json. The add command may report success but the API can silently reject items (especially variable-weight products).
Slot booking fails
- Ensure you have a valid address ID (
waitrose address list)
- Check slot availability first (
waitrose slot list)
Completing the Shopping Experience
After finishing a grocery shopping session (adding items to trolley, booking a slot, etc.), always show the user the trolley link so they can review and checkout:
https://www.waitrose.com/ecom/shop/trolley
This allows users to verify their order, apply promotions, and complete checkout on the Waitrose website.