### Install iLidl via CLI

Source: https://github.com/rorydotgg/ilidl/blob/main/README.md

Instructions for installing the iLidl package using pip or uv, including the optional authentication dependency for Playwright-based login flows.

```bash
pip install ilidl
uv add ilidl
pip install "ilidl[auth]"
playwright install chromium
```

--------------------------------

### Install iLidl and Authentication Support

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Installs the iLidl library using pip or uv. The '[auth]' extra installs dependencies for authentication, which requires Playwright for browser-based login. Playwright browsers must also be installed.

```bash
# Basic installation
pip install ilidl

# Or with uv
uv add ilidl

# With authentication support (requires Playwright for browser-based login)
pip install "ilidl[auth]"
playwright install chromium
```

--------------------------------

### Manage Receipts and Coupons via CLI

Source: https://github.com/rorydotgg/ilidl/blob/main/README.md

Command-line interface examples for retrieving receipt history and managing coupon activations. Supports JSON output for integration with other tools.

```bash
ilidl receipt latest --json
ilidl receipts --from 2026-03-01
ilidl coupons list
ilidl coupons activate --all
```

--------------------------------

### GET /coupons

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Fetch all available coupons from the Lidl Plus account, including activation status and validity dates.

```APIDOC
## GET /coupons

### Description
Retrieves a list of all coupons associated with the authenticated Lidl Plus account.

### Method
GET

### Endpoint
/coupons

### Response
#### Success Response (200)
- **coupons** (List) - A list of Coupon objects containing id, title, description, start_date, end_date, and is_activated status.

#### Response Example
{
  "coupons": [
    {
      "id": "promo-abc123",
      "title": "10% off Fresh Produce",
      "is_activated": false
    }
  ]
}
```

--------------------------------

### Get Specific Receipt Details with LidlClient

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Fetches detailed information for a single receipt using its ID. This includes a full item breakdown, store details, payment method, and VAT information. UK receipts are automatically parsed from HTML into a structured format. The example demonstrates accessing various attributes of the returned Receipt object.

```python
from ilidl import LidlClient

client = LidlClient(refresh_token="...", country="GB", language="en")

# Fetch specific receipt by ID
receipt = client.receipt("abc123-def456-789")

# Access receipt data
print(f"Receipt ID: {receipt.id}")
print(f"Date: {receipt.date.strftime('%Y-%m-%d %H:%M')}")
print(f"Store: {receipt.store.name}, {receipt.store.locality}")
print(f"Address: {receipt.store.address}, {receipt.store.postal_code}")
print(f"Payment: {receipt.payment_method}")

# Iterate through items
for item in receipt.items:
    print(f"  {item.name}: £{item.price:.2f}")
    print(f"    Quantity: {item.quantity}, Unit Price: {item.unit_price}")
    print(f"    VAT Group: {item.vat_group}")

    # Check for discounts on item
    for discount in item.discounts:
        print(f"    Discount: {discount.description} -£{discount.amount:.2f}")

print(f"Total: £{receipt.total:.2f}")

# Access VAT breakdown
for vat_type, (base, amount) in receipt.vat_breakdown.items():
    print(f"VAT {vat_type}: Base £{base:.2f}, Tax £{amount:.2f}")
```

--------------------------------

### List All Receipts with LidlClient

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Fetches all receipts from a Lidl Plus account, supporting automatic pagination. It returns a list of Receipt objects, each containing a summary of the receipt. The `only_favourite` parameter can be used to filter for starred receipts only. The example shows how to access basic receipt information.

```python
from ilidl import LidlClient

client = LidlClient(refresh_token="...", country="GB", language="en")

# Get all receipts
all_receipts = client.receipts()

# Get only favourite/starred receipts
favourites = client.receipts(only_favourite=True)

# Process receipts
for receipt in all_receipts:
    print(f"ID: {receipt.id}")
    print(f"Date: {receipt.date}")
    print(f"Store: {receipt.store.id}")
    print(f"Total: {receipt.total} {receipt.currency}")
    print("---")

# Example output:
# ID: abc123-def456
# Date: 2024-03-15 14:30:00+00:00
# Store: 12345
# Total: 45.67 GBP
```

--------------------------------

### Get Most Recent Receipt with LidlClient

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Retrieves the most recent receipt from the user's account. This is a convenience method that simplifies fetching the latest transaction. It returns a full Receipt object, similar to `client.receipt()`. An `ILidlError` is raised if no receipts are found in the account.

