# AliExpress Store Product

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/aliexpress/store/product` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/aliexpress-store-product |

## Description

AliExpress Store Product API: list products from an AliExpress seller store by URL or store ID. Returns store metadata and product cards (~40 SSR items) as JSON via browser rendering. Pagination is not supported.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/aliexpress/store/product' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Store 1101705614 all-items listing

```json
{
  "results": [
    {
      "price": 0.99,
      "title": "Car Phone Holder Magnetic Dashboard Mount",
      "rating": 4.8,
      "currency": "USD",
      "image_url": "https://ae-pic-a1.aliexpress-media.com/kf/Sexample1.jpg",
      "product_id": "3256802427534863",
      "sold_count": 1200,
      "listing_url": "https://www.aliexpress.com/item/3256802427534863.html"
    },
    {
      "price": 8.39,
      "title": "Universal Car Air Vent Phone Mount Stand",
      "rating": 4.5,
      "currency": "USD",
      "image_url": "https://ae-pic-a1.aliexpress-media.com/kf/Sexample2.jpg",
      "product_id": "1005008808856805",
      "sold_count": 800,
      "listing_url": "https://www.aliexpress.com/item/1005008808856805.html"
    }
  ],
  "store_id": "1101705614",
  "seller_id": "911768809",
  "store_name": "Nunua Car Car Store",
  "owner_member_id": "251242175"
}
```

## Documentation

## Overview
The **AliExpress Store Product API** returns product listings from an AliExpress seller store **all-items** page (`/store/{id}/pages/all-items.html`). Pass a **store URL** or **numeric store ID** and receive structured JSON with store metadata, product cards, prices, ratings, and sold counts.

AliExpress store catalogs paginate via JavaScript. Piloterr uses **browser rendering** to load the all-items page and extract listing cards from the SSR HTML. This endpoint returns the ~40 products visible in the initial render. **Pagination is not supported.**

Use each result's `listing_url` with **AliExpress Product** for full PDP details and seller identity.

## Quickstart
```
GET https://api.piloterr.com/v2/aliexpress/store/product?query=https://www.aliexpress.com/store/1101705614
GET https://api.piloterr.com/v2/aliexpress/store/product?query=1101705614&sort=orders
```

Via POST:
```
POST https://api.piloterr.com/v2/aliexpress/store/product
Content-Type: application/json

{"query": "https://www.aliexpress.com/store/1101705614", "sort": "orders"}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Store URL (`/store/{id}`) or numeric store ID |
| `sort` | string | no | Sort alias: `default`, `bestmatch`, `orders`, `new`, `price` |
| `return_page_source` | boolean | no | Return raw HTML as `{"result": "..."}` (default: `false`) |

## Accepted inputs
| Format | Example |
|---|---|
| Store URL | `https://www.aliexpress.com/store/1101705614` |
| All-items URL | `https://www.aliexpress.com/store/1101705614/pages/all-items.html` |
| Store ID | `1101705614` |

Rejected (400): search URLs, product URLs, empty query.

## Response: store metadata
| Field | Type | Description |
|---|---|---|
| `store_id` | string | Public store ID from the URL |
| `seller_id` | string | Internal AliExpress store ID from page config |
| `owner_member_id` | string | Seller member ID when available |
| `store_name` | string | Store display name |

## Response: each listing (`results[]`)
| Field | Type | Always present | Description |
|---|---|---|---|
| `product_id` | string | yes | AliExpress product ID |
| `title` | string | yes | Product title |
| `listing_url` | string | yes | Canonical URL: `https://www.aliexpress.com/item/{id}.html` |
| `image_url` | string | no | Thumbnail URL |
| `price` | number | no | Sale price parsed from `pdp_npi` |
| `currency` | string | no | ISO 4217 code (`USD`, `EUR`, …) |
| `rating` | number | no | Star rating, 1 decimal |
| `sold_count` | integer | no | Units sold when displayed on the card |
| `review_count` | integer | no | Review count when available |

## Workflow
1. **Store Product**: list visible store products (this endpoint)
2. **Product**: fetch full PDP JSON from any `listing_url`

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Store all-items page not parseable |
| `500` | Rendering or parsing error |

## Notes
- AliExpress store pagination is JavaScript-only; only the SSR-visible ~40 products are returned.
- Sort aliases map to AliExpress `shop_sortType` params.
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Seller catalog snapshot**: inspect the top ~40 products from a competitor store
- **Dropshipping research**: audit visible store inventory and pricing
- **Store monitoring**: track listing and price changes on the SSR slice
- **Product enrichment**: chain Store Product → Product for specs and delivery data