Manual procurement API

One Channel, One Seller, One Order

Each purchase order can contain multiple products or SKUs, but all items must belong to the same channel and seller.

If your customer purchases products from different sellers or channels, your application must split them into separate purchase orders before calling the HIOBuy Order API.

HIOBuy does not automatically split purchase orders and does not expose a Batch Order API for this workflow.

Identify the channel and seller

• Use the order-level channel; shortcut paths must agree with any body or line channel. Do not mix channels in lines[] or items[].
• Reuse genuine Product API seller.id for client grouping when available: 1688 derives it from sellerOpenId; Taobao detail derives it from shop_id. A generated seller_1688_* / seller_taobao_* fallback, missing ID, product title or shop name is not reliable seller evidence. Do not compare Taobao shop IDs with render seller IDs; they are different identifier namespaces.
• No new mandatory seller field is added to the standard create request. In self mode the Gateway verifies 1688 ownership from original product details, and Taobao ownership from render_item_list[].seller_id plus complete product/SKU coverage before official creation. Missing or ambiguous evidence is rejected.
• In Warehouse procurement mode, including Manual Order, the warehouse owns seller validation before creating any order, starting procurement, debiting a wallet or returning partial success. Gateway checks raw channel conflicts and propagates the warehouse’s validation errors without performing duplicate marketplace lookups. Warehouse acceptance is required; Gateway does not establish that an external warehouse already implements this check.
• For Manual Order, channel=manual selects the route; all items must also share one source_platform. seller_name is a display declaration only. Warehouse must resolve trusted platform seller ownership for every item. When it cannot, it must reject with SELLER_ID_UNAVAILABLE; a caller-supplied name or ID is not a substitute. Do not enable Manual creation before this contract is accepted.

Errors and recovery

All three errors use HTTP 400, category VALIDATION_ERROR:

Mixed-order message: “A purchase order must contain products from the same channel and seller. Please split the items into separate orders by channel and seller.”

A seller-scope rejection must produce no purchase order, procurement task, wallet debit or partially successful order. Existing idempotency rules remain in force. Each intentionally separate purchase needs its own business reference/key; retry an unchanged purchase with its original key.

Procurement versus consolidated shipping

Purchase orders are domestic purchases from individual sellers. Products from separate purchase orders can later be received as separate warehouse packages and, subject to warehouse/shipping eligibility, consolidated into one international shipment. Consolidation does not merge the original procurement order numbers, domestic freight, payment, cancellation or refund states.

Correct request shape: multiple SKUs from one verified seller

Warehouse must independently establish that both product URLs belong to one stable platform seller. These example URLs are illustrative and do not constitute seller evidence or production acceptance.

{
  "channel": "manual",
  "external_order_id": "MANUAL-SELLER-A-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 41",
      "unit_price": 5000,
      "quantity": 1
    }
  ]
}

Incorrect: actual product owners differ

If items[0].product_url resolves to Seller A and items[1].product_url resolves to Seller B, the warehouse must return MULTIPLE_SELLERS_NOT_ALLOWED, even if the request declares seller_name: "Seller A". When ownership cannot be verified, return SELLER_ID_UNAVAILABLE instead of accepting the request based on the declared name.

{
  "channel": "manual",
  "external_order_id": "INVALID-MIXED-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-B/shirt",
      "product_name": "Shirt",
      "specification": "M",
      "unit_price": 3000,
      "quantity": 1
    }
  ]
}

The warehouse’s seller rejection must be replayed according to the existing business-number/idempotency contract, with no order creation or debit. Previously created orders retain replay, detail, payment and cancellation behavior.

POST /v1/orders/manual

One request creates one order for one platform and one seller; multiple items from that seller are allowed. Only jd, pinduoduo and poizon are open. seller_name is required. Split different platforms or sellers into separate requests and business numbers.

Requires a production API key, order:create scope, warehouse fulfillment and an active warehouse binding. No marketplace OAuth or product API is needed. Sandbox manual procurement is unavailable. The warehouse manual endpoint must be implemented and verified before use.

Request

Authorization: Bearer <PRODUCTION_API_KEY>
Content-Type: application/json
Idempotency-Key: 6c14ce20-cf29-4c25-a9ee-3d36aac94c16

{
  "channel": "manual",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "language": "en",
  "remark": "Please ship together",
  "items": [
    {
      "item_ref": "I001",
      "product_url": "https://example.com/item1",
      "product_name": "Wireless Mouse",
      "specification": "Black",
      "unit_price": 3500,
      "quantity": 2,
      "product_image": null,
      "remark": ""
    }
  ]
}

external_order_id is required and unique within the app’s manual orders. The same business number and procurement data return the existing order, even with a different header key; changing data returns HTTP 409 IDEMPOTENCY_CONFLICT. A new purchase uses a new business number. Idempotency-Key is required for create, pay and cancel. order_sn is generated by HIOBuy; item_ref is optional and generated when omitted. Do not send sellers arrays or item-level platform/seller overrides.

Warehouse amounts

All request and response amounts use integer CNY fen: 3500 means CNY 35.00. Warehouse alone calculates merchandise, domestic shipping, the existing 5% procurement fee and final payment. The example fee does not define its billing base, minimum or rounding. HIOBuy validates and saves the returned fees; it never adds another 5%. Missing amounts or incomplete item mappings cannot be paid.

{
  "channel": "manual",
  "success": true,
  "order_id": "WH10001",
  "order_sn": "HB202610160001",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "status": "wait_payment",
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "total": {
    "merchandise": {
      "amount": 7000,
      "currency": "CNY"
    },
    "shipping": {
      "amount": 800,
      "currency": "CNY"
    },
    "procurement_fee": {
      "amount": 390,
      "currency": "CNY"
    },
    "payment": {
      "amount": 8190,
      "currency": "CNY"
    }
  },
  "order_list": [
    {
      "order_id": "WH10001",
      "shipping": {
        "amount": 800,
        "currency": "CNY"
      },
      "lines": [
        {
          "item_ref": "I001",
          "sub_order_id": "WI10001",
          "title": "Wireless Mouse",
          "spec_title": "Black",
          "quantity": 2,
          "unit_price": {
            "amount": 3500,
            "currency": "CNY"
          },
          "line_total": {
            "amount": 7000,
            "currency": "CNY"
          }
        }
      ]
    }
  ],
  "failed_offers": [],
  "request_id": "req_example"
}

Existing order operations

Creation does not debit a wallet or start procurement. Use the returned order_id and channel=manual with the existing pay, cancel, detail and domestic trace APIs. Do not submit pay_amount or any final amount. Before payment HIOBuy checks the warehouse amount against the stored snapshot; the warehouse executes the existing wallet payment. Procurement starts only after confirmed payment. Cancellation follows existing rules and does not itself confirm a refund.

• POST /v1/orders/pay
• POST /v1/orders/cancel
• POST /v1/orders/detail
• POST /v1/orders/logistics/trace

{
  "channel": "manual",
  "order_id": "WH10001"
}

{
  "channel": "manual",
  "order_id": "WH10001",
  "cancel_reason": "buyer_request"
}

Retries and limits

For a timeout or unknown result, retain the original business number and key and query order detail; do not automatically change keys to pay again. Warehouse detail includes payment_status, seller/platform, line references and frozen fees. Manual orders currently use detail and domestic trace; the marketplace order list and marketplace refund APIs do not support manual orders. Limits: 1–100 items; quantity 1–9999; seller_name 200 characters; product_name and specification 500; remarks 1000; HTTP/HTTPS URLs 2048. Strings and decimal prices are rejected.

400 VALIDATION_ERROR · 403 FULFILLMENT_MODE_NOT_SUPPORTED / WAREHOUSE_AUTH_INVALID · 409 IDEMPOTENCY_CONFLICT / ORDER_AMOUNT_CHANGED / ORDER_OPERATION_UNRESOLVED · 502 WAREHOUSE_INVALID_RESPONSE · 503 WAREHOUSE_UNAVAILABLE

Webhooks

procurement.failed / procurement.out_of_stock

{
  "type": "procurement.failed",
  "data": {
    "channel": "manual",
    "order_id": "WH10001",
    "order_sn": "HB202610160001",
    "external_order_id": "EXT-10001",
    "source_platform": "jd",
    "seller_name": "Seller A",
    "status": "partial_failure",
    "reason_code": "OUT_OF_STOCK",
    "items": [
      {
        "item_ref": "I001",
        "sub_order_id": "WI10001",
        "quantity": 1,
        "reason_code": "OUT_OF_STOCK"
      }
    ]
  }
}