# S 1688 — 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 wholesale products on 1688.com and retrieve detailed information including pricing, specifications, and customer reviews. Access comprehensive product data to compare suppliers and make informed purchasing decisions on China's leading B2B marketplace.

**Category:** Marketplaces | **Website:** [s.1688.com/](https://s.1688.com/) | **Docs:** [parse.bot/marketplace/eceea1c8-5d3d-4edf-b744-6f1b60240aea/s-1688-com-api](https://parse.bot/marketplace/eceea1c8-5d3d-4edf-b744-6f1b60240aea/s-1688-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-s-1688-com-api-eceea1c8/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_product_detail

Fetch detailed product information for a specific 1688 offer ID. Returns SKU selector data including pricing tiers per variant, available properties (colors, sizes), images, trade model (min order, stock), and promotion info. The offer_id is available from search_products results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `offer_id` | string | Yes | The 1688 offer ID (numeric string from search_products results offerId field) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-s-1688-com-api-eceea1c8/get_product_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offer_id":"<string>"}'
```

### get_product_reviews

Fetch customer reviews for a product. Requires both the offer_id and the seller's loginId (available from search_products results). Returns a list of reviews which may be empty if the product has no reviews yet. Each review includes star rating, content, and date when available.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `login_id` | string | Yes | The seller's loginId (from search_products results loginId field) |
| `offer_id` | string | Yes | The 1688 offer ID |
| `page` | integer | No | Page number for pagination |

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

### search_by_image

Image-based product search (拍立淘 / Pailitao). Given a publicly accessible product image URL, returns visually matching wholesale products from 1688.com. Internally registers the image via putImage API then queries the recommendation engine with the image ID. Each page returns up to 40 items. Results are auto-iterated via integer page counter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `image_url` | string | Yes | Publicly accessible image URL to search by (e.g. an alicdn.com product image URL) |
| `page` | integer | No | Page number for pagination |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-s-1688-com-api-eceea1c8/search_by_image \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"<string>","page":"<integer>"}'
```

### search_products

Full-text search over 1688.com product listings by keyword. Returns a paginated list of product offers with seller info, pricing, and location. Each page returns up to 40 items. Paginates via integer page counter. Results include enough seller context (loginId) to drill into reviews.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination |
| `query` | string | Yes | Search keyword (Chinese or English) |

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