```python
from ilidl import LidlClient
from ilidl.exceptions import ILidlError

client = LidlClient(refresh_token="...", country="GB", language="en")

try:
    receipt = client.latest_receipt()

    print(f"Latest receipt from {receipt.date.strftime('%Y-%m-%d')}")
    print(f"Store: {receipt.store.name}")

    for item in receipt.items:
        print(f"  {item.name}: £{item.price:.2f}")

    print(f"Total: £{receipt.total:.2f}")

except ILidlError as e:
    print(f"Error: {e}")
```

--------------------------------

### Interact with Lidl Plus API via Python

Source: https://github.com/rorydotgg/ilidl/blob/main/README.md

Demonstrates how to initialize the LidlClient and perform common tasks like fetching the latest receipt and listing available coupons programmatically.

```python
from ilidl import LidlClient

client = LidlClient(refresh_token="...", country="GB", language="en")

# Get latest receipt with parsed items
receipt = client.latest_receipt()
for item in receipt.items:
    print(f"{item.name}: {item.price}")

# List coupons
for coupon in client.coupons():
    print(f"{coupon.title} (active: {coupon.is_activated})")
```

--------------------------------

### Initialize Receipt and Coupon Data Models

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Demonstrates how to instantiate the Receipt and Coupon dataclasses. These models are used to structure data retrieved from the Lidl API, facilitating easy serialization and data manipulation.

```python
from datetime import datetime

receipt = Receipt(
    id="abc123",
    date=datetime.now(),
    store=Store(
        id="12345",
        name="Lidl London",
        address="123 High Street",
        postal_code="SW1A 1AA",
        locality="London"
    ),
    items=[
        Item(
            name="Bread",
            price=1.50,
            vat_group="A",
            quantity=1.0,
            unit_price=1.50,
            discounts=[Discount(description="Price Match", amount=0.10)]
        )
    ],
    total=1.40,
    currency="GBP",
    payment_method="Card",
    vat_breakdown={"A": (1.40, 0.07)}
)

coupon = Coupon(
    id="promo123",
    title="10% off",
    start_date=datetime(2024, 3, 1),
    end_date=datetime(2024, 3, 31),
    is_activated=False,
    description="10% off fresh produce",
    image_url="https://example.com/coupon.jpg"
)
```

--------------------------------

### Authenticate with Lidl Plus

Source: https://github.com/rorydotgg/ilidl/blob/main/README.md

Command to initiate the OAuth authentication flow. This launches a headless browser to capture the refresh token, which is then stored locally for subsequent API requests.

```bash
ilidl login
```

--------------------------------

### Manage Coupons via CLI

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Command-line interface for listing, activating, and deactivating Lidl Plus coupons. Includes options for bulk activation and JSON output.

```bash
ilidl coupons list --json
ilidl coupons activate promo-abc123
ilidl coupons activate --all
ilidl coupons deactivate promo-abc123
```

--------------------------------

### Configure iLidl via TOML

Source: https://github.com/rorydotgg/ilidl/blob/main/README.md

The configuration file structure used by iLidl to store authentication tokens and account preferences like language and country code.

```toml
[auth]
refresh_token = "..."

[account]
language = "en"
country = "GB"
```

--------------------------------

### CLI Authentication with iLidl

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Logs into Lidl Plus using the command-line interface. This command initiates an interactive login process that prompts the user for their phone number and a verification code, launching a headless browser for authentication. A debug mode is available to save screenshots for troubleshooting.

```bash
# Run interactive login - prompts for phone number and verification code
ilidl login

# With debug mode to save screenshots for troubleshooting
ilidl login --debug
```

--------------------------------

### Fetch and List Coupons with Python

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Retrieves all available coupons from a Lidl Plus account using the LidlClient. Returns a collection of Coupon objects containing details like activation status, validity dates, and descriptions.

```python
from ilidl import LidlClient

client = LidlClient(refresh_token="...", country="GB", language="en")

coupons = client.coupons()

for coupon in coupons:
    print(f"ID: {coupon.id}")
    print(f"Title: {coupon.title}")
    print(f"Description: {coupon.description}")
    print(f"Valid: {coupon.start_date.date()} to {coupon.end_date.date()}")
    print(f"Activated: {coupon.is_activated}")
    if coupon.image_url:
        print(f"Image: {coupon.image_url}")
    print("---")

# Filter to inactive coupons only
inactive = [c for c in coupons if not c.is_activated]
print(f"Found {len(inactive)} coupons to activate")
```

--------------------------------

### Configure ilidl Programmatically

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Utilizes the Config class to load, modify, and save account settings stored in TOML format. Allows for custom configuration paths and updates to authentication tokens.

```python
from ilidl.config import Config
from pathlib import Path

# Load default configuration
config = Config()

# Modify and save configuration
config.country = "DE"
config.language = "de"
config.refresh_token = "new_token_here"
config.save()
```

--------------------------------

### Initialize LidlClient in Python

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Initializes the LidlClient for interacting with the Lidl Plus API. The client can be configured with a refresh token, country, and language. It handles automatic token renewal and connection retries. The client can be used as a context manager for automatic resource cleanup or manually closed.

```python
from ilidl import LidlClient

# Basic initialization
client = LidlClient(
    refresh_token="your_refresh_token_here",
    country="GB",
    language="en"
)

# Use as context manager for automatic cleanup
with LidlClient(
    refresh_token="your_refresh_token_here",
    country="GB",
    language="en",
    app_version="16.45.5"  # Optional, defaults to current version
) as client:
    # Use client
    receipts = client.receipts()

# Manual cleanup
client.close()
```

--------------------------------

### POST /coupons/{id}/activate

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Activate a specific coupon by its unique identifier to enable it for checkout.

```APIDOC
## POST /coupons/{id}/activate

### Description
Activates a specific coupon by its ID. Raises an HTTP error if the operation fails.

### Method
POST

### Endpoint
/coupons/{id}/activate

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the coupon.

### Response
#### Success Response (200)
- **status** (string) - Confirmation of activation.
```

--------------------------------

### Manage Receipts via CLI

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Commands to list, filter, and retrieve receipt details from the command line. Supports table output or JSON format for integration with other scripts.

```bash
ilidl receipts
ilidl receipts --from 2024-03-01 --to 2024-03-15
ilidl receipts --json
ilidl receipt latest
ilidl receipt abc123-def456-789 --json
```

--------------------------------

### Activate and Deactivate Coupons with Python

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Manages coupon activation states using the LidlClient. These methods require a valid coupon ID and may raise HTTPStatusError if the request fails.

```python
from ilidl import LidlClient
import httpx

client = LidlClient(refresh_token="...", country="GB", language="en")

# Activate a single coupon
coupon_id = "promo-abc123"
try:
    client.activate_coupon(coupon_id)
    print(f"Coupon {coupon_id} activated successfully")
except httpx.HTTPStatusError as e:
    print(f"Failed to activate coupon: {e.response.status_code}")

# Deactivate a coupon
try:
    client.deactivate_coupon(coupon_id)
    print(f"Coupon {coupon_id} deactivated")
except httpx.HTTPStatusError as e:
    print(f"Failed to deactivate: {e.response.status_code}")
```

--------------------------------

### Access Data Models

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Imports type-safe dataclass models used for parsing API responses within the ilidl library.

```python
from ilidl import Receipt, Item, Store, Coupon, Discount
from datetime import datetime
```

--------------------------------

### Handle iLidl API Exceptions

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Provides a robust pattern for catching specific library exceptions such as AuthError and ReceiptParseError, alongside standard HTTP errors. This ensures applications can gracefully handle authentication failures or data parsing issues during API calls.

```python
from ilidl import LidlClient
from ilidl.exceptions import ILidlError, AuthError, ReceiptParseError
import httpx

try:
    client = LidlClient(refresh_token="invalid_token", country="GB", language="en")
    receipt = client.latest_receipt()
except AuthError as e:
    print(f"Authentication error: {e}")
except ReceiptParseError as e:
    print(f"Parse error: {e}")
except ILidlError as e:
    print(f"iLidl error: {e}")
except httpx.HTTPStatusError as e:
    print(f"HTTP error: {e.response.status_code} - {e.response.text}")
```

--------------------------------

### POST /coupons/{id}/deactivate

Source: https://context7.com/rorydotgg/ilidl/llms.txt

Deactivate a previously activated coupon by its unique identifier.

```APIDOC
## POST /coupons/{id}/deactivate

### Description
Deactivates a previously activated coupon. Raises an HTTP error if the operation fails.

### Method
POST

### Endpoint
/coupons/{id}/deactivate

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the coupon.

### Response
#### Success Response (200)
- **status** (string) - Confirmation of deactivation.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.