Lidl APIlidl.bg ↗
Get all currently discounted products from lidl.bg: prices, old prices, discount percentages, validity windows, and category data via a single API endpoint.
What is the Lidl API?
The lidl.bg API exposes one endpoint — list_discounted_products — that returns every product currently on sale in the Lidl Bulgaria online catalogue, typically covering around 400 discounted items across the full product range. Each result includes 10 structured fields: product ID, title, brand, category path, current price, original price, discount percentage, discount text, and catalogue scope metadata.
curl -X GET 'https://api.parse.bot/scraper/986169ac-0f96-43ea-a40b-8a36d8c43408/list_discounted_products?category=%D0%98%D0%BD%D1%81%D1%82%D1%80%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B8+%D0%B8+%D0%B3%D1%80%D0%B0%D0%B4%D0%B8%D0%BD%D0%B0' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace lidl-bg-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Lidl Bulgaria discounted products — browse current deals."""
from parse_apis.lidl_bg_api import LidlBg, ParseError
client = LidlBg()
# List the top 5 discounted products across all categories (sorted by discount %).
for product in client.products.list(limit=5):
print(
f"{product.title}: {product.price} {product.currency} "
f"(was {product.old_price}, {product.discount_text})"
)
# Drill into a single product to inspect its availability window.
best_deal = client.products.list(limit=1).first()
if best_deal is not None:
print(f"\nBest deal: {best_deal.title}")
print(f" Category: {best_deal.category_path}")
print(f" Valid from ts: {best_deal.valid_from} to {best_deal.valid_until}")
print(f" Availability: {best_deal.availability_text}")
print(f" In-store only: {not best_deal.online_available}")
# Narrow to a specific category and list a few items.
try:
for product in client.products.list(category="Хранителни", limit=3):
print(f"{product.title} — {product.discount_text} ({product.packaging})")
except ParseError as e:
print(f"Extraction failed ({e.code}): {e}")
print("\nexercised: products.list / products.list(category=)")
Returns the complete list of products in the lidl.bg online catalogue that currently carry a discount (an old price higher than the current price or a percentage-discount badge). The whole catalogue is walked in pages of 100 behind the scenes (typically 4 round trips for ~400 products) and non-discounted products are filtered out, so one call returns all discounted items sorted by discount percentage, highest first. Optionally narrows to one top-level category by its Bulgarian label as shown in the site's category filter. Prices are in EUR as displayed by the site; valid_from/valid_until are Unix timestamps of the in-store availability window and may be null. A category with no discounted products returns an empty items list with discounted_count 0.
| Param | Type | Description |
|---|---|---|
| category | string | Top-level category label in Bulgarian exactly as the site's category filter shows it (one shape: Инструменти и градина). Omitted = whole catalogue. An unknown label yields an empty result. |
{
"type": "object",
"fields": {
"items": "array of discounted products: product_id, title, brand, category, category_path, price, old_price, discount_percent, discount_text, currency, packaging, availability_text (list of store-availability badges), valid_from, valid_until, deal_of_day, online_available, description, image, url",
"category": "category filter applied, or null for whole catalogue",
"discounted_count": "number of discounted products returned in items",
"total_products_scanned": "number of catalogue products examined",
"total_products_in_catalog": "catalogue size reported by the site for this scope"
},
"sample": {
"data": {
"items": [
{
"url": "https://www.lidl.bg/p/b'lgarska-tarevita/p10062839",
"brand": null,
"image": "https://imgproxy-retcat.assets.schwarz/OpQPDJyPcF8bMnVgSTM5L_hkIpBboq0NCSr6oE6pOvQ/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/GFsb2ctbWVkaWEvYmcvMS9GQkFFMEZCMEQwNEY0NDZFNUExNDU3Njl/EOTFGNDVFRDVERDgwRDdFNEMwOERCMUMzNENEMDMxOUIzRjc2NzkzLnBuZw.png",
"price": 0.35,
"title": "Българска царевица",
"category": "Хранителни",
"currency": "EUR",
"old_price": 0.79,
"packaging": "бр.",
"product_id": "10062839",
"valid_from": 1788728400,
"deal_of_day": false,
"description": "",
"valid_until": 1789333199,
"category_path": "Светове на нуждата/Храна и близки до нея храни/Плодове и зеленчуци/Зеленчуци",
"discount_text": "-55%",
"discount_percent": 55,
"online_available": false,
"availability_text": [
"в магазините от 07.09. - 13.09."
]
}
],
"category": null,
"discounted_count": 114,
"total_products_scanned": 390,
"total_products_in_catalog": 390
},
"status": "success"
}
}About the Lidl API
What the endpoint returns
The list_discounted_products endpoint scans the entire lidl.bg catalogue and returns only the products carrying an active discount — those where the old price exceeds the current price or a discount badge is present. Each item in the items array includes product_id, title, brand, category, category_path, price, old_price, discount_percent, and discount_text. Alongside the product list, the response includes discounted_count (how many discounted products were found), total_products_scanned (products examined to find them), and total_products_in_catalog (the full catalogue size for the given scope).
Filtering by category
The optional category parameter accepts a top-level category label in Bulgarian, exactly as it appears in the site's category filter — for example, Инструменти и градина. When supplied, scanning and results are scoped to that category, and the category field in the response reflects the filter applied. When omitted, the whole catalogue is walked and category returns null. This makes it straightforward to monitor discounts within a specific product area without processing the full result set.
Coverage and freshness
The catalogue is paginated in batches of 100 products, requiring typically four round trips to cover approximately 400 products. Results reflect the discount state of the catalogue at call time. Lidl Bulgaria's promotions are time-bounded — the discount_text field often contains validity language from the site (such as offer-end dates), which allows callers to surface that window to end users without additional parsing.
The Lidl API is a managed, monitored endpoint for lidl.bg — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when lidl.bg changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official lidl.bg API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track daily price drops across the lidl.bg catalogue to alert subscribers when
discount_percentexceeds a threshold. - Compare
priceandold_priceacross categories to identify which product groups carry the deepest discounts. - Aggregate
discount_textfields to extract promotion validity windows for a deal-expiry calendar. - Scope calls to a specific Bulgarian-language category using the
categoryparameter to build category-level discount feeds. - Monitor
total_products_scannedvsdiscounted_countover time to track how the proportion of discounted items changes. - Feed
brandanddiscount_percentinto a price-intelligence dataset covering Lidl Bulgaria's private-label and branded ranges.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Lidl Bulgaria offer an official developer API for its product catalogue?+
What does the `discount_text` field contain, and how is it different from `discount_percent`?+
discount_percent is a numeric value representing the percentage reduction in price. discount_text is a free-form string taken directly from the site's discount badge or label — it may include validity language such as offer-end dates, promotional descriptions, or formatted percentage strings. The two fields are complementary: use discount_percent for numeric filtering and discount_text when you need the human-readable promotion copy.Does the API return products from Lidl Bulgaria's physical stores or only the online catalogue?+
discount_text field, but the API does not return structured per-store stock levels or branch-specific inventory. You can fork this API on Parse and revise it to add a store-availability endpoint if that data is accessible on the site.Does the API include non-discounted products or full catalogue browsing?+
list_discounted_products returns only items currently carrying a discount. Non-discounted products are scanned to produce total_products_scanned but are not included in the items array. You can fork this API on Parse and revise it to add an endpoint that returns the full catalogue regardless of discount status.How current is the discount data, and do promotions update automatically?+
list_discounted_products reflects the discount state of the lidl.bg catalogue at the time the request is made. Lidl Bulgaria updates its promotions on a rolling basis — typically weekly — so re-calling the endpoint is the correct pattern for detecting newly added or expired offers. There is no webhook or push mechanism; polling is required.