Advanced product endpoints

Seller shop product search: POST /v1/products/seller/search

Additional routes for sourcing workflows (1688-heavy unless noted). Overview: Products.

Endpoint index

1688 product top list

POST /v1/products/top-list returns products in a 1688 category ranking. Send a JSON body with a key that has the product:search scope; see Authentication.

curl https://api.hiobuy.com/v1/products/top-list \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"1688","rank_id":"1111","rank_type":"complex","limit":10,"language":"en"}'

The response is a StandardTopList object, with request_id added at the top level. This example shows one item; the real items array can be empty or contain up to the requested limit.

{
  "channel": "1688",
  "rank_id": "1111",
  "rank_name": "Overall ranking",
  "rank_type": "complex",
  "language": "en",
  "items": [
    {
      "item_id": "1234567890",
      "title": "Example product",
      "translate_title": "Example product",
      "image_url": "https://example.com/product.jpg",
      "sort": 1,
      "service_list": [
        "sendGoods48H"
      ],
      "buyer_num": 120,
      "sold_out": 800,
      "goods_score": "4.8"
    }
  ],
  "request_id": "req_example"
}

1688 daily sales trend

POST /v1/products/daily-sales-trend returns daily unit sales for one 1688 product.

The date range includes both endpoints and cannot exceed 90 calendar days. Invalid dates and longer ranges return a validation error.

curl https://api.hiobuy.com/v1/products/daily-sales-trend \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"1688","product_id":"1234567890","start_date":"20260901","end_date":"20260903"}'

The response is a StandardDailySalesTrend object, with request_id added at the top level. The figures below are illustrative, not live sales data.

{
  "channel": "1688",
  "product_id": "1234567890",
  "start_date": "20260901",
  "end_date": "20260903",
  "points": [
    {
      "date": "20260901",
      "quantity": 100
    },
    {
      "date": "20260902",
      "quantity": 85
    },
    {
      "date": "20260903",
      "quantity": 92
    }
  ],
  "request_id": "req_example"
}

These two endpoints return the standard response structures shown above. Their current gateway routes do not apply response_format: "upstream".

Upstream response format {#upstream-format}

Add "response_format": "upstream" to return vendor JSON in an upstream envelope instead of standard models. See Response format.

Seller shop search

POST /v1/products/seller/search lists products from a specific 1688 or Weidian seller shop. The request requires an API key with the product:search scope; see Authentication for the authentication header and Product response models for the complete normalized product fields.

Request body

Send a JSON object. channel and the seller identifier for that channel are required.

The Weidian request does not use 1688-only price or filter parameters. For a stable cross-channel integration, use the default standard response format.

1688 request

{
  "channel": "1688",
  "seller_open_id": "YOUR_1688_SELLER_OPEN_ID",
  "keyword": "jacket",
  "page": 1,
  "page_size": 20
}

Weidian request

{
  "channel": "weidian",
  "shop_id": "YOUR_WEIDIAN_SHOP_ID",
  "page": 1,
  "page_size": 20,
  "sort_rule": 2
}

Standard response

The default response is a normalized product list at the top level, not inside a data object. This empty-result example shows the envelope without inventing product or seller data:

{
  "request_id": "REQUEST_ID",
  "channel": "1688",
  "keyword": "jacket",
  "page": 1,
  "page_size": 20,
  "total": 0,
  "items": []
}

Each items[] entry uses the standard product list item structure: id, channel, source_product_id, source_url, title (original, translated, language), price (original_currency, original_amount, display_currency, display_amount), image, and seller (name, with optional id and shop_url). Sales, stock, and status fields can be present when the upstream marketplace provides them. Do not assume a full product-detail or SKU payload in standard results; use the relevant product-detail API or the Weidian upstream format when that source-specific data is required.