# Ripley API — Chile and Peru department store + Mercado Ripley: search, categories, normal / internet / Tarjeta Ripley prices, seller, stock, specs and reviews

> Search Ripley (simple.ripley.cl Chile or simple.ripley.com.pe Peru) — Ripley's own stock and the Mercado Ripley marketplace shops. One page of 48 products with the three prices kept apart (normal crossed price, internet price, Tarjeta Ripley card price), discount %, seller and whether it is Ripley or a marketplace shop, rating, review count, image, colours and variant SKUs; plus brand counts, price range and the source's filter facets. Sponsored ads come in a separate `sponsored` list. Filters: brand, seller_type, min_price, max_price; sort; page. `query` is required.
> ReefAPI engine `ripley` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/ripley/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/ripley/v1/search — 3 credits
Search Ripley (simple.ripley.cl Chile or simple.ripley.com.pe Peru) — Ripley's own stock and the Mercado Ripley marketplace shops. One page of 48 products with the three prices kept apart (normal crossed price, internet price, Tarjeta Ripley card price), discount %, seller and whether it is Ripley or a marketplace shop, rating, review count, image, colours and variant SKUs; plus brand counts, price range and the source's filter facets. Sponsored ads come in a separate `sponsored` list. Filters: brand, seller_type, min_price, max_price; sort; page. `query` is required.

**Parameters:**
- `query` (string, required) — What to search for, as typed in the Ripley search box (Spanish: notebook, zapatillas, televisor, sofá).
- `country` (enum, optional, default "cl") — cl = simple.ripley.cl (Chile, CLP), pe = simple.ripley.com.pe (Peru, PEN). [one of: cl, pe]
- `page` (integer, optional, default 1) — Result page (48 organic products per page).
- `sort` (enum, optional, default "relevance") — relevance | price_low | price_high | rating. [one of: relevance, price_low, price_high, rating]
- `brand` (string, optional) — Only this brand, spelled as the `facets.brands` list shows it.
- `seller_type` (enum, optional) — ripley = sold by Ripley itself; marketplace = Mercado Ripley shops. [one of: ripley, marketplace]
- `min_price` (integer, optional) — Lowest price, in the local currency. The source compares its lowest payable price (the Tarjeta Ripley card price when there is one), so a row can carry a `price` outside the range.
- `max_price` (integer, optional) — Highest price, in the local currency. Same rule as min_price: measured 2026-10-15, 4 of 48 rows had price 509 990-549 990 over max 500 000 with card_price 489 990-499 990 inside.

**Returns:** total, page, page_size (48 organic rows), last_page, has_more, returned, products[]{id, parent_id, name, brand, url, price (internet), normal_price, internet_price, card_price (Tarjeta Ripley), discount_pct, currency, in_stock_index, seller, seller_legal_name, seller_type (ripley|marketplace), rating, review_count, category_code, image, colors, variant_count, variant_skus}, sponsored[] (ads, same shape, NOT filtered by the source), facets{brands, price_range, filters}

**Example request body:**
```json
{
  "query": "notebook"
}
```

### POST https://api.reefapi.com/ripley/v1/category — 3 credits
Browse one Ripley category by its path (e.g. tecno/computacion/notebooks) — the same rows, prices, filters, sort and facets as `search`, without a keyword. Paths come from `categories` or from the site's own category URL. `category` is required.

**Parameters:**
- `category` (string, required) — Category path as `categories` returns it, or a full simple.ripley.cl / simple.ripley.com.pe category URL.
- `country` (enum, optional, default "cl") — cl = simple.ripley.cl (Chile, CLP), pe = simple.ripley.com.pe (Peru, PEN). [one of: cl, pe]
- `page` (integer, optional, default 1) — Result page (48 organic products per page).
- `sort` (enum, optional, default "relevance") — relevance | price_low | price_high | rating. [one of: relevance, price_low, price_high, rating]
- `brand` (string, optional) — Only this brand, spelled as the `facets.brands` list shows it.
- `seller_type` (enum, optional) — ripley = sold by Ripley itself; marketplace = Mercado Ripley shops. [one of: ripley, marketplace]
- `min_price` (integer, optional) — Lowest price, in the local currency. The source compares its lowest payable price (the Tarjeta Ripley card price when there is one), so a row can carry a `price` outside the range.
- `max_price` (integer, optional) — Highest price, in the local currency. Same rule as min_price: measured 2026-10-15, 4 of 48 rows had price 509 990-549 990 over max 500 000 with card_price 489 990-499 990 inside.

