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.
| โจ Features | ๐ฆ Installation | โ๏ธ Configuration | ๐ Lidl Plus Login |
| ๐ ๏ธ Options | ๐งโ๐ป Development | ๐ License |
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.
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.
- ๐ 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.
- Loyalty Card QR Code Image (
- ๐ฑ 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.
- All account-level entities (
- ๐ก๏ธ 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.
- Store-specific offer sensors (
- ๐๏ธ 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.
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!
| 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 โ |
This integration is available via the official Home Assistant Marketplace (HA 2026.11+) or as a custom repository.
- Open Marketplace in Home Assistant.
- Click on the three dots in the top right corner and select Custom repositories.
- Add
FaserF/ha-lidlwith category Integration. - Search for "Lidl Weekly Offers".
- Install and restart Home Assistant.
- Download the latest release zip file.
- Extract the
custom_components/lidlfolder into your Home Assistant'scustom_componentsdirectory. - Restart Home Assistant.
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 toen-USand the website link resolves tolidl.com.
- ๐จ๐ฆ / ๐ฆ๐บ / ๐ณ๐ฟ / ๐ฏ๐ต / ๐จ๐ณ / Non-Lidl countries: Lidl does not operate stores or Lidl Plus mobile services in these regions.
- Navigate to Settings > Devices & Services in Home Assistant.
- Click Add Integration and search for Lidl Weekly Offers.
- Select your country.
- Enter your ZIP code or city name to search for nearby Lidl stores.
- (Optional) Check Log in to Lidl Plus to enable personal features โ see below.
- Select your specific store from the dropdown list.
- Submit to create the device and entities.
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.
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 |
The integration attempts a headless login directly from Home Assistant using your credentials:
- During setup (or via Options โ Log in to Lidl Plus), enter your Lidl Plus email/phone and password.
- If your account uses MFA/2FA, a second step appears asking for the SMS/email verification code.
- 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.
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.
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.
- Open DevTools first: Press F12 in your browser โ go to the Network tab โ enable "Preserve log" (checkbox at the top of the Network tab).
- Click the login link shown in Home Assistant โ Lidlโs login page opens.
- Log in with your Lidl Plus email and password.
- Enter the MFA code when prompted and submit it.
- The browser shows "Hoppla!" or a blank page โ this is normal and expected.
- 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=... - Right-click that request โ Copy โ Copy link address (or click it and copy "Request URL" from the Headers panel).
- Paste the full URL into the text field in Home Assistant and submit.
- 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).
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.
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}")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).
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_tokenmacOS / 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.toolCopy the refresh_token value and paste it in Home Assistant.
| 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 |
You can adjust settings at any time:
- Go to Settings > Devices & Services.
- Find Lidl Weekly Offers and click Configure.
- 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.
The community has built dedicated cards to display Lidl discounts beautifully in your dashboard.
A dedicated Lovelace card maintained by the community:
Ensure formatting and import order matches:
ruff check . --fix
ruff format .Ensure all files pass strict type checking:
mypy .Verify your changes against the test suite:
pytestThis project is licensed under the MIT License. See the LICENSE file for details.