Supplier inquiry API

Estimate international shipping before the customer buys

For a sofa, a floor lamp, a treadmill or a large pet crate, the international shipping cost is driven almost entirely by how the item is actually packed: its packed weight, its box dimensions, and how many packages it ships in.

That data is routinely missing or unreliable on 1688 and Taobao product pages. Which leaves your customer with a very practical problem:

They know what the product costs. They have no idea what it costs to get it to their country.

The Supplier inquiry API closes that gap. HIOBuy’s supplier communication service contacts the real supplier before the purchase, confirms packed weight, package dimensions and carton details, and returns the answers to your application as structured data — ready to feed into a shipping estimate.

Why the Product API isn’t enough

The product APIs reliably give you what the marketplace itself knows: title, images, price, SKUs, attributes, shop information. Logistics data is a different story:

• no weight is published at all;
• the weight shown is the net product weight, not the packed weight;
• product dimensions exist, but not the dimensions after packing;
• the weight was typed in by the seller and is only indicative;
• different SKUs pack to different weights;
• a large item ships split across several packages;
• carton quantity, carton weight and carton size are nowhere on the page.

The Product API tells you what the marketplace knows. A supplier inquiry gets you what only the supplier can confirm.

Example: estimating shipping for a sofa

A customer in the United States is looking at a 1688 sofa in your app, priced at ¥800. The product API has already returned the product, price, images, SKUs and attributes — but no reliable packed weight or package dimensions.

So your app cannot answer the only question that matters next:

Product price          ¥800
International shipping ???

On a bulky item, that unknown can easily exceed the price of the product itself.

Your app raises an inquiry:

POST /v1/supplier-inquiries
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "questions": [
    { "type": "packed_weight" },
    { "type": "package_dimensions" },
    { "type": "carton_info" }
  ]
}

HIOBuy hands the task to the supplier communication service, and a China-based operator contacts the actual supplier of that listing. The supplier replies that the sofa ships as two packages:

Package 1   32 kg   110 × 75 × 55 cm
Package 2   18 kg    90 × 60 × 40 cm

Those answers come back to your application as structured JSON, and the whole path looks like this:

1688 product
      ↓  Product API
Price: ¥800
      ↓  reliable logistics data missing
Supplier inquiry
      ↓  HIOBuy contacts the real supplier
Supplier confirms: 2 packages, 32 kg + 18 kg, box dimensions
      ↓  structured logistics data
International shipping estimate (China → United States)
      ↓
The customer sees an approximate total cost before buying

Which is the point of the whole exercise:

Product cost
+ estimated international shipping
= a realistic pre-purchase cost

Where it sits in the HIOBuy APIs

Product API           "What is the product, and what does it cost?"
        ↓
Supplier inquiry API  "How will the supplier actually pack it?"
        ↓
Shipping quote        "Roughly what will it cost to ship internationally?"

Supplier inquiry is the missing layer between product data and a shipping quote.

More than shipping data

Packaging data for shipping estimation is the first and most concrete use of this API, but the same supplier communication channel answers anything only the supplier knows:

MOQ · stock · lead time · neutral packaging · customization · carton information · product details · anything else, via the other type.

So today it gives you packaging data → shipping estimate, and the same call can equally serve supplier information → purchasing decision. See question types for all ten and their answer schemas.

How it works

1. Your app calls POST /v1/supplier-inquiries with a product URL, an optional SKU, and one or more typed questions.
2. HIOBuy creates the inquiry and hands it to the supplier communication service.
3. A China-based operator contacts the supplier of that listing.
4. The supplier replies.
5. The reply is normalized into structured data against the schema of each question type.
6. Your endpoint receives the supplier_inquiry.message_answered webhook, or you poll GET /v1/supplier-inquiries/{id}.

An inquiry is a conversation, not a one-shot request. Once it exists you keep adding follow-up messages to the same thread rather than opening a second one.

Attachments

Some questions are much easier to ask with a picture. A packaging reference, a SKU screenshot, a dimension drawing, a specification sheet — and in the other direction, the supplier’s own packaging photo, a carton photo or a quotation PDF.

Every message, yours and the supplier’s, can carry up to five attachments:

{
  "message": "Please ask the supplier whether they can use packaging similar to this.",
  "attachments": [
    {
      "type": "image",
      "url": "https://example.com/reference-packaging.jpg",
      "filename": "reference-packaging.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}

type is image, document or other. The URL must be https://; anything else is rejected with INVALID_ATTACHMENT_URL.

Supplier replies may include attachments too. They arrive in the message’s attachments array and in the supplier_inquiry.message_answered webhook, alongside the structured answers. You only ever see attachments the inquiry service marked as yours to see — operator working files and supplier chat screenshots stay internal to the service and never reach the API.

Access

Supplier inquiry is off by default. HIOBuy enables it per application after commercial onboarding — contact HIOBuy support to request access.

If the capability is missing or suspended, every endpoint returns 403 SUPPLIER_INQUIRY_NOT_ENABLED.

Supported marketplaces

Anything else fails with UNSUPPORTED_MARKETPLACE. A product is identified by channel + source_product_id, never by the raw URL string, so different link shapes for the same offer resolve to the same product.

Inquiry statuses

pending, processing, waiting_supplier and answered count as active. An application may hold only one active inquiry per product — that is what keeps a single supplier thread per offer. Sending a create request for a product with a completed or failed inquiry reopens that conversation instead of creating a new one.

Webhooks

Register an endpoint in the developer portal and subscribe to the supplier_inquiry category. Signing and retries follow the standard webhook rules.

Every payload carries inquiry_id and product.{channel,source_product_id}.

Error codes

SUPPLIER_INQUIRY_SERVICE_UNAVAILABLE is deliberately generic: provider-side reasons such as balance or account state are not exposed. Quote the request_id when contacting support.

Endpoints