Liverpool API & Scraper
Liverpool is Mexico's largest department-store chain and runs a marketplace on liverpool.com.mx.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
This API reads it as JSON. `search` takes Spanish words or a Liverpool category id with the store's own filters (brand, price range, minimum discount, minimum rating, sold by Liverpool, marketplace seller, gift with purchase) and five sort orders, and returns per product: id, title, brand, the struck list price, the promotion price Liverpool shows in bold, the discount, rating and review count, who sells it and a sponsored flag. `product` returns one product in full: every variant (colour, size, capacity) with its own list, sale and promotion price and a stock flag, the payment promotions for Liverpool cards and for other cards with discount, months without interest, monthly payment and total, wallet cashback and coupons, every marketplace offer with seller, seller rating, ships-in days and offer price, the specification table, and with a postal code the estimated delivery dates. `store_stock` returns the units in each Liverpool store of a Mexican state, and `reviews` the customer reviews with the star distribution.
What a Liverpool field actually contains
Fields that read differently from how they look. Every row was measured against live liverpool.com.mx pages on 2026-10-14.
| Field | What it holds |
|---|---|
| product_id | Liverpool's product id, the number at the end of a product address (…/tienda/pdp/…/1183307572). Pass it unchanged to product and reviews; a product URL works too. Search to product returned the same id on 16 of 16 rows. |
| list_price, promo_price | list_price is the struck price (precio de lista); promo_price is the bold price Liverpool shows. On 14 of 14 products promo_price equalled the price printed on the product page, and the second printed number matched list_price, or on multi-variant items the top of the price range, on 14 of 14. |
| sale_price (product only) | Liverpool's selling price before payment promotions; the page never prints it. One 50-inch TV: list 11,499, sale 8,570, promotion 6,427.50 MXN. It is given per variant; on multi-variant items the product-level figure is null because Liverpool's own product-level value belongs to one variant only. |
| promo_price_max, price_is_range | Items with variants priced differently carry a range: promo_price is the lowest (Liverpool's "desde"), promo_price_max the highest. product lists each variant with its own price. |
| liverpool_card_promotions, other_card_promotions | The payment options Liverpool lists under Tarjetas Liverpool and Otras tarjetas: discount percent, months without interest, monthly payment and the total you pay. The monthly payment and months Liverpool prints on the page matched on 4 of 4 products. Marketplace offers carry none. |
| offers | Marketplace sellers offering the variant: seller id and name, seller rating, days to ship, and the offer's own prices. A perfume had two offers, 1,049 and 1,780 MXN, for the same bottle. |
| sold_by (search) | The seller names Liverpool's search index holds for the item. It can include Liverpool group banners (suburbia, toysrus) and sellers that have since left: it differed from the product's current offers on 3 of 16 products. product.sold_by is the current list. |
| delivery | With postal_code, Liverpool's own estimate: date_from and date_to. It changes with the postal code (11000: Oct 21-25, 64000: Oct 23-27 for the same TV) and not with where the request comes from. available false means Liverpool shows no date for that postal code or item. |
| sponsored | True on paid placements. Liverpool adds 0 to 3 of them per page, and they take the place of regular results; use next_offset to page without missing rows. |
All prices are Mexican pesos (MXN). Search lists in-stock items only, as Liverpool's own search does. Prices and promotions were identical when read from inside and outside Mexico (99 of 99 search rows, 3 of 3 products).
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/liverpool/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "televisor",
"sort": "price_asc"
}
}{
"ok": true,
"meta": {
"api": "liverpool",
"endpoint": "search",
"mode": "live",
"latency_ms": 1922.1,
"record_count": 56,
"bytes": 112072,
"cache_hit": false,
"total": 2311,
"currency": "MXN",
"sponsored_rows": 3,
"pagination": {
"offset": 0,
"next_offset": 53,
"has_more": true
},
"upstream_requests": 1,
"charged_credits": 2,
"version": "0.1.0",
"request_id": "f3aa130888c8463d",
"queue_ms": 1.9,
"fetched_at": "2026-10-14T18:57:26.912Z"
},
"data": {
"query": {
"query": "televisor",
"sort": "price_asc",
"page_size": 56,
"offset": 0
},
"total": 2311,
"offset": 0,
"next_offset": 53,
"has_more": true,
"sponsored_count": 3,
"corrected_query": null,
"redirected_to": null,
"results": [
{
"product_id": "1197752111",
"sku_id": "1197752111",
"title": "Pantalla Smart TV Mini LED QLED de 4K/UHD 65QD8SFM con Fire OS con AI Smooth Motion",
"brand": "HISENSE",
"url": "https://www.liverpool.com.mx/tienda/pdp/pantalla-smart-tv-mini-led-qled-de-4k-uhd-65qd8sfm-con-fire-os-con-ai-smooth-motion/1197752111",
"image": "https://sp629.liverpool.com.mx/i/QD8SFM65MAIN940X1215LIVERPOOL.jpg",
"product_type": "Big Ticket",
"currency": "MXN",
"list_price": 13332.57,
"list_price_max": null,
"promo_price": 11499.3,
"promo_price_max": null,
"price_is_range": false,
"discount_pct": 14,
"rating": 4.5,
"review_count": 8,
"sold_by": [
"liverpool"
],
"sold_by_liverpool": true,
"is_marketplace": false,
"is_cross_border": false,
"sponsored": true,
"main_category": "Electrónica",
"category_paths": [
"Electrónica > TV y Video > Pantallas",
"Hisense > Pantallas y audio"
],
"categories": [
{
"category_id": "[trimmed-depth]",
"name": "[trimmed-depth]"
},
{
"category_id": "[trimmed-depth]",
"name": "[trimmed-depth]"
},
{
"category_id": "[trimmed-depth]",
"name": "[trimmed-depth]"
}
],
"colors": [
{
"sku_id": "[trimmed-depth]",
"color": "[trimmed-depth]",
"color_hex": "[trimmed-depth]",
"images": "[trimmed-depth]"
}
]
},
{
"product_id": "1169723156",
"sku_id": "1169723156",
"title": "Cable RCA de 1.3 m",
"brand": "CONTROL EXPERT",
"url": "https://www.liverpool.com.mx/tienda/pdp/cable-rca-de-1-3-m/1169723156",
"image": "https://ss630.liverpool.com.mx/lg/1169723156.jpg",
"product_type": "Soft Line",
"currency": "MXN",
"list_price": 169,
"list_price_max": null,
"promo_price": 152.1,
"promo_price_max": null,
"price_is_range": false,
"discount_pct": 10,
"rating": null,
"review_count": 0,
"sold_by": [
"LIDERT MX"
],
"sold_by_liverpool": false,
"is_marketplace": true,
"is_cross_border": false,
"sponsored": false,
"main_category": "Electrónica",
"category_paths": [
"Electrónica > Audio > Cables de Audio",
"Electrónica > Audio > Accesorios para audio"
],
"categories": [
{
"category_id": "[trimmed-depth]",
"name": "[trimmed-depth]"
},
{
"category_id": "[trimmed-depth]",
"name": "[trimmed-depth]"
},
{
"category_id": "[trimmed-depth]",
"name": "[trimmed-depth]"
}
],
"colors": [
{
"sku_id": "[trimmed-depth]",
"color": "[trimmed-depth]",
"color_hex": "[trimmed-depth]",
"images": "[trimmed-depth]"
}
]
},
{
"product_id": "999681394344",
"sku_id": "999681394344",
"title": "Control remoto para TV compatible con televisores Smart TV LCD LED reproductores de dvd/blu-ray decodificadores",
"brand": "RADIOSHACK",
"url": "https://www.liverpool.com.mx/tienda/pdp/control-remoto-para-tv-compatible-con-televisores-smart-tv-lcd-led-reproductores-de-dvd-blu-ray-decodificadores/999681394344",
"image": "https://sp101.liverpool.com.mx/i/1203173578.jpg",
"product_type": "Soft Line",
"currency": "MXN",
"list_price": 159,
"list_price_max": null,
"promo_price": 159,
"promo_price_max": null,
"price_is_range": false,
"discount_pct": 0,
"rating": null,
"review_count": 0,
"sold_by": [
"Coolbox"
],
"sold_by_liverpool": false,
"is_marketplace": true,
"is_cross_border": false,
"sponsored": false,
"main_category": "Electrónica",
"category_paths": [
"Electrónica > TV y Video > Accesorios de TV y video",
"Electrónica > TV y Video > Controles Remoto"
],
"categories": [
{
"category_id": "[trimmed-depth]",
"name": "[trimmed-depth]"
},
{
"category_id": "[trimmed-depth]",
"name": "[trimmed-depth]"
},
{
"category_id": "[trimmed-depth]",
"name": "[trimmed-depth]"
}
],
"colors": [
{
"sku_id": "[trimmed-depth]",
"color": "[trimmed-depth]",
"color_hex": "[trimmed-depth]",
"images": "[trimmed-depth]"
}
]
}
],
"facets": {
"categories": [
{
"name": "Electrónica",
"count": 1820
},
{
"name": "Muebles",
"count": 434
}
],
"brands": [
{
"name": "AIWA",
"count": 12
},
{
"name": "CONTROL EXPERT",
"count": 49
},
{
"name": "DAEWOO",
"count": 27
}
],
"sellers": [
{
"name": "liverpool",
"count": 222
},
{
"name": "CONTROL INN",
"count": 1068
},
{
"name": "RANOR INFINITY SA DE CV",
"count": 219
}
],
"price_ranges": [
{
"name": "Menos de $500",
"count": 748,
"low": 100,
"high": 500
},
{
"name": "$500 - $1000",
"count": 435,
"low": 500,
"high": 1000
},
{
"name": "$1000 - $2000",
"count": 206,
"low": 1000,
"high": 2000
}
],
"discount_ranges": [
{
"name": "10 % o más",
"count": 121,
"low": 10,
"high": 20
},
{
"name": "20 % o más",
"count": 381,
"low": 20,
"high": 30
},
{
"name": "30 % o más",
"count": 305,
"low": 30,
"high": 40
}
]
}
}
}What the Liverpool API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search liverpool.com.mx by keyword and/or category with the store's own filters (brand, price range, minimum discount, minimum rating, sold by Liverpool, marketplace seller id, gift with purchase) and 5 sort orders. Each row: product id, title, brand, URL, image, list price and promotion price (ranges for multi-variant items), discount %, rating and review count, who sells it (Liverpool and/or marketplace sellers), sponsored flag, category ids, colours with their SKU. Plus the source's total, facets and `next_offset` for gap-free paging. Liverpool lists in-stock items only. Needs `query` or `category` (or `seller_id`). | Pricing teams call search to search liverpool.com.mx by keyword and/or category with the store's own filters (brand, price…. | query, category, brand, min_price, max_price, ... |
| product | Full Liverpool product by product_id or URL: title, brand, description, images, category path, list / sale / promotion price, discount, stock flag, rating, who sells it, colour and size options, every variant (SKU) with its own prices, stock flag, Liverpool-card and other-card payment promotions (discount %, months without interest, monthly payment, total), wallet cashback, coupons and marketplace offers (seller id and name, seller rating, ships-in days, offer prices), and the specification table. With `postal_code` it adds Liverpool's delivery-date estimate to that Mexican postal code. | Marketplace operators call product to get full Liverpool product by product_id or URL. | product_id, url, sku_id, postal_code |
| reviews | Customer reviews of a Liverpool product: rating, title, text, date, author nickname as Liverpool shows it, verified-purchase flag, helpful / not-helpful votes, photos and videos, plus the review summary (average, count, star distribution, attribute ratings such as battery or picture quality) with `include_summary`. | Catalog enrichment teams call reviews to get customer reviews of a Liverpool product. | product_id, sort, rating, with_text_only, page, ... |
| store_stock | Units in stock per Liverpool department store in one Mexican state, for one variant (SKU): store name and id, stock count, address, city, postal code, coordinates, opening hours, store phone and whether click-and-collect / drive-thru pick-up is available. Liverpool's own 'Ver disponibilidad en tienda'. | Retail analysts call store_stock to get units in stock per Liverpool department store in one Mexican state, for one variant (SKU). | sku_id, state |
Call search from your stack
curl -X POST https://api.reefapi.com/liverpool/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"televisor","sort":"price_asc"}'import requests
r = requests.post(
"https://api.reefapi.com/liverpool/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "televisor",
"sort": "price_asc"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/liverpool/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "televisor",
"sort": "price_asc"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.liverpool.search with {"query":"televisor","sort":"price_asc"}.Who uses this API and why
- Track Liverpool's promotion prices and discounts on a product list during Hot Sale and Buen Fin.
- Compare the instalment offers (meses sin intereses) for Liverpool cards and other cards across products.
- Find which marketplace sellers offer a product on Liverpool and at what price.
- Check stock of a product in Liverpool stores by state before sending shoppers to a store.
- Estimate delivery dates to your customers' postal codes for products sold on Liverpool.
Questions developers ask before integrating
Do I need a Liverpool account?
No. Everything is read logged out, and you call reefapi.com from anywhere.
Which price should I use?
promo_price is what Liverpool shows as the price; list_price is the struck price before discount. For what a buyer pays with a card in instalments, read liverpool_card_promotions and other_card_promotions on each variant in product.
Do you return meses sin intereses?
Yes. Each variant lists the instalment plans Liverpool offers, for example 9 months without interest of 761.78 MXN on a 50-inch TV, with the discount and the total, separately for Liverpool cards and for other cards.
Which search filters are there?
Brand, price range, minimum discount, minimum rating, sold by Liverpool, marketplace seller id, gift with purchase and category. Each was checked against the unfiltered count in the same run: "televisor" 2,314 → Samsung 288, 5,000-10,000 MXN 274, from 20,000 MXN 143, up to 1,000 MXN 1,187, 30 % off or more 1,537, rated 4.5 or more 302, sold by Liverpool 225, gift with purchase 12, category Pantallas 417.
How do I page through all results?
Pass next_offset from each answer as offset in the next call. Up to 120 products per call; a search for "vestido" counted 10,912 products.
Can I see stock in a physical store?
Yes. store_stock takes a variant's sku_id and a Mexican state (01-32 or its name) and returns each Liverpool store with units in stock, address, hours and click-and-collect. One TV had stock in 14 stores of the Mexico City area.
Why do some searches return a category?
Liverpool sends some words, such as brand names, to a landing page. The API follows it and says so in redirected_to: "lego" returned the 598 products of the Lego category.
What is not returned?
Out-of-stock items in search, a category tree, questions and answers, and delivery dates for items where Liverpool's own page shows none.
What is the Liverpool API?
Liverpool API is a ReefAPI endpoint group for mexico's largest department store and marketplace: list, sale and promotion price, liverpool-card and other-card offers with months without interest, sellers, delivery dates, store stock and reviews. It returns live JSON through POST requests under /liverpool/v1.
Is the Liverpool API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Liverpool calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Liverpool login or account?
No login to Liverpool is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Liverpool data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Liverpool API use?
Liverpool actions currently cost 1-3 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Liverpool from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call liverpool actions with the same key, credit pool and JSON envelope used by normal REST requests.