# Qoo10 Japan API — search qoo10.jp, read any item (sale, list and coupon / Mega Wari prices, Q-points, shipping, stock and price per option, seller rating), shop listings, ranking 200 and the category tree

> Search Qoo10 Japan (qoo10.jp) across every shop by keyword, optionally inside one category, a price range (applied by the site to the sale price), in one of the site's five sort orders. 40 organic items per page (sponsored PR rows returned apart), up to 50 pages. Each row: item id, title, brand, sale price (JPY, tax included), struck price and price drop, the coupon price the card advertises (shop coupon / Mega Wari / Mega Debut) with its label, Q-points, rating and review count, free-shipping flag, ship-from country, shop id/name/grade.
> ReefAPI engine `qoo10` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/qoo10/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/qoo10/v1/search — 3 credits
Search Qoo10 Japan (qoo10.jp) across every shop by keyword, optionally inside one category, a price range (applied by the site to the sale price), in one of the site's five sort orders. 40 organic items per page (sponsored PR rows returned apart), up to 50 pages. Each row: item id, title, brand, sale price (JPY, tax included), struck price and price drop, the coupon price the card advertises (shop coupon / Mega Wari / Mega Debut) with its label, Q-points, rating and review count, free-shipping flag, ship-from country, shop id/name/grade.

**Parameters:**
- `query` (string, required) — Search words, Japanese or English (e.g. `iphone`, `トナーパッド`). Full-width letters are normalised.
- `category_id` (string, optional) — Qoo10 category code to search inside: a 9-digit large (1xxxxxxxx) or medium (2xxxxxxxx) code from `categories` or a row's `category_large_id` / `category_medium_id` (220000285 = 保護フィルム). An unknown code returns 0 rows.
- `min_price` (integer, optional) — Minimum sale price in JPY. Measured: the site filters on the sale price, not on the coupon price.
- `max_price` (integer, optional) — Maximum sale price in JPY (sale price, not coupon price).
- `sort` (enum, optional, default "ranking") — Result order (the site's own five). [one of: ranking, price_asc, price_desc, most_reviewed, newest]
- `page` (integer, optional, default 1) — Result page, 1-50 (the site's pager stops at 50).

**Returns:** results[]{item_id, url, title, brand, brand_no, official_brand, image, price, currency=JPY, price_is_placeholder, struck_price, price_drop, coupon_price, coupon_price_label, coupon_price_type, qpoints, rating, rating_pct, review_count, free_shipping, ships_from, shop_coupon_available, category_large_id, category_medium_id, shop{shop_id, name, grade, grade_label, url}, sponsored} + sponsored[] + page, last_page, has_more, page_clamped, query, filters

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

### POST https://api.reefapi.com/qoo10/v1/product — 3 credits
One Qoo10 Japan item page: title, brand, condition, the sale price, the seller's list price, discount % and deal type (タイムセール / 今日の特価), the item's recent minimum selling price, the coupon price the page advertises (shop coupon / Mega Wari / Mega Debut / Mega Point) with its label and the page's own price breakdown, Q-points, stock and price delta per option, order limit, shipping fee, carrier and free-over threshold, ship-from country, rating, satisfaction %, review and sales counts, category codes, images and the seller (grade, rating, followers, award).

**Parameters:**
- `item_id` (string, optional) — Qoo10 item number (goodscode) exactly as a search row's `item_id` returns it. Required unless `url` is given.
- `url` (string, optional) — An item page URL (www.qoo10.jp/g/<number>, /item/<name>/<number> or Goods.aspx?goodscode=<number>).

**Returns:** product{item_id, url, title, brand, brand_no, condition, price, currency, price_is_placeholder, list_price, discount_pct, discount_type, recent_min_price, ld_price, ld_price_is_coupon_price, price_mismatch, coupon_price, coupon_price_label, coupon_price_type, coupons_applied[]{type, amount}, price_breakdown[]{label, value}, mega_point_effective_price, qpoints_max, availability, in_stock, stock_total, order_limit, option_levels, option_levels_read, variants[]{option_id, group, level, name, price_delta, stock, in_stock, image}, addon_options[], options_read, ships_from, ships_from_label, shipping[]{carrier, fee, free_over, condition, ships_from, last_mile}, shipping_fee, free_shipping, delivery_days_guaranteed, rating, rating_ld, satisfaction_pct, review_count, sold_count, category_large_id, category_large_name, category_medium_id, category_small_id, images[], promotion_text, shop{shop_id, name, url, grade, grade_label, rating_pct, rating, followers, award}, shop_read}

**Example request body:**
```json
{
  "item_id": "775669909"
}
```

### POST https://api.reefapi.com/qoo10/v1/shop — 3 credits
Every item one Qoo10 Japan shop sells, 60 per page, in one of the site's five sort orders: the same row fields as `search`.

**Parameters:**
- `shop_id` (string, required) — The shop's id as in www.qoo10.jp/shop/<shop_id> (a search row's `shop.shop_id`), or the shop URL.
- `sort` (enum, optional, default "ranking") — Result order (the site's own five). [one of: ranking, price_asc, price_desc, most_reviewed, newest]
- `page` (integer, optional, default 1) — Result page, 60 items per page.

**Returns:** results[]{same as search} + shop_id, page, last_page, has_more

**Example request body:**
```json
{
  "shop_id": "medicube"
}
```

### POST https://api.reefapi.com/qoo10/v1/ranking — 3 credits
Qoo10 Japan's ranking 200 (ランキング200), overall or for one of its eleven tabs: rank, item id, title, brand, sale price and struck price, review count, free shipping.

**Parameters:**
- `group` (enum, optional, default "all") — Ranking tab. [one of: all, fashion, beauty, supplements, mens, electronics, phones, home, food, pets, baby, kpop]

**Returns:** results[]{rank, item_id, url, title, brand, image, price, currency, struck_price, review_count, free_shipping} + group, group_name

**Example request body:**
```json
{
  "group": "beauty"
}
```

### POST https://api.reefapi.com/qoo10/v1/categories — 3 credits
The Qoo10 Japan category tree as the site's menu publishes it: 11 groups, their large categories and medium categories with 9-digit codes usable as `search.category_id`.

**Parameters:** none

**Returns:** groups[]{group_id, name, categories[]{category_id, level, name, children[]{category_id, level, name}}}

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