**Returns:** total, page, page_size (48 organic rows), last_page, has_more, returned, products[]{id, parent_id, name, brand, url, price (internet), normal_price, internet_price, card_price (Tarjeta Ripley), discount_pct, currency, in_stock_index, seller, seller_legal_name, seller_type (ripley|marketplace), rating, review_count, category_code, image, colors, variant_count, variant_skus}, sponsored[] (ads, same shape, NOT filtered by the source), facets{brands, price_range, filters}

**Example request body:**
```json
{
  "category": "tecno/computacion/notebooks"
}
```

### POST https://api.reefapi.com/ripley/v1/categories — 3 credits
The Ripley category tree (Chile or Peru): departments and their sub-categories with the `path` to pass to `category`.

**Parameters:**
- `country` (enum, optional, default "cl") — cl = Chile, pe = Peru. [one of: cl, pe]
- `depth` (integer, optional, default 2) — Levels of children to include (1-4).

**Returns:** categories[]{id, name, path, child_count, children[]}

### POST https://api.reefapi.com/ripley/v1/product — 2 credits
One Ripley product by SKU (a search row's `id`), parent id or product URL: the three prices kept apart — normal (crossed), internet and Tarjeta Ripley card price — with discount %, stock, EAN, brand, model, part number, seller (Ripley or the marketplace shop) with its legal name and tax id, category path, rating and review count, all images, description, the full specification sheet, every variant with its own SKU, prices and stock, and extended-warranty offers. Optional `commune`: delivery options for that commune (one extra request). One of `id` or `url` is required.

**Parameters:**
- `id` (string, optional) — SKU as search rows return it (`id`), or the parent id (ending in P).
- `url` (string, optional) — A simple.ripley.cl / simple.ripley.com.pe product URL (the trailing ...<sku>p is read).
- `country` (enum, optional, default "cl") — cl = Chile, pe = Peru (taken from the URL when one is given). [one of: cl, pe]
- `commune` (string, optional) — Numeric commune / district code for delivery options (Chile 13101 = Santiago, Peru 150101 = Lima).

**Returns:** id, parent_id, name, brand, model, part_number, ean, url, price, normal_price, internet_price, card_price, discount_pct, card_discount_pct, currency, in_stock, seller, seller_legal_name, seller_tax_id, seller_type, category_path, rating, review_count, description, images, colors, specifications, variants[], extended_warranties[], delivery[] (with commune)

**Example request body:**
```json
{
  "id": "2000403871267"
}
```

### POST https://api.reefapi.com/ripley/v1/reviews — 1 credit
Customer reviews of one Ripley product: rating, title, text, author nickname, location, date and photos, plus the average, the rating histogram and the totals. Paged; sort newest / oldest / rating_high / rating_low / with_media. `id` is required.

**Parameters:**
- `id` (string, required) — SKU or parent id of the product (search row `id`).
- `country` (enum, optional, default "cl") — cl = Chile, pe = Peru. [one of: cl, pe]
- `page` (integer, optional, default 1) — Review page.
- `limit` (integer, optional, default 10) — Reviews per page (1-50).
- `sort` (enum, optional, default "newest") — newest | oldest | rating_high | rating_low | with_media. [one of: newest, oldest, rating_high, rating_low, with_media]

**Returns:** id, total, rating_count, average_rating, histogram, page, limit, returned, has_more, reviews[]{rating, title, text, author, location, created_at, media}

**Example request body:**
```json
{
  "id": "2000403871267"
}
```

## 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=ripley
- Human docs page: https://reefapi.com/docs/ripley
- Overview page: https://reefapi.com/ripley-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt