# Liverpool API — search Mexico's largest department store and marketplace (liverpool.com.mx) and read full products: list, sale and promotion price, Liverpool-card and other-card offers with months without interest, variants, marketplace sellers, delivery date by postal code, store stock and reviews

> 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`).
> ReefAPI engine `liverpool` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/liverpool/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/liverpool/v1/search — 2 credits
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`).

**Parameters:**
- `query` (string, optional) — Search words in Spanish, e.g. 'televisor', 'tenis nike', 'vestido', 'perfume'. Needs query OR category OR seller_id.
- `category` (string, optional) — Liverpool category id (e.g. CAT5150041 Electrónica, CATST14457077 Pantallas), from `categories[].category_id` of any search row or `category_path` of a product. Alone it browses the category; with query it narrows the search. An id Liverpool does not know is rejected.
- `brand` (string, optional) — Brand name as Liverpool lists it (facets.brands). Matched case-insensitively.
- `min_price` (number, optional) — Lowest price in MXN. Liverpool applies it to the promotion price (the bold price), not to the sale price.
- `max_price` (number, optional) — Highest promotion price in MXN.
- `min_discount` (integer, optional) — Only items discounted at least this many percent off the list price.
- `min_rating` (number, optional) — Only items whose average rating is at least this (0-5). Liverpool's own '4 estrellas o más' chip uses 3.8.
- `sold_by_liverpool` (boolean, optional) — Only items Liverpool itself sells (an item can be sold by Liverpool and marketplace sellers at once).
- `seller_id` (string, optional) — Only items offered by this marketplace seller (`variants[].offers[].seller_id` in product).
- `gift_with_purchase` (boolean, optional) — Only items with Liverpool's 'Regalo con compra' promotion.
- `sort` (enum, optional, default "relevance") — Result order (Liverpool's own sort bar). [one of: relevance, newest, price_asc, price_desc, top_rated]
- `page_size` (integer, optional, default 56) — Rows per call (Liverpool's default 56, at most 120). Sponsored rows, when Liverpool inserts them, count toward it.
- `offset` (integer, optional, default 0) — How many organic (non-sponsored) results to skip. Pass `next_offset` from the previous call to page without gaps.
- `page` (integer, optional) — Convenience: offset = (page-1) x page_size. When Liverpool inserted sponsored rows on an earlier page this skips the organic rows they displaced; use offset/next_offset for complete paging. Ignored when offset is given.

**Returns:** results[]{product_id, sku_id, title, brand, url, image, product_type, currency (MXN), list_price (precio de lista), list_price_max, promo_price (the bold price), promo_price_max, price_is_range, discount_pct, rating, review_count, sold_by[], sold_by_liverpool, is_marketplace, is_cross_border, sponsored, main_category, category_paths[], categories[]{category_id, name}, colors[]{sku_id, color, color_hex, images[]}} + total, offset, next_offset, has_more, sponsored_count, corrected_query, redirected_to{category_id, url} (Liverpool sends some words, e.g. brand names, to a category page; the rows are then that category), facets{categories[], brands[], sellers[], price_ranges[], discount_ranges[]}

**Example request body:**
```json
{
  "query": "televisor",
  "sort": "price_asc"
}
```

### POST https://api.reefapi.com/liverpool/v1/product — 3 credits
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.

**Parameters:**
- `product_id` (string, optional) — Liverpool product id: the number at the end of a product URL (`/tienda/pdp/<slug>/1183307572`), returned as `product_id` in every search row. Provide product_id OR url.
- `url` (string, optional) — A liverpool.com.mx product URL; alternative to product_id.
- `sku_id` (string, optional) — Variant to estimate delivery for (`variants[].sku_id`). Default: the first in-stock variant.
- `postal_code` (string, optional) — Mexican postal code (5 digits). Adds `delivery`: Liverpool's estimated delivery dates to it. Dates differ by postal code (11000 Oct 21-25 vs 64000 Oct 23-27 for the same TV).

**Returns:** item{product_id, title, brand, url, description, product_type, department, images[], category_path[]{category_id, name}, currency, list_price, list_price_max, sale_price, promo_price, promo_price_max, price_is_range, discount_pct, in_stock, rating, review_count, sold_by[], is_marketplace, has_hybrid_seller, is_presale, is_international, is_collection, extended_warranty_available, min_pieces, options{colors[], sizes[]}, variant_count, variants[]{sku_id, color, color_brand_name, color_hex, size, in_stock, list_price, sale_price, promo_price, discount_pct, liverpool_card_promotions[]{description, discount_pct, months_without_interest, monthly_payment, total_price, is_best, type}, other_card_promotions[], has_msi, wallet_cashback, wallet_cashback_amount, coupon_ids[], min_pieces, offers_count, best_offer_id, offers[]{offer_id, seller_id, seller_name, seller_sku_id, ships_in_days, seller_rating, seller_review_count, list_price, sale_price, promo_price, discount_pct, currency, is_cross_border}, image}, specs[]{group, name, value}, delivery{postal_code, sku_id, available, date_from, date_to, text, shipping_type, message, days_to_deliver, fulfillment} (only with postal_code)}

**Example request body:**
```json
{
  "product_id": "1163569672"
}
```

### POST https://api.reefapi.com/liverpool/v1/reviews — 1 credit
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`.

**Parameters:**
- `product_id` (string, required) — Liverpool product id.
- `sort` (enum, optional, default "most_helpful") — Review order (Liverpool's own options). [one of: most_helpful, newest, highest_rating, lowest_rating]
- `rating` (integer, optional) — Only reviews with exactly this many stars.
- `with_text_only` (boolean, optional) — Only reviews that have written text (Liverpool's own page shows these; star-only ratings are excluded).
- `page` (integer, optional, default 1) — Review page.
- `page_size` (integer, optional, default 20) — Reviews per page (at most 100).
- `include_summary` (boolean, optional) — Also return the review summary: average, review count, star distribution in percent and attribute ratings.

**Returns:** reviews[]{review_id, rating, title, text, date, author, verified_purchase, helpful_count, not_helpful_count, featured, photos[], videos[], sku_id} + total, page, page_size, has_more, summary{average, review_count, stars_pct{}, attributes[]{name, rating}} (with include_summary)

**Example request body:**
```json
{
  "product_id": "1163569672"
}
```

### POST https://api.reefapi.com/liverpool/v1/store_stock — 1 credit
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'.

**Parameters:**
- `sku_id` (string, required) — Variant SKU: `variants[].sku_id` from product (for single-variant items it equals the product id).
- `state` (string, required) — Mexican state: two-digit code 01-32 (09 = CDMX / zona metropolitana, 14 = Jalisco, 19 = Nuevo León) or its name as Liverpool writes it (e.g. 'JALISCO').

**Returns:** sku_id, state, state_name, stores[]{store_id, store_name, stock, address, address_text, city, state, postal_code, lat, lon, phone, hours, click_and_collect, drive_thru_pickup}, stores_with_stock, total_units

**Example request body:**
```json
{
  "sku_id": "1163059041",
  "state": "09"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=liverpool
- Human docs page: https://reefapi.com/docs/liverpool
- Overview page: https://reefapi.com/liverpool-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt