# AliExpress API — product search, full product detail (SKU/variant prices, specs, images), buyer reviews, shipping rates, store catalogs and deals (region- and currency-aware)

> Product search cards (price, sold_count, rating, store); filters sort/min_price/max_price/ship_from/free_shipping, paginated
> ReefAPI engine `aliexpress` · 10 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/aliexpress/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 or blocked calls are free.
- **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 /aliexpress/v1/search — 1 credit
Product search cards (price, sold_count, rating, store); filters sort/min_price/max_price/ship_from/free_shipping, paginated

**Parameters:**
- `query` (string, required) — What to search for (product keywords).
- `sort` (enum, optional, default "best_match") — Result ordering. [one of: best_match, orders, price_low, price_high, newest, default, best_selling, price_asc, price_desc]
- `min_price` (number, optional) — Only items at or above this price (in `currency`).
- `max_price` (number, optional) — Only items at or below this price (in `currency`).
- `ship_from` (string, optional) — Only items shipped from this country (2-letter ISO code, e.g. CN, US, ES).
- `free_shipping` (boolean, optional, default false) — Only items with free shipping.
- `country` (string, optional, default "US") — Ship-to country (2-letter ISO code, e.g. US, DE, TR). Changes prices, availability and shipping options.
- `currency` (string, optional, default "USD") — Currency for prices (3-letter ISO code, e.g. USD, EUR, TRY).
- `page` (integer, optional, default 1) — Page number to start from (easy paging: 1, 2, 3…).
- `max_pages` (integer, optional, default 1) — How many consecutive pages to fetch in one call (1–10, ~48–60 results per page; larger values are capped at 10).

**Returns:** results[]{product_id, title, url, image, images[], price, original_price, currency, discount_pct, price_formatted, sold_count, rating, store_name, store_url, product_type, promo_tags[]} + related_searches[] + ranking_searches[] (AliExpress 'people also search for' / trending terms) (meta.pagination for paging)

**Example request body:**
```json
{
  "query": "wireless earbuds",
  "country": "US",
  "currency": "USD"
}
```

### POST /aliexpress/v1/product_detail — 1 credit
Full product + SKU-variant price/stock matrix + specs + images + video + store + shipping + rating + coupons + sale countdown + wishlist counts

**Parameters:**
- `product_id` (string, optional) — AliExpress product ID — the digits in the product URL (…/item/<id>.html). Provide product_id OR url.
- `url` (string, optional) — Full product URL — alternative to product_id.
- `country` (string, optional, default "US") — Ship-to country (2-letter ISO code, e.g. US, DE, TR). Changes prices, availability and shipping options.
- `currency` (string, optional, default "USD") — Currency for prices (3-letter ISO code, e.g. USD, EUR, TRY).

**Returns:** product{product_id, title, price_min, price_max, currency, rating, review_count, sold_count, total_stock, images[], video_url, sku_variants[]{sku_id, props, price, stock, available}, sku_properties[], specs[]{name,value}, store{}, shipping, coupons[]{text, promotion_id}, sale{type, ends_at, countdown}, selling_points[], wishlist_count, store_wished_count, description_url}

### POST /aliexpress/v1/reviews — 1 credit
Buyer reviews (paginated — fetch many pages in one call) + rating distribution

**Parameters:**
- `product_id` (string, optional) — AliExpress product ID — the digits in the product URL (…/item/<id>.html). Provide product_id OR url.
- `url` (string, optional) — Full product URL — alternative to product_id.
- `filter` (enum, optional, default "all") — Which reviews to return (passed to the upstream feedback API; the 3 listed are the documented values). [one of: all, image, additional]
- `page_size` (integer, optional, default 10) — Reviews per page (1–20; larger values are capped at 20).
- `max_pages` (integer, optional, default 1) — How many consecutive review pages to gather in one call (1–20). Combine with page_size=20 to pull all reviews of a product (e.g. max_pages=10 → up to 200 reviews).
- `review_sort` (string, optional, default "complex_default") — Upstream sort key (advanced) — leave at the default.
- `country` (string, optional, default "US") — Ship-to country (2-letter ISO code, e.g. US, DE, TR). Changes prices, availability and shipping options.
- `currency` (string, optional, default "USD") — Currency for prices (3-letter ISO code, e.g. USD, EUR, TRY).
- `page` (integer, optional, default 1) — Page number to start from (easy paging: 1, 2, 3…).

**Returns:** reviews[]{rating, text, date, country, sku_info, logistics, images[], labels[]} + summary{total_reviews, total_pages, average_star, distribution{1..5}, positive/neutral/negative counts} (meta.pagination for paging)

### POST /aliexpress/v1/similar — 1 credit
Products similar to a given item (search-backed 'more like this', seed product excluded), paginated

**Parameters:**
- `product_id` (string, optional) — AliExpress product ID — the digits in the product URL (…/item/<id>.html). Provide product_id OR url.
- `url` (string, optional) — Full product URL — alternative to product_id.
- `query` (string, optional) — Optional seed keywords — overrides the product's own title (skips the detail lookup). Provide product_id/url OR query.
- `sort` (enum, optional, default "best_match") — Result ordering. [one of: best_match, orders, price_low, price_high, newest, default, best_selling, price_asc, price_desc]
- `country` (string, optional, default "US") — Ship-to country (2-letter ISO code, e.g. US, DE, TR). Changes prices, availability and shipping options.
- `currency` (string, optional, default "USD") — Currency for prices (3-letter ISO code, e.g. USD, EUR, TRY).
- `page` (integer, optional, default 1) — Page number to start from (easy paging: 1, 2, 3…).
- `max_pages` (integer, optional, default 1) — How many consecutive pages to fetch in one call (1–10, ~48–60 results per page; larger values are capped at 10).

**Returns:** results[]{product_id, title, url, image, images[], price, original_price, currency, discount_pct, price_formatted, sold_count, rating, store_name, store_url, product_type, promo_tags[]} + seed_query + title — products like the given one (meta.pagination for paging)

### POST /aliexpress/v1/description — 1 credit
Full product description text + images

**Parameters:**
- `product_id` (string, optional) — AliExpress product ID — the digits in the product URL (…/item/<id>.html). Provide product_id OR url.
- `url` (string, optional) — Full product URL — alternative to product_id.
- `description_url` (string, optional) — Direct description URL from a previous product_detail response (advanced — skips one lookup).
- `country` (string, optional, default "US") — Ship-to country (2-letter ISO code, e.g. US, DE, TR). Changes prices, availability and shipping options.
- `currency` (string, optional, default "USD") — Currency for prices (3-letter ISO code, e.g. USD, EUR, TRY).

**Returns:** text + images[] + block_count + format

### POST /aliexpress/v1/shipping — 1 credit
Shipping options per destination country

**Parameters:**
- `product_id` (string, optional) — AliExpress product ID — the digits in the product URL (…/item/<id>.html). Provide product_id OR url.
- `url` (string, optional) — Full product URL — alternative to product_id.
- `country` (string, optional, default "US") — Ship-to country (2-letter ISO code, e.g. US, DE, TR). Changes prices, availability and shipping options.
- `currency` (string, optional, default "USD") — Currency for prices (3-letter ISO code, e.g. USD, EUR, TRY).

**Returns:** options[]{carrier, cost, currency, delivery estimate} + option_count (for the given ship-to `country`)

### POST /aliexpress/v1/store_info — 1 credit
Store profile (+ live seller metrics when a query is supplied)

**Parameters:**
- `store_id` (string, optional) — AliExpress store ID — the digits in the store URL (…/store/<id>). Provide store_id OR store_url.
- `store_url` (string, optional) — Full store URL — alternative to store_id.
- `query` (string, optional) — Any keyword the store sells — unlocks live seller metrics (score, positive rate, feedback count). Optional.
- `country` (string, optional, default "US") — Ship-to country (2-letter ISO code, e.g. US, DE, TR). Changes prices, availability and shipping options.
- `currency` (string, optional, default "USD") — Currency for prices (3-letter ISO code, e.g. USD, EUR, TRY).

**Returns:** store{name, …profile} + seller_metrics{seller_score, seller_positive_rate, seller_feedback_count, seller_country, top_rated} (only when `query` given)

### POST /aliexpress/v1/store_items — 1 credit
Store catalog items (keyword-scoped to the store; shopId alone lists nothing)

**Parameters:**
- `store_id` (string, required) — AliExpress store ID — the digits in the store URL (…/store/<id>).
- `query` (string, required) — Keyword to search within the store (required — the store catalog is only reachable through a keyword).
- `country` (string, optional, default "US") — Ship-to country (2-letter ISO code, e.g. US, DE, TR). Changes prices, availability and shipping options.
- `currency` (string, optional, default "USD") — Currency for prices (3-letter ISO code, e.g. USD, EUR, TRY).
- `page` (integer, optional, default 1) — Page number to start from (easy paging: 1, 2, 3…).
- `max_pages` (integer, optional, default 1) — How many consecutive pages to fetch in one call (1–10, ~48–60 results per page; larger values are capped at 10).

**Returns:** results[]{product_id, title, url, image, images[], price, original_price, currency, discount_pct, price_formatted, sold_count, rating, store_name, store_url, product_type, promo_tags[]} — items of ONE store matching `query` (meta.pagination for paging)

### POST /aliexpress/v1/store_categories — 1 credit
Store category tree

**Parameters:**
- `store_id` (string, optional) — AliExpress store ID — the digits in the store URL (…/store/<id>). Provide store_id OR store_url.
- `store_url` (string, optional) — Full store URL — alternative to store_id.
- `country` (string, optional, default "US") — Ship-to country (2-letter ISO code, e.g. US, DE, TR). Changes prices, availability and shipping options.
- `currency` (string, optional, default "USD") — Currency for prices (3-letter ISO code, e.g. USD, EUR, TRY).

**Returns:** categories[] (the store's category tree; may be empty for small stores)

### POST /aliexpress/v1/deals — 1 credit
SuperDeals / discounted cards (search-derived, sorted by discount)

**Parameters:**
- `query` (string, required) — Product keywords to find deals for.
- `min_discount` (integer, optional, default 0) — Only items discounted at least this % off the original price.
- `sort` (enum, optional, default "orders") — How candidate items are ranked before the discount filter. [one of: best_match, orders, price_low, price_high, newest, default, best_selling, price_asc, price_desc]
- `country` (string, optional, default "US") — Ship-to country (2-letter ISO code, e.g. US, DE, TR). Changes prices, availability and shipping options.
- `currency` (string, optional, default "USD") — Currency for prices (3-letter ISO code, e.g. USD, EUR, TRY).
- `page` (integer, optional, default 1) — Page number to start from (easy paging: 1, 2, 3…).
- `max_pages` (integer, optional, default 1) — How many consecutive pages to fetch in one call (1–10, ~48–60 results per page; larger values are capped at 10).

**Returns:** results[]{product_id, title, url, image, images[], price, original_price, currency, discount_pct, price_formatted, sold_count, rating, store_name, store_url, product_type, promo_tags[]} — only discounted items, sorted by discount_pct (meta.pagination for paging)

**Example request body:**
```json
{
  "query": "wireless earbuds"
}
```

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