Provides complete product search capabilities through the official 1688 Open Platform API, including 9 core interfaces.
Authentication Instructions
Each Skill has a built-in independent authentication module (scripts/auth.py），does not depend on any external Skill。
The Token cache of all 1688 Skills points to the same fixed path, achieving "independent operation + authentication happens only once".
- Token cache path:
skills/.1688_token_cache.json(shared by all 1688 Skills) - After any Skill completes authentication on its first request, other Skills directly reuse the cache
- Automatically refresh with refresh_token before the Token expires
- Supports
ALI1688_REFRESH_TOKEN(automatic refresh) andALI1688_ACCESS_TOKEN(direct use) two modes
Configuration
Set environment variables in the OpenClaw config:
{
skills: {
entries: {
"1688-product-search": {
env: {
ALI1688_APP_KEY: "your-app-key",
ALI1688_APP_SECRET: "your-app-secret",
ALI1688_REFRESH_TOKEN: "your-refresh-token"
}
}
}
}
}
How to obtain AppKey / AppSecret / Token
If you encounter Token-related errors (such as 401, signature failure, Token expired), follow these steps:
Step 1: Register as a developer & create an application → obtain AppKey + AppSecret
- Open 1688 Open Platform, and log in with your 1688 account
- Go to Control Center
- Click "My Applications" → "Create Application"
- Fill in the application information and submit for review
- After the review is approved, you can see AppKey and AppSecret
Step 2: Subscribe to a solution → obtain API call permissions
- Open Cross-border ERP/Independent Site SaaS Digital Solution
- Click "Subscribe Now" to bind the solution to your application
- Only after successful subscription does the application have permission to call the APIs in the solution
Step 3: User authorization → obtain access_token + refresh_token
- Visit the authorization page in a browser (replace YOUR_APPKEY and YOUR_REDIRECT_URI):
https://auth.1688.com/oauth/authorize?client_id=YOUR_APPKEY&site=1688&redirect_uri=YOUR_REDIRECT_URI
- Log in with your 1688 account and agree to authorize
- The page will redirect to your callback address, and the URL will contain the
codeparameter - Exchange the code for a Token (valid for a short time, must be used within 10 minutes):
curl -X POST "https://gw.open.1688.com/openapi/param2/1/system.oauth2/getToken/YOUR_APPKEY" \
-d "grant_type=authorization_code" \
-d "need_refresh_token=true" \
-d "client_id=YOUR_APPKEY" \
-d "client_secret=YOUR_APPSECRET" \
-d "redirect_uri=YOUR_REDIRECT_URI" \
-d "code=授权码"
- The returned result includes:
access_token— used to call APIs (valid for about 10 hours)refresh_token— used to refresh access_token (valid for about half a year)
Step 4: Configure into environment variables
ALI1688_APP_KEY= the application's AppKeyALI1688_APP_SECRET= the application's AppSecretALI1688_REFRESH_TOKEN= the refresh_token obtained in the previous step (recommended, supports automatic refresh)ALI1688_ACCESS_TOKEN= the access_token obtained in the previous step (backup, must be manually replaced after expiration)
Common Token errors and solutions
| Error | Cause | Solution |
|---|---|---|
HTTP 400 refresh failed |
refresh_token is invalid or has expired | Go through Step 3 authorization again to obtain a new refresh_token |
HTTP 401 unauthorized |
access_token is expired or invalid | Set ALI1688_REFRESH_TOKEN to enable automatic refresh |
签名错误(code=25) |
AppSecret is incorrect | Check whether ALI1688_APP_SECRET matches the application details page |
无权限调用 |
Solution not subscribed | Go back to Step 2 to subscribe to the corresponding solution |
refresh_token 半年后过期 |
Token expires naturally | Go through Step 3 authorization again |
Reference links
- 1688 Open Platform - Control Center
- API call instructions
- Signature rules
- Authorization instructions
- Solution subscription
Usage
1. Category query
# 查询所有一级类目（英语）
python3 scripts/product_search.py category 0
# 查询中文类目
python3 scripts/product_search.py category 0 --language en
2. Multilingual keyword search
# 英文关键词搜索
python3 scripts/product_search.py keyword-search "dress" --country en
# 中文关键词搜索
python3 scripts/product_search.py keyword-search "连衣裙" --country en
# 带筛选条件的搜索
python3 scripts/product_search.py keyword-search "dress" --country en --filter "shipIn48Hours,shipIn24Hours" --sort '{"price":"asc"}'
3. Multilingual image search
Image search supports three methods, in priority order:Local image file > imageId > image URL
# 方式一：本地图片文件（推荐）
# 自动压缩（>300KB）→ base64编码 → 上传获取imageId → 图搜
python3 scripts/product_search.py image-search --image-path "/path/to/your/image.jpg" --country en
# 方式二：图片URL（直接用 imageAddress 字段图搜，无需上传）
python3 scripts/product_search.py image-search --image-url "https://example.com/image.jpg" --country en
# 方式三：已有 imageId（由 upload-image 接口返回）
python3 scripts/product_search.py image-search "your_image_id" --country en
# 上传图片获取imageId（单独使用）
python3 scripts/product_search.py upload-image "/path/to/your/image.jpg"
Processing flow when the user sends an image file or screenshot:
⚠️ Note: The 1688 image upload API (
product.image.upload)imageBase64methodonly supports images from the 1688 platform itself, and returns an invalid imageId for local screenshots/external images ("0"）。
Recommended handling strategy:
- Ask the user for the image'soriginal source URL
- If the URL contains
alicdn.com, directly use theimageAddressfield for image search (verified effective) - If the URL does not contain
alicdn.com, first download it locally, then upload it via base64 to try to obtain an imageId; if the imageId is still"0", fall back toimageAddressimage search
Local file base64 upload process (for reference only, success rate is limited):
- If the image is larger than 300KB, first compress it with Pillow (adjust quality first, then reduce resolution), then base64-encode it
- Call the
product.image.uploadAPI (uploadImageParamfield wrapper, containingimageBase64) to upload - If a valid imageId is returned (not
"0"), use imageId for image search; otherwise fall back toimageAddressimage search
Processing flow when the user provides an image URL:
- Determine the domain of the image URL:
- is
alicdn.comdomain(such ascbu01.alicdn.com、img.alicdn.com, etc.): directly pass theimageAddressfield to the image search API, no download needed - not
alicdn.comdomain(such as images uploaded by the user, images from other e-commerce platforms, etc.): first download the image to a local temporary file, then follow the local file image search process (compress → base64 → upload → imageId → image search)
- is
4. Multilingual product details
⚠️ Note: This API supports querying only 1 product at a time, and does not support batch querying of multiple product IDs.
# 查询单个商品详情
python3 scripts/product_search.py product-detail "offer_id"
5. Multilingual product store search
# 根据商家ID搜索商品
python3 scripts/product_search.py shop-search "seller_open_id" --country en
6. Multilingual product recommendations
# 基于关键词的商品推荐
python3 scripts/product_search.py offer-recommend "keyword" --country en
7. Product pool product retrieval
Retrieve a product list from a business-customized product pool; product pool access permission is required. For paginated queries, the same taskId。
# 拉取品池商品（offerPoolId 和 taskId 为必填）
python3 scripts/product_search.py pool-pull --pool-id 111 --task-id 1 --page-no 1 --page-size 10
# 指定类目和排序
python3 scripts/product_search.py pool-pull --pool-id 111 --task-id 1 --cate-id 11 --sort-field order1m --sort-type DESC --page-no 1 --page-size 10
Request parameters:
| Parameter | Type | Required | Description | Example value |
|---|---|---|---|---|
--pool-id |
Long | ✅ | Product pool ID (business-customized and access-controlled; obtain it from the connected business. Passing an arbitrary value will cause an error. For sourcing and proxy purchasing, it is recommended to use the keyword search API) | 111 |
--task-id |
String | ✅ | Query task ID; for paginated queries, the same taskId must be used consistently (e.g., if a product pool has 10,000 products and 1,000 are queried per page, 10 queries are needed, and the same taskId must be passed for all 10 queries) | 1 |
--page-no |
Integer | ✅ | Page number | 1 |
--page-size |
Integer | ✅ | Number per page | 10 |
--cate-id |
Long | ❌ | Category ID | 11 |
--language |
String | ❌ | Language, default en | en |
--sort-field |
String | ❌ | Sort field:order1m(Sales in the last 1 month) / buyer1m(Number of buyers in the last 1 month) |
order1m |
--sort-type |
String | ❌ | Sort rule:ASC / DESC |
DESC |
Return result structure:
{
"result": {
"success": "true",
"code": "200",
"result": [
{
"offerId": 111111,
"bizCategoryId": "111111",
"offerPoolTotal": 122211
}
]
}
}
| Field | Type | Description | Example value |
|---|---|---|---|
result.success |
String | Whether successful | true |
result.code |
String | Error code | 200 |
result.result[].offerId |
Long | Product ID | 111111 |
result.result[].bizCategoryId |
String | The institution's category ID | 111111 |
result.result[].offerPoolTotal |
Integer | Total number of product pool (returned for every offer) | 122211 |
8. Related product recommendations
# 基于商品ID的相关推荐
python3 scripts/product_search.py related-recommend "offer_id" --country en
9. Upload image to get imageId
# 上传本地图片获取imageId
python3 scripts/product_search.py upload-image "/path/to/image.jpg"
Intelligent image compression feature: When the uploaded image file is larger than 300KB, the system will automatically perform intelligent compression to ensure the image size meets the requirements of the 1688 API. The compression process will:
- Automatically detect the image format and convert it to JPEG (if needed)
- Keep the file size within 300KB while maintaining the best image quality
- Temporarily generate the compressed image for upload, and automatically clean up the temporary file after completion
- Output detailed compression logs (original size → compressed size)
This ensures that no matter what the size of the image provided by the user is, a valid imageId can be successfully obtained for subsequent image search operations.
Important notice
Image search trigger
When instructions related to image search such as "image search for the same item", "find the same item", "search for items by image", "image search for the same item" are received, the system will automatically call the image search interface (product.search.imageQuery) instead of the keyword search interface.
Interface trigger rules
| User intent | Interface to call | Description |
|---|---|---|
| Image search for the same item, find the same item, search for items by image | product.search.imageQuery |
Image search |
| Products from the same store, products from the same merchant | product.search.querySellerOfferList |
Need to get from product details sellerOpenId |
| Similar products, related products, related recommendations | product.related.recommend |
Recommended based on product ID; some products may return empty |
| Product recommendation | product.search.offerRecommend |
Recommended based on keywords |
| Fetch xx product pool, fetch product pool, fetch product pool products | pool.product.pull |
Need to provide offerPoolId and taskId |
Product query results must expose the product ID and link
The return results of all product query interfaces (keyword search, image search, store search, product recommendation, etc.) must show the following two core fields to the user:
offerId(Product ID): the unique identifier of the product, which can be used for subsequent operations such as querying product details and related recommendations- Product link: Prefer to use
promotionURL(promotional link with tracking parameters); if not available, usehttps://detail.1688.com/offer/{offerId}.html
Display format example (Markdown table or list is acceptable):
商品ID: 683381849222
链接: https://detail.1688.com/offer/683381849222.html?fromkv=...（promotionURL）
It is prohibited to display only the product title and price without exposing the product ID and link. Users need to use the product ID for subsequent operations.
Parameter description
Common parameters
| Parameter | Description | Default value | Optional values |
|---|---|---|---|
--country / --language |
Language code | en |
en / ja / ko / ru / vi / es , etc.,does not support zh |
--beginPage |
Start page | 1 |
Number |
--pageSize |
Number per page | 20 |
Number, maximum 50 |
Note: When the API parameters include beginPage , the default is 1; when they include pageSize , the default is 20; when they include country or language , the default is en。
⚠️ Important：
countryandlanguageparametersneither supportszh(Chinese). Regardless of whether the user asks in Chinese or English,en(English) must be passed as the default value. Passingzhwill cause the API to report an error or return abnormal results.
Filter conditions (filter)
Supports multiple filter conditions, with multiple conditions separated by English commas:
shipIn24Hours- Ships within 24 hoursshipIn48Hours- Ships within 48 hourscertifiedFactory- Certified factoryisOnePsale- Supports dropshippingnew7- New arrivals in 7 days1688Selection- 1688 Selected
Example:--filter "shipIn48Hours,certifiedFactory,isOnePsale"
Sort parameters (sort)
Supports sorting by different dimensions:
price- Wholesale pricerePurchaseRate- Repurchase ratemonthSold- Monthly sales
Example:--sort '{"price":"asc"}' or --sort '{"monthSold":"desc"}'
Output format
JSON format, directly returning the raw response data of the 1688 API.
Important note: All product query results will include the product ID (offerId field), which is the unique identifier of the product and can be used for subsequent product detail queries or other operations.
Error handling
- No mock data is returned on failure: When the API call fails, parameters are incorrect, or a network exception occurs, an error message JSON is returned directly and the process exits
- Error format：
{"error": "具体的错误信息"} - Exit code: Returns exit code 1 on failure and 0 on success
Product result field descriptions
For all product list APIs (keyword search, image search, shop search, product recommendations, etc.), the query results must display all of the following available fields:
| Field | Description | Required display |
|---|---|---|
offerId |
Product ID, unique identifier | ✅ Required |
subject |
Product title (Chinese) | ✅ Required |
subjectTrans |
Product title (English translation) | Display if available |
imageUrl |
Product main image URL | ✅ Required |
priceInfo.price |
Wholesale price | ✅ Required |
priceInfo.promotionPrice |
Promotional price | Display if available |
priceInfo.consignPrice |
Dropshipping price | Display if available |
monthSold |
Monthly sales | ✅ Required |
repurchaseRate |
Repurchase rate | ✅ Required |
minOrderQuantity |
Minimum order quantity | Display if available |
tradeScore |
Shop rating | Display if available |
sellerDataInfo.tradeMedalLevel |
Merchant level (star rating) | Display if available |
sellerDataInfo.compositeServiceScore |
Comprehensive service score | Display if available |
productSimpleShippingInfo.shippingTimeGuarantee |
Shipping time (24h/48h) | Display if present |
isOnePsale |
Whether dropshipping is supported | Display when true |
isSelect |
Whether it is 1688 Selected | Display when true |
offerIdentities |
Product tag list | Display if present |
sellerIdentities |
Seller tag list | Display if present |
Tag value meaning description (offerIdentities / sellerIdentities)
| Tag value | Meaning |
|---|---|
tp_member |
TrustPass member |
createDate / modifyDate |
Listed/Updated time |
| Product link | Prefer promotionURL, otherwise use https://detail.1688.com/offer/{offerId}.html |
API endpoint address
| Endpoint | Full URL |
|---|---|
| Category query | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/category.translation.getById/${APPKEY} |
| Keyword search | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.keywordQuery/${APPKEY} |
| Image search | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.imageQuery/${APPKEY} |
| Product details | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.queryProductDetail/${APPKEY} |
| Shop search | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.querySellerOfferList/${APPKEY} |
| Product recommendations | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.offerRecommend/${APPKEY} |
| Product pool product retrieval | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/pool.product.pull/${APPKEY} |
| Related recommendations | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.related.recommend/${APPKEY} |
| Image upload | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.image.upload/${APPKEY} |
1688 API general description
API integration key points
- Language support: by default uses
country=en, but returned fields include both Chinese and English- Chinese field example:
subject - English field example:
subjectTrans - ⚠️
countryandlanguageparameters both do not supportzh, optional values areen/ja/ko/ru/vi/es, etc.,regardless of the situation, by default passen
- Chinese field example:
- Access Token: the access_token generated by the current solution ispermanently validthat is
- Filter conditions: supports multiple product filter conditions (shipping time, certified factory, dropshipping, etc.)
- Sorting function: supports sorting by price/repurchase rate/monthly sales, but only effective for the current page
Important limitations
- Data volume limit: each query returns at most 2000 products
- Image search: it is recommended to use only 1688 image URLs; success rates for other domains are unstable
- Price display: the API returns the original price; the promotional price will apply at checkout
Service list mapping
sendGoods24H→ 24-hour shippingsendGoods48H→ 48-hour shipping
API reference documentation
For complete API endpoint and data structure documentation, please refer to references/api.md。