Skip to content
ConorSmalleyPublic
forked from FaserF/ha-lidl

About

A Home Assistant integration that fetches weekly offers, discounts, upcoming deal previews, active coupons, and digital receipts for your local Lidl store directly from the official Lidl Plus API.

Resources

Stars

0 stars

Watchers

0 watching

Forks

ย 
ย 

Latest commit

ย 

History

96 Commits

Folders and files

Repository files navigation

Lidl Weekly Offers (for Home Assistant) ๐Ÿ›’

A secure, robust Home Assistant integration that fetches weekly offers, discounts, upcoming deal previews, coupons, and digital receipts for your local Lidl store directly from the official Lidl Plus API.

Home Assistant Marketplace Downloads (Current release) GitHub Release License


๐Ÿงญ Quick Links

โœจ Features ๐Ÿ“ฆ Installation โš™๏ธ Configuration ๐Ÿ” Lidl Plus Login
๐Ÿ› ๏ธ Options ๐Ÿง‘โ€๐Ÿ’ป Development ๐Ÿ“„ License

Why use this integration?

Instead of scraping brittle public HTML pages (which constantly break) or using heavy headless browser setups, this integration connects directly to Lidl's official mobile app backend endpoints. By utilizing curl_cffi for advanced TLS fingerprinted client impersonation, it retrieves structured weekly store brochures and discount offers in real-time.


๐Ÿ›’ Supermarket Family & Deals Hub

Check out our full collection of Home Assistant supermarket integrations and the multi-store aggregator:

Repository Description
๐Ÿท๏ธ Grocery Deals (ha-grocery-deals) Smart multi-store price comparison hub (aggregates all 5 integrations)
๐Ÿ”ด ha-rewe REWE weekly offers, bonus points, coupons & product filters
๐ŸŸก ha-edeka EDEKA weekly offers, discounts & PAYBACK card
โšช ha-aldi ALDI Sรผd & ALDI Nord weekly flyers & brochures
๐Ÿ”ด ha-norma Norma weekly store discounts & flyer offers

It groups all sensors under a single market device and implements advanced lock-serialization, random jitter delays, storage caching, and exponential backoffs to keep your setup secure and prevent rate-limiting bans.


โœจ Features

  • ๐Ÿ›’ Detailed Offers Sensors:
    • Offers: Current week's discounted items count, with attributes detailing titles, brands, categories, prices (original & discount), packaging units, unit prices, and direct links to product images.
    • Offers Preview: Next week's upcoming deals.
  • ๐Ÿ” Lidl Plus Features (requires login):
    • Loyalty Card QR Code Image (image): A dynamic 300x300 PNG QR Code entity rendering your 17-digit barcode for scanning directly at the checkout. Includes state attributes for your full profile (user_name, email, country, registration_date).
    • Activated & Available Coupons: Sensors for currently active and available coupons, broken down by store vs. online shop coupons.
    • Activate All Coupons: A button entity to activate every available coupon with a single tap.
    • Last Receipt: Shows total amount, date, store code, article count, and redeemed coupon counts.
  • ๐Ÿ“ฑ Single Lidl Plus Account Device per Country:
    • All account-level entities (Loyalty Card QR Code, Activated Coupons, Available Coupons, Last Receipt, Activate All Coupons) are grouped under a dedicated Lidl Plus Account (DE) device.
    • Features a direct Visit Lidl Plus Account button taking you directly to your web account management portal.
  • ๐Ÿ›ก๏ธ Rate-Limiting & Anti-Ban Protections:
    • First-Fetch Optimisation: Skips jitter sleep on initial setup so the first refresh completes instantly.
    • Lock Queueing: A domain-wide lock ensures concurrent updates run sequentially.
    • Random Jitter: Introduces a 5โ€“15 second delay between requests.
    • Restart-Resistance: Saves parsed data to Home Assistant's JSON storage cache to survive restarts without hitting the API.
    • Exponential Backoff: Backs off for up to 24 hours on 403/429 blocks, and minutes on network failures.
  • โš™๏ธ Store-Based Device Grouping:
    • Store-specific offer sensors (Offers, Offers Preview, Force Update) are grouped under their respective Lidl Store device.
    • Visit Lidl Store Button: The store device registry provides a dynamic configuration URL pointing directly to your local store page.
  • ๐ŸŽ›๏ธ Manual Force Update:
    • A Force Update button entity allows manually triggering an API update on demand (disabled by default to avoid accidental triggers).
  • ๐Ÿ” Diagnostic Downloads:
    • Full support for Home Assistant UI Diagnostics. Download complete configurations with identifiers and session details automatically redacted.

โค๏ธ Support This Project

I maintain this integration in my free time alongside my regular job.

This project is and will always remain 100% free.

Donations are completely voluntary โ€” but they help me stay motivated and dedicate more time to maintaining open-source tools!

PayPal


๐Ÿ”Œ Recommended Hardware & Ecosystem Links

Device / Service Integration Use Case Link
Home Assistant Green & Official Hardware Recommended hardware foundation for local Home Assistant integrations Official Device Page โ†’
Home Assistant Connect ZBT-1 (Zigbee / Thread) Local Zigbee2MQTT, ZHA & Matter-over-Thread wireless mesh Official Device Page โ†’

๐Ÿ“ฆ Installation

Home Assistant Marketplace (Recommended)

This integration is available via the official Home Assistant Marketplace (HA 2026.11+) or as a custom repository.

  1. Open Marketplace in Home Assistant.
  2. Click on the three dots in the top right corner and select Custom repositories.
  3. Add FaserF/ha-lidl with category Integration.
  4. Search for "Lidl Weekly Offers".
  5. Install and restart Home Assistant.

Open Marketplace

Manual Installation

  1. Download the latest release zip file.
  2. Extract the custom_components/lidl folder into your Home Assistant's custom_components directory.
  3. Restart Home Assistant.

๐ŸŒ Supported Countries

This integration supports 28 countries operating on the Lidl Plus API infrastructure:

Country Code Country Code Country Code
๐Ÿ‡ฆ๐Ÿ‡น Austria AT ๐Ÿ‡ง๐Ÿ‡ช Belgium BE ๐Ÿ‡ง๐Ÿ‡ฌ Bulgaria BG
๐Ÿ‡จ๐Ÿ‡ญ Switzerland CH ๐Ÿ‡จ๐Ÿ‡ฟ Czech Republic CZ ๐Ÿ‡ฉ๐Ÿ‡ช Germany DE
๐Ÿ‡ฉ๐Ÿ‡ฐ Denmark DK ๐Ÿ‡ช๐Ÿ‡ช Estonia EE ๐Ÿ‡ช๐Ÿ‡ธ Spain ES
๐Ÿ‡ซ๐Ÿ‡ฎ Finland FI ๐Ÿ‡ซ๐Ÿ‡ท France FR ๐Ÿ‡ฌ๐Ÿ‡ง United Kingdom GB
๐Ÿ‡ฌ๐Ÿ‡ท Greece GR ๐Ÿ‡ญ๐Ÿ‡ท Croatia HR ๐Ÿ‡ญ๐Ÿ‡บ Hungary HU
๐Ÿ‡ฎ๐Ÿ‡ช Ireland IE ๐Ÿ‡ฎ๐Ÿ‡น Italy IT ๐Ÿ‡ฑ๐Ÿ‡น Lithuania LT
๐Ÿ‡ฑ๐Ÿ‡บ Luxembourg LU ๐Ÿ‡ฑ๐Ÿ‡ป Latvia LV ๐Ÿ‡ณ๐Ÿ‡ฑ Netherlands NL
๐Ÿ‡ต๐Ÿ‡ฑ Poland PL ๐Ÿ‡ต๐Ÿ‡น Portugal PT ๐Ÿ‡ท๐Ÿ‡ด Romania RO
๐Ÿ‡ธ๐Ÿ‡ช Sweden SE ๐Ÿ‡ธ๐Ÿ‡ฎ Slovenia SI ๐Ÿ‡ธ๐Ÿ‡ฐ Slovakia SK
๐Ÿ‡บ๐Ÿ‡ธ United States US

Note for US users: Lidl Plus launched in the United States in 2026. The US region uses the same shared Lidl Plus API infrastructure (stores.lidlplus.com, offers.lidlplus.com) as European countries. The Accept-Language header is automatically set to en-US and the website link resolves to lidl.com.

โŒ Unsupported Countries & Technical Reasons

  • ๐Ÿ‡จ๐Ÿ‡ฆ / ๐Ÿ‡ฆ๐Ÿ‡บ / ๐Ÿ‡ณ๐Ÿ‡ฟ / ๐Ÿ‡ฏ๐Ÿ‡ต / ๐Ÿ‡จ๐Ÿ‡ณ / Non-Lidl countries: Lidl does not operate stores or Lidl Plus mobile services in these regions.

โš™๏ธ Configuration

  1. Navigate to Settings > Devices & Services in Home Assistant.
  2. Click Add Integration and search for Lidl Weekly Offers.

Add Integration

  1. Select your country.
  2. Enter your ZIP code or city name to search for nearby Lidl stores.
  3. (Optional) Check Log in to Lidl Plus to enable personal features โ€” see below.
  4. Select your specific store from the dropdown list.
  5. Submit to create the device and entities.

๐Ÿ” Lidl Plus Login (optional)

Logging in to your Lidl Plus account enables additional sensors and the coupon activation button. Without a login, only the public weekly offers are available.


๐Ÿ—๏ธ How Lidl's Authentication Works

Lidl uses OAuth 2.0 with PKCE (Proof Key for Code Exchange), designed exclusively for their mobile app. Key constraints that affect this integration:

Constraint Effect
redirect_uri is only com.lidlplus.app://callback No other redirect URI (including http://localhost) is accepted โ€” the auth server returns "There's been an error, Sorry, something went wrong" for any other value
Login page uses Cloudflare Turnstile (anti-bot CAPTCHA) Headless/automated login is frequently blocked on new accounts or after repeated attempts
MFA (2FA) is enforced on many accounts A verification code sent via SMS/email is required even in headless mode
The app deeplink com.lidlplus.app:// cannot be opened in a desktop browser After successful login, the browser shows a connection error โ€” the authorization code is embedded in the failed redirect URL

Option 1: Automatic login (try this first)

The integration attempts a headless login directly from Home Assistant using your credentials:

  1. During setup (or via Options โ†’ Log in to Lidl Plus), enter your Lidl Plus email/phone and password.
  2. If your account uses MFA/2FA, a second step appears asking for the SMS/email verification code.
  3. On success, the integration stores a refresh token โ€” you will not need to log in again.

If this fails with one of the errors below, proceed to Option 2.


Option 2: Browser-based login (fallback when headless login is blocked)

When the automatic login is blocked (Captcha, new session detection, or persistent MFA issues), Home Assistant automatically shows you a login link and a text field.

โš ๏ธ What happens after MFA โ€” and why "Hoppla!" is expected

After you submit the MFA code, Lidl's server redirects to com.lidlplus.app://callback?code=XXXX. A desktop browser cannot open this mobile app deeplink, so the Lidl SPA shows:

"Hoppla! Es ist ein Fehler aufgetreten" / "This site can't be reached"

This is completely expected and correct. The authorization code is embedded in that failed redirect URL. You capture it via the DevTools Network tab โ€” Chrome and Firefox do NOT show com.lidlplus.app:// URLs in the address bar.

Step-by-step instructions

  1. Open DevTools first: Press F12 in your browser โ†’ go to the Network tab โ†’ enable "Preserve log" (checkbox at the top of the Network tab).
  2. Click the login link shown in Home Assistant โ€” Lidlโ€™s login page opens.
  3. Log in with your Lidl Plus email and password.
  4. Enter the MFA code when prompted and submit it.
  5. The browser shows "Hoppla!" or a blank page โ€” this is normal and expected.
  6. In the Network tab, search for com.lidlplus.app โ€” you will see a failed request with a URL like:
    com.lidlplus.app://callback?code=XXXXXXXXXXXXXXXXXX&state=...
    
  7. Right-click that request โ†’ Copy โ†’ Copy link address (or click it and copy "Request URL" from the Headers panel).
  8. Paste the full URL into the text field in Home Assistant and submit.
  9. Home Assistant extracts the code, exchanges it for a token โ€” done.

๐Ÿ’ก Alternative: paste just the refresh token If you already have a refresh token (e.g. from the CLI method below), you can paste it directly (minimum 20 characters).


Option 3: Manual token via Terminal (advanced)

You can generate and exchange the code yourself without relying on the HA UI. Useful if you run HA on a server without a browser accessible from the same machine.

Step 1: Generate PKCE values

In Python (any machine):

import base64, hashlib, secrets

verifier = secrets.token_urlsafe(64)
challenge = (
    base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest())
    .decode()
    .rstrip("=")
)
nonce = secrets.token_urlsafe(32)
state = secrets.token_urlsafe(32)
print(f"verifier={verifier}\nchallenge={challenge}\nnonce={nonce}\nstate={state}")

