Documentation index for LLMs

English-first index of the HIOBuy Public API docs. Each link points to the canonical HTML page under /en/api-docs/.

Machine-readable exports

Integrating an LLM agent? Start with Agent API & MCP. For REST backends, read Response format (standard default) then Order preview / Create order.

Getting started

  • Introduction — HioBuy Public API v1 docs for Taobao, 1688, and Weidian: product search/detail, multilingual fields, auth, warehousing, sandbox vs production onboarding.
  • Authentication — Authenticate REST calls with Bearer credentials, scoped headers including language IDs, sandbox and production gateways, rotating secrets securely.
  • Response format — Understand the standardized JSON envelope (ret, msg, data, retcode), pagination, multilingual titles, bilingual error semantics, timestamps, and payloads.
  • Languages — Which marketplace languages exist, query parameters per channel, multilingual titles, storefront localization rules for shopper experiences.
  • Errors — Decode retcodes, bilingual error bodies, timeouts, webhook signature failures, validation traps, retries, SLA guidance across platform APIs.
  • Rate limits — Per-endpoint quotas, crawler vs burst limits, warehousing vs search policies, backoff strategies and monitoring quotas for integrations.
  • Sandbox — hio_test_* sandbox keys: sb_* fixtures for products, orders, /v1/fulfillment/* (packages, returns, VAS), support tickets; sandbox_trigger quotas; no auto webhooks vs hio_live_*.

Products

  • Overview — Overview of catalogue APIs tying together keyword/image search, detail payloads, parsers, uploads, advanced utilities, SKU refresh patterns.
  • Product detail — Fetch bilingual detail with normalized SKUs/stock matrices, promotions, translations, sourcing metadata plus refresh cadence considerations.
  • Keyword search — POST keyword searches with paging, filters and sorting knobs for Taobao and 1688 discovery inside shopping-agent storefront dashboards.
  • Upload image — Securely upload buyer photos to obtain searchable media identifiers power similarity search personalization flows.
  • Image search — Taobao-compatible image retrieval with scoring facets duplicate guards multilingual relevance inside purchasing automation stacks.
  • Parse URL — Turn share links/Taobao shortened URLs into channel plus source identifiers for crawler ingestion or analytics ingestion.
  • Response models — Schemas for bilingual titles price ladders promotions variants (incl. prop_id/value_id) warehousing inventory signals returned by catalogue integrations.
  • 1688 categories — 1688 category ID reference for product search filters: top-level list plus downloadable full category tree with English and Chinese names.
  • Advanced endpoints — Experimental or auxiliary catalogue utilities including official taxonomy helpers seller tooling deep links beyond baseline APIs.

Procurement orders

  • Overview — Procurement lifecycle: previews, placements, payouts, cancellations, consolidated response models for storefront orchestration.
  • Preview — Domestic quotations before submit including fees coupons express lines SKU breakdown for cart preview experiences.
  • Create order — Create authenticated procurement payloads with idempotency buyer notes warehousing hooks aligned with previews.
  • Pay order — Trigger secure payouts poll capture states reconcile rejects for domestic legs of concierge checkout flows.
  • 1688 payment methods — Query a native 1688 order's supported payment channels to diagnose KJB eligibility. Includes buyer main-account requirements, channel codes, CNY fen and error handling.
  • 1688 Cross-border Pay link — Get a 1688 Cross-border Pay cashier URL for up to 30 orders without submitting payment. Request fields, batch exclusions, scopes, errors and Sandbox restrictions.
  • Detail & list — Polling endpoints for SKU manifests domestic milestones payment timelines plus batch retrieval for dashboards.
  • Domestic trace — Courier domestic traces exception codes SLA insights before warehouse consolidation outbound international legs.
  • Cancel — Cancel unpaid or reversible domestic procurements documenting reject flows refunds partial reversals safeguards.
  • Response models — Structures for previews payments logistics covering nested SKU services coupons warehousing slots concierge assistants.

Fulfillment (warehouse)

  • Warehouse authorization — Warehouse vs self fulfillment; under warehouse mode choose HioBuy procurement or self procurement; portal channel authorization before /v1/orders and /v1/fulfillment.
  • Overview — Cross-border warehousing automations quotations shipment batches airway bills tracking wallet balances payouts APIs hub.
  • WH-DEV testing guide — Test the full HioBuy warehouse fulfillment workflow with a WH-DEV code: inbound, package received, shipping quotes, shipment packing, ready for payment, dispatch, tracking.
  • Inbound notice — POST /v1/fulfillment/inbounds/create inbound notice MOCK: tracking items VAS sandbox fixtures and protocol error codes.
  • Packages — GET packages list/detail/tracking + unclaimed list/claim (masked tracking, exact match).
  • Package returns — POST/GET returns return-to-seller: create, confirm fee, cancel; sandbox ret_* fixtures.
  • Locations — GET /v1/fulfillment/locations read-only catalog: Chinese receiving address, destinations, hours, receiving status.
  • Value-added services — GET value-added-services catalog: stable service codes, stages, pricing types and current rates.
  • Service requests — POST/GET service-requests: atomic create, list/detail, confirm quoted fees; photos/QC results.
  • Shipping channels — `GET /v1/fulfillment/shipping/channels` lists active, price-configured warehouse shipping channels. Expand regions, services, and reference rate cards. Language header; amounts are CNY_minor.
  • Shipping quotes — `POST /v1/fulfillment/shipping/quotes` declared-data shipping estimates. Single-package shorthand or packages[]; Language header; amounts are CNY_minor.
  • Shipments — POST create/pay/cancel/intercept and GET list + GET {id}: PENDING → WAIT_PAYMENT → WAIT_SHIP → SHIPPED → SIGNED; lightweight list vs full detail (boxes, timeline, international_tracking).
  • International tracking — GET /v1/fulfillment/shipments/{id}/tracking carrier scan events — not shipment detail timeline or tracking numbers.
  • Wallet balance — Wallet payouts recharge thresholds settlement nuances multi-currency notes for warehousing finance dashboards connectors.
  • Finance — List fulfillment wallet transactions and request/download overseas commercial invoices; amounts use CNY_minor like Balance.
  • Support tickets — Human support tickets for HioBuy warehouse fulfillment: packages, returns, shipments, VAS, billing, and related API issues.
  • Response models — Field reference for quotes, preview/create pricing, shipment list/detail, balance, and international tracking events (CNY_minor).
  • Webhooks — Fulfillment webhooks: warehouse-mode HTTPS callbacks, HioBuy-Signature HMAC, event catalog, retries, and portal Send test.

Supplier inquiry

  • Overview — Supplier-confirmed packed weight, package dimensions and carton info for 1688/Taobao: estimate international shipping on sofas, furniture, lighting and other bulky items before purchase.
  • Create inquiry — POST /v1/supplier-inquiries and /messages: product_url, sku, typed questions, Idempotency-Key, one active inquiry per product and ACTIVE_INQUIRY_EXISTS handling.
  • Question types — Ten question types and their answer schemas: packed_weight, package_dimensions, carton_info, stock, lead_time, moq, neutral_packaging, customization, other.
  • Read inquiries — GET /v1/supplier-inquiries list, detail and messages: filters, pagination, message/timeline models, answer payloads, polling versus webhooks.

Integrations

  • Agent API & MCP — AI agent China sourcing: Cursor MCP and hiobuy-agent-api Skill for 1688, Taobao, Weidian shopping-agent search — /ai/v1 Live keys, not sandbox OpenAPI /v1.
  • Commerce AI (Preview) — Commerce AI is in Preview (Invite Only). It covers ecommerce text translation, text/image localization, image text translation, label/Chinese clutter removal, white background rendering, smart HD enhancement, image analysis, and pricing guidance for invited technical evaluation only. No public pricing table is published; credits are test metering only.

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support