# Wish — cross-border marketplace search, products, shipping & reviews

> Keyword search across Wish with price, rating, shipping, deal and merchant-tier filters. Returns the price charged, the strikethrough price where Wish publishes one, rating, review count and merchant id.
> ReefAPI engine `wish` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/wish/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, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /wish/v1/search — 3 credits
Keyword search across Wish with price, rating, shipping, deal and merchant-tier filters. Returns the price charged, the strikethrough price where Wish publishes one, rating, review count and merchant id.

**Parameters:**
- `query` (string, required) — What to search for.
- `market` (enum, optional, default "US") — Storefront to price against — it changes the currency, the price and how many variations exist. Wish sets it from the exit and accepts no override, so a rarer market costs extra attempts and GB can come back MARKET_UNAVAILABLE; 'any' is cheapest and reports whichever storefront answered. [one of: US, GB, CN, any]
- `limit` (integer, optional, default 30) — How many products to return (1-150).
- `max_pages` (integer, optional, default 5) — Upstream pages to walk. Wish returns 20-30 usable rows per page, so 150 results needs about 6.
- `min_price` (number, optional) — Lowest price, in the storefront's currency. Applied by this API to the rows it fetched — Wish's search ignores price filters — so raise `max_pages` to widen the net. `filtered_out` reports how many rows it removed.
- `max_price` (number, optional) — Highest price, in the storefront's currency. Applied by this API to the rows it fetched, like `min_price`.
- `min_rating` (enum, optional) — Only products rated this many stars and up. Applied by this API to the rows it fetched. Products with no reviews have no rating and are excluded. [one of: 4, 3, 2, 1]

**Returns:** {query, storefront, currency, total_found, returned, results[], filters_applied, filtered_out, next_offset}

**Example request body:**
```json
{
  "query": "wireless earbuds",
  "limit": 10,
  "market": "US"
}
```

### POST /wish/v1/product — 3 credits
Full product record: price, list price, SHIPPING COST and total, every colour/size variation with its own price and stock, merchant, categories, images, description and rating histogram.

**Parameters:**
- `product_id` (string, required) — Wish product id, or any wish.com product URL.
- `market` (enum, optional, default "US") — Storefront to price against. [one of: US, GB, CN, any]
- `max_variants` (integer, optional, default 100) — Variations to return. Wish publishes up to several hundred per product; `variant_count` always states the true total.

**Returns:** {product with variants[], merchant{}, categories[], images[]}

**Example request body:**
```json
{
  "product_id": "63eb5819af90c9111b845906",
  "market": "US"
}
```

### POST /wish/v1/reviews — 2 credits
Buyer reviews for a product with the 1-5 star histogram. No reviewer personal data is returned.

**Parameters:**
- `product_id` (string, required) — Wish product id, or any wish.com product URL.
- `market` (enum, optional, default "any") — Storefront. Reviews do not vary by market; 'any' is cheapest. [one of: US, GB, CN, any]
- `limit` (integer, optional, default 30) — How many reviews to return.
- `offset` (integer, optional, default 0) — Where to start, for paging.

**Returns:** {product_id, rating, review_count, rating_spread{}, reviews[]}

**Example request body:**
```json
{
  "product_id": "6188c90eddcc50d1bcf714c2",
  "limit": 5,
  "market": "any"
}
```

### POST /wish/v1/similar — 3 credits
The related-products grid Wish shows under a product.

**Parameters:**
- `product_id` (string, required) — Wish product id, or any wish.com product URL.
- `market` (enum, optional, default "US") — Storefront to price against. [one of: US, GB, CN, any]
- `limit` (integer, optional, default 30) — How many related products to return.

**Returns:** {product_id, storefront, currency, returned, results[]}

**Example request body:**
```json
{
  "product_id": "63eb5819af90c9111b845906"
}
```

### POST /wish/v1/merchant — 2 credits
A Wish store's display name, average rating and rating count.

**Parameters:**
- `merchant_id` (string, required) — Wish merchant id, as returned by `search` (`merchant_id`) or `product` (`merchant.merchant_id`).
- `market` (enum, optional, default "any") — Storefront. Store data does not vary by market. [one of: US, GB, CN, any]

**Returns:** {merchant_id, name, rating, rating_count, store_url}

### POST /wish/v1/trending — 3 credits
Wish's logged-out home feed — what the site puts in front of a new visitor in the chosen storefront.

**Parameters:**
- `market` (enum, optional, default "US") — Storefront to price against. [one of: US, GB, CN, any]
- `limit` (integer, optional, default 30) — How many products to return.
- `offset` (integer, optional, default 0) — Where to start, for paging.

**Returns:** {storefront, currency, returned, results[]}

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