# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/aliexpress/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/aliexpress/get-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/aliexpress/get-product-by-url \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/aliexpress/get-product-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/aliexpress/get-product-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/aliexpress/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>","sort_by":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.