Step 2: Open the OAuth authorization URL in a browser

Replace COUNTRY (e.g. DE) and use the generated values:

https://accounts.lidl.com/connect/authorize?client_id=LidlPlusNativeClient&redirect_uri=com.lidlplus.app%3A%2F%2Fcallback&response_type=code&scope=openid%20profile%20offline_access%20lpprofile%20lpapis&code_challenge=CHALLENGE&code_challenge_method=S256&Country=COUNTRY&language=LANG-COUNTRY&nonce=NONCE&state=STATE

Log in โ†’ complete MFA โ†’ copy the com.lidlplus.app://callback?code=XXX URL from the address bar (see Option 2 Step 4โ€“6).

Step 3: Exchange the code for a refresh token

Windows (PowerShell):

$body = @{
    grant_type    = "authorization_code"
    code          = "PASTE_CODE_HERE"
    redirect_uri  = "com.lidlplus.app://callback"
    code_verifier = "PASTE_VERIFIER_HERE"
}
$b64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("LidlPlusNativeClient:secret"))
$headers = @{ Authorization = "Basic $b64" }
(Invoke-RestMethod -Uri "https://accounts.lidl.com/connect/token" -Method Post -Body $body -Headers $headers).refresh_token

macOS / Linux (cURL):

curl -s -X POST https://accounts.lidl.com/connect/token \
  -H "Authorization: Basic TGlkbFBsdXNOYXRpdmVDbGllbnQ6c2VjcmV0" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=PASTE_CODE_HERE" \
  -d "redirect_uri=com.lidlplus.app://callback" \
  -d "code_verifier=PASTE_VERIFIER_HERE" | python3 -m json.tool

Copy the refresh_token value and paste it in Home Assistant.


๐Ÿ”ด Common Errors & Solutions

Error Cause Solution
"There's been an error, Sorry, something went wrong" shown before login The OAuth authorization URL uses a redirect_uri that is not com.lidlplus.app://callback โ€” Lidl only accepts this exact URI Make sure you use the link provided by Home Assistant (not a manually constructed URL with a localhost redirect)
"Login flow did not reach callback. Last status: 200" Cloudflare/Turnstile CAPTCHA blocked the headless login Use Option 2 (browser-based login) โ€” HA will show you the link automatically
"invalid_auth" in HA Wrong email/password Double-check credentials on the Lidl Plus app
"mfa_failed" Wrong or expired MFA code Request a new code and enter it immediately
Browser shows error after login but address bar is empty / URL not visible Browser navigated away from the deeplink URL Use F12 โ†’ Network tab to find the com.lidlplus.app:// request (see Option 2 tip)
"invalid_token" when pasting callback URL Code already used or expired (codes are single-use and expire within ~60 seconds) Start the login flow again to generate a fresh code
Integration loses authentication after some time Lidl refresh tokens expire after ~30 days of inactivity Re-login via Options โ†’ Log in to Lidl Plus

๐Ÿ› ๏ธ Options Flow

You can adjust settings at any time:

  1. Go to Settings > Devices & Services.
  2. Find Lidl Weekly Offers and click Configure.
  3. Options available:
    • Update Interval: How often to poll the Lidl API (1โ€“168 hours, default: 24 h).
    • Automatically activate coupons in background: Toggle automatic background activation of store coupons upon refresh.
    • Skip special product selection coupons: Choose whether to skip coupons requiring product choices or automatically select default products.
    • Log in to Lidl Plus / Log out of Lidl Plus: Manage your Lidl Plus authentication.

๐Ÿƒ Lovelace Cards

The community has built dedicated cards to display Lidl discounts beautifully in your dashboard.

Custom Discounts Card

A dedicated Lovelace card maintained by the community:

Discounts Card


๐Ÿง‘โ€๐Ÿ’ป Development

Ruff Linter

Ensure formatting and import order matches:

ruff check . --fix
ruff format .

Type Checking

Ensure all files pass strict type checking:

mypy .

Running Tests

Verify your changes against the test suite:

pytest

๐Ÿ“„ License

This project is licensed under the MIT License. See the LICENSE file for details.

About

A Home Assistant integration that fetches weekly offers, discounts, upcoming deal previews, active coupons, and digital receipts for your local Lidl store directly from the official Lidl Plus API.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages