# HIOBuy Public API — English documentation index Generated from the site navigation. Canonical HTML base: https://hiobuy.com/en/api-docs - Summary for LLMs: https://hiobuy.com/llms.txt - OpenAPI: https://api.hiobuy.com/openapi.json - Agent / MCP: https://hiobuy.com/en/api-docs/agent-api --- ## Getting started - [Introduction](https://hiobuy.com/en/api-docs): HioBuy Public API v1 docs for Taobao, 1688, and Weidian: product search/detail, multilingual fields, auth, warehousing, sandbox vs production onboarding. - [Authentication](https://hiobuy.com/en/api-docs/authentication): Authenticate REST calls with Bearer credentials, scoped headers including language IDs, sandbox and production gateways, rotating secrets securely. - [Response format](https://hiobuy.com/en/api-docs/response-format): Understand the standardized JSON envelope (ret, msg, data, retcode), pagination, multilingual titles, bilingual error semantics, timestamps, and payloads. - [Languages](https://hiobuy.com/en/api-docs/localization): Which marketplace languages exist, query parameters per channel, multilingual titles, storefront localization rules for shopper experiences. - [Errors](https://hiobuy.com/en/api-docs/errors): Decode retcodes, bilingual error bodies, timeouts, webhook signature failures, validation traps, retries, SLA guidance across platform APIs. - [Rate limits](https://hiobuy.com/en/api-docs/rate-limits): Per-endpoint quotas, crawler vs burst limits, warehousing vs search policies, backoff strategies and monitoring quotas for integrations. - [Sandbox](https://hiobuy.com/en/api-docs/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](https://hiobuy.com/en/api-docs/products): Overview of catalogue APIs tying together keyword/image search, detail payloads, parsers, uploads, advanced utilities, SKU refresh patterns. - [Product detail](https://hiobuy.com/en/api-docs/product-detail): Fetch bilingual detail with normalized SKUs/stock matrices, promotions, translations, sourcing metadata plus refresh cadence considerations. - [Keyword search](https://hiobuy.com/en/api-docs/product-search): POST keyword searches with paging, filters and sorting knobs for Taobao and 1688 discovery inside shopping-agent storefront dashboards. - [Upload image](https://hiobuy.com/en/api-docs/product-upload-image): Securely upload buyer photos to obtain searchable media identifiers power similarity search personalization flows. - [Image search](https://hiobuy.com/en/api-docs/product-image-search): Taobao-compatible image retrieval with scoring facets duplicate guards multilingual relevance inside purchasing automation stacks. - [Parse URL](https://hiobuy.com/en/api-docs/product-parse): Turn share links/Taobao shortened URLs into channel plus source identifiers for crawler ingestion or analytics ingestion. - [Response models](https://hiobuy.com/en/api-docs/product-response-models): Schemas for bilingual titles price ladders promotions variants (incl. prop_id/value_id) warehousing inventory signals returned by catalogue integrations. - [1688 categories](https://hiobuy.com/en/api-docs/product-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](https://hiobuy.com/en/api-docs/product-advanced): Experimental or auxiliary catalogue utilities including official taxonomy helpers seller tooling deep links beyond baseline APIs. ## Procurement orders - [Overview](https://hiobuy.com/en/api-docs/orders): Procurement lifecycle: previews, placements, payouts, cancellations, consolidated response models for storefront orchestration. - [Preview](https://hiobuy.com/en/api-docs/order-preview): Domestic quotations before submit including fees coupons express lines SKU breakdown for cart preview experiences. - [Create order](https://hiobuy.com/en/api-docs/order-create): Create authenticated procurement payloads with idempotency buyer notes warehousing hooks aligned with previews. - [Pay order](https://hiobuy.com/en/api-docs/order-pay): Trigger secure payouts poll capture states reconcile rejects for domestic legs of concierge checkout flows. - [Detail & list](https://hiobuy.com/en/api-docs/order-detail): Polling endpoints for SKU manifests domestic milestones payment timelines plus batch retrieval for dashboards. - [Domestic trace](https://hiobuy.com/en/api-docs/order-logistics-trace): Courier domestic traces exception codes SLA insights before warehouse consolidation outbound international legs. - [Cancel](https://hiobuy.com/en/api-docs/order-cancel): Cancel unpaid or reversible domestic procurements documenting reject flows refunds partial reversals safeguards. - [Response models](https://hiobuy.com/en/api-docs/order-response-models): Structures for previews payments logistics covering nested SKU services coupons warehousing slots concierge assistants. ## Fulfillment (warehouse) - [Warehouse authorization](https://hiobuy.com/en/api-docs/fulfillment-setup): Warehouse vs self fulfillment; under warehouse mode choose HioBuy procurement or self procurement; portal channel authorization before /v1/orders and /v1/fulfillment. - [Overview](https://hiobuy.com/en/api-docs/fulfillment): Cross-border warehousing automations quotations shipment batches airway bills tracking wallet balances payouts APIs hub. - [Inbound notice](https://hiobuy.com/en/api-docs/fulfillment-inbounds): POST /v1/fulfillment/inbounds/create inbound notice MOCK: tracking items VAS sandbox fixtures and protocol error codes. - [Packages](https://hiobuy.com/en/api-docs/fulfillment-packages): GET packages list/detail/tracking + unclaimed list/claim (masked tracking, exact match). - [Package returns](https://hiobuy.com/en/api-docs/fulfillment-returns): POST/GET returns return-to-seller: create, confirm fee, cancel; sandbox ret_* fixtures. - [Locations](https://hiobuy.com/en/api-docs/fulfillment-locations): GET /v1/fulfillment/locations read-only catalog: Chinese receiving address, destinations, hours, receiving status. - [Value-added services](https://hiobuy.com/en/api-docs/fulfillment-value-added-services): GET value-added-services catalog: stable service codes, stages, pricing types and current rates. - [Service requests](https://hiobuy.com/en/api-docs/fulfillment-service-requests): POST/GET service-requests: atomic create, list/detail, confirm quoted fees; photos/QC results. - [Shipping quotes](https://hiobuy.com/en/api-docs/fulfillment-freight-estimate): `POST /v1/fulfillment/shipping/quotes` international line quotes (dim weight, channel codes); legacy alias `…/shipments/freight/estimate`. - [Shipments](https://hiobuy.com/en/api-docs/fulfillment-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](https://hiobuy.com/en/api-docs/fulfillment-tracking): GET /v1/fulfillment/shipments/{id}/tracking carrier scan events — not shipment detail timeline or tracking numbers. - [Wallet balance](https://hiobuy.com/en/api-docs/fulfillment-balance): Wallet payouts recharge thresholds settlement nuances multi-currency notes for warehousing finance dashboards connectors. - [Finance](https://hiobuy.com/en/api-docs/fulfillment-finance): List fulfillment wallet transactions and request/download overseas commercial invoices; amounts use CNY_minor like Balance. - [Support tickets](https://hiobuy.com/en/api-docs/support-tickets): Human support tickets for HioBuy warehouse fulfillment: packages, returns, shipments, VAS, billing, and related API issues. - [Response models](https://hiobuy.com/en/api-docs/fulfillment-response-models): Field reference for quotes, preview/create pricing, shipment list/detail, balance, and international tracking events (CNY_minor). - [Webhooks](https://hiobuy.com/en/api-docs/webhooks): Fulfillment webhooks: warehouse-mode HTTPS callbacks, HioBuy-Signature HMAC, event catalog, retries, and portal Send test. ## Integrations - [Agent API & MCP](https://hiobuy.com/en/api-docs/agent-api): 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.