# AliExpress — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for products across AliExpress and instantly access detailed information including product specs, customer reviews, and pricing to make informed purchasing decisions. Browse through product categories and retrieve complete product data directly from URLs to compare options and find exactly what you're looking for.

**Category:** Marketplaces | **Website:** [aliexpress.com/](https://aliexpress.com/) | **Docs:** [parse.bot/marketplace/bfda6d5b-d378-48b6-bf03-d30ffb29c85b/aliexpress-com-api](https://parse.bot/marketplace/bfda6d5b-d378-48b6-bf03-d30ffb29c85b/aliexpress-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-aliexpress-com-api-bfda6d5b/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_categories

Retrieve the top-level category tree from AliExpress. Returns all main shopping categories with their IDs, display names, and icon URLs. No input parameters required.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-aliexpress-com-api-bfda6d5b/get_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_product_by_url

Extract product details from a full AliExpress product URL. Parses the product ID from the URL path and returns the same data as get_product_details. The URL must contain /item/<product_id>.html.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full AliExpress product URL containing /item/<product_id>.html (e.g. 'https://www.aliexpress.com/item/3256811621288203.html'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-aliexpress-com-api-bfda6d5b/get_product_by_url \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### get_product_details

Retrieve detailed information about a specific AliExpress product by its numeric ID. Returns the product name, image gallery, and canonical URL. Uses HTML page extraction with MTOP API fallback.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | AliExpress numeric product ID (e.g. '3256811621288203'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-aliexpress-com-api-bfda6d5b/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>"}'
```

### get_product_reviews

Retrieve customer reviews for a product with pagination. Returns up to `limit` reviews per page (max 50) with ratings, text, reviewer info, and optional images. Also returns aggregate statistics (average rating, total count).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of reviews per page (1–50). |
| `page` | integer | No | Page number for review pagination. |
| `product_id` | string | Yes | AliExpress numeric product ID (e.g. '3256811621288203'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-aliexpress-com-api-bfda6d5b/get_product_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","product_id":"<string>"}'
```

### search_products

Full-text search over AliExpress product listings. Returns up to 60 products per page with pricing, ratings, and sales data. Sorting controls result ordering; pagination via page number. Some products may have null prices depending on seller configuration.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search keyword (e.g. 'wireless earbuds', 'phone case'). |
| `sort_by` | string | No | Sort order for results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-aliexpress-com-api-bfda6d5b/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>","sort_by":"<string>"}'
```