Supplier: Search by Keyword or Image
search_supplier_products[Supply Product]
[What it does] Searches supplier products by keyword or image across the account's visible supplier platforms, returning comparable candidates and echoing the filters that actually took effect.
[When to use] Use it when the merchant wants to find products to sell, compare suppliers, or match an uploaded image; the agent also calls it first to obtain the supplier platform ID and product ID needed before a detail lookup or an import. Trigger words: sourcing, find a supplier, same as this image, best sellers, cost price.
[When not to use] For variants, stock or per-country shipping on one known product use get_supplier_product and list_supplier_product_shipping_methods_and_cost; to import or map use create_pre_publish_products; for products already in the merchant's stores use list_managed_store_products.
[How to use]
Paging depends on scope: cursor paging and a larger page size work only when one supplier platform is selected; an all-platform search returns a fixed slice per platform, so pick a platform before paging.
Each candidate may include
supplier_product_url; Agent and 1688 Dropshipping candidates use the configured DSers product-detail page because those platforms do not expose a public supplier-site URL.Compare only the metrics marked available on a candidate, and only in the base currency; unmarked metrics are unknown, and original supplier prices carry different currencies, so never infer or mix them.
Filters are adapted per platform: trust the echoed effective conditions and tell the merchant which filters did not apply, rather than claiming the results meet every condition.
If some platforms fail while others return candidates, treat it as partial coverage — report the gap and continue; do not retry the whole search or answer "nothing found". [Side effects] Read-only; never imports, edits or maps products. [Confirmation] Not required.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "search_supplier_products"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Result ordering sent to Product BFF. For one explicit supplier_platform_id, the upstream order is preserved without local re-sorting. | recommended |
| cursor | No | Continuation cursor for an explicitly selected supplier_platform_id. Invalid when supplier_platform_id is omitted. | |
| keyword | No | Product name or keyword the user mentioned. Optional. | |
| ship_to | No | Destination country_code from prepare ship_to[], supported by all configured platforms. Defaults to US when omitted. | US |
| image_url | No | Publicly accessible product image URL for visual search. Optional. | |
| max_price | No | Maximum purchase price in USD major units, for example 56.78. The Tool converts it to Product BFF minor units. Supported by AliExpress, 1688 Dropshipping, and Agent. | |
| min_price | No | Minimum purchase price in USD major units, for example 12.34. The Tool converts it to Product BFF minor units. Supported by AliExpress, 1688 Dropshipping, and Agent. | |
| page_size | No | Maximum candidates for an explicitly selected supplier_platform_id, up to 100. Ignored when supplier_platform_id is omitted. | |
| ship_from | No | Country codes from prepare ship_from[]. Supported only by AliExpress and Alibaba. Paste JSON example: ["US"]. | |
| category_ids | No | Category IDs from prepare categories[]. Supported by AliExpress, 1688 Dropshipping, and Agent. Paste JSON example: ["200003482"]. | |
| delivery_time | No | AliExpress only. Fixed preset: THREE_DAYS=Within 3 days, FIVE_DAYS=Within 5 days, SEVEN_DAYS=Within 7 days, TEN_DAYS=Within 10 days. | |
| free_shipping | No | Free-shipping checkbox value. Set to "Free" only for AliExpress, 1688 Dropshipping, or Agent; otherwise omit. This is mapped internally to Product BFF shipping_type without changing its value. | |
| super_factory | No | 1688 Dropshipping only. Set to "YES" when the user selects Super Factory; otherwise omit. | |
| order_count_max | No | Maximum order volume, supported only by 1688 Dropshipping. | |
| order_count_min | No | Minimum order volume, supported only by 1688 Dropshipping. | |
| shipping_method | No | Exact logistics service_id copied from list_supplier_search_filters shipping_methods[]. Supported only by 1688 Dropshipping and Agent; never use the display label. | |
| shipping_time_max | No | Maximum shipping time in days; numeric range supported only by 1688 Dropshipping and Agent. | |
| shipping_time_min | No | Minimum shipping time in days; numeric range supported only by 1688 Dropshipping and Agent. | |
| supplier_platform_id | No | Supplier platform application ID returned by list_supplier_search_filters platforms[].supplier_platform_id. Use filter values and supported_filters from that same platform. Omit to search every visible platform with per-platform filter adaptation. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| candidates | Yes | Comparable supplier product cards | |
| conditions | Yes | Effective search and filter conditions | |
| pagination | Yes | Cursor pagination information | |
| toolcall_response_at | Yes | UTC timestamp when the Tool response was returned, formatted as RFC3339. |