Scavio Aliexpress

AliExpress via Scavio

Search AliExpress products, browse a category, pull one product in full with all its SKU variants, read translated customer reviews, and open a seller's storefront and catalogue. All endpoints return structured JSON.

When to trigger

Use this skill when the user asks to:

• Search AliExpress for a product with price, rating, units-sold and free-shipping filters
• Browse a whole AliExpress category and sort by best sellers (units ordered)
• Pull one product in full - current and original price, discount, every SKU variant group, the full image gallery, and the seller
• Read translated buyer reviews with star rating, buyer country, per-SKU variant and photos
• Open a seller's profile (followers, rating, catalogue size) and page through their catalogue
• Do price comparison, dropshipping research, or product-market research on AliExpress

Setup

Get a free API key at scavio.dev (50 free credits to get started, no card required):

export SCAVIO_API_KEY=sk_live_your_key

Every request is a POST with a JSON body and:

Authorization: Bearer $SCAVIO_API_KEY

Endpoints

Base URL: https://api.scavio.dev. Every AliExpress endpoint costs 1 credit.

Two facts that decide how you call this

search and category share one product shape. The same filters (sort_by, min_price, max_price, ship_from, free_shipping, ship_to, currency) apply to both. Use search for a keyword, category for a category id.

ship_to changes what appears, not just prices. The 2-letter destination country changes prices, VAT and delivery estimates - and which items appear at all, because AliExpress filters by shippability. Send it explicitly for a stable result.

When you set min_price/max_price, total_results comes back null. AliExpress reports a broadened match count under a price filter, so the total is suppressed rather than shown wrong. The products array is still correct.

Parameters

Search (/search)

Category (/category)

Same fields as search, but category_id is required and there is no query.

Reviews (/reviews)

Product (/product)

Seller (/seller) and Seller Products (/seller-products)

Examples

import requests

BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Search, best sellers first, shipped to the UK, priced in GBP
found = requests.post(f"{BASE}/api/v1/aliexpress/search", headers=HEADERS,
    json={"query": "usb c hub", "sort_by": "orders", "max_price": 40,
          "free_shipping": True, "ship_to": "GB", "currency": "GBP"}).json()

row = found["data"]["products"][0]
product_id = row["product_id"]

# 2. One product in full - price, every SKU variant group, the seller
product = requests.post(f"{BASE}/api/v1/aliexpress/product", headers=HEADERS,
    json={"product_id": product_id, "ship_to": "GB", "currency": "GBP"}).json()
store_id = product["data"]["seller"]["store_id"]

# 3. Reviews with photos only
reviews = requests.post(f"{BASE}/api/v1/aliexpress/reviews", headers=HEADERS,
    json={"product_id": product_id, "filter": "image", "page_size": 50}).json()

# 4. The seller's catalogue
catalogue = requests.post(f"{BASE}/api/v1/aliexpress/seller-products", headers=HEADERS,
    json={"store_id": store_id, "page": 1}).json()

curl:

curl -s https://api.scavio.dev/api/v1/aliexpress/search \
  -H "Authorization: Bearer $SCAVIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"mechanical keyboard","sort_by":"orders","ship_to":"US","currency":"USD"}'

Response shape

Every response uses the envelope { data, response_time, credits_used, credits_remaining }. data carries the product/review/seller payload described in the table above (products[], products_count, total_results, reviews[], seller, and so on).

Guardrails

• Every call is 1 credit, including one that comes back empty.
• Send ship_to and currency explicitly - they change prices, delivery estimates and which items appear at all.
• Under a min_price/max_price filter, total_results is null by design; use the products array, not the total.
• The product, seller and seller-products endpoints typically take 20-60 seconds. Size your client timeout accordingly (120s is safe).
• Never invent a sort_by or filter value; unrecognised values are rejected before the request runs.
• Never fabricate prices, ratings, seller details or review text. Only return what the API returned.
• Review text is written by real buyers. Summarise; do not build profiles of individuals.

Failure handling

• 400 means an invalid or missing parameter. Fix and retry.
• 401 means the API key is invalid or missing. Check SCAVIO_API_KEY.
• 404 means the product, seller or category could not be resolved.
• 429 means rate or usage limit exceeded. Wait before retrying. See rate limits.
• 502 / 503 mean the source is temporarily unavailable - wait a few seconds and retry, up to a few times.
• An empty result set is usually the filters - widen the price range, drop free_shipping, or change ship_from.
• If SCAVIO_API_KEY is not set, prompt the user to export it before continuing.