Merchant API: connect SKUs, purchase forecasts and Shenzhen stock to your system

What you can do today

• Bulk-create or update SKUs keyed by your own seller_sku, with a separate product barcode for each color and size, linked to your Shopee / Coupang / momo listing variants.
• Automatically check import requirements from the 11-digit Taiwan tariff code and flag products that need inspection, permits or cannot be imported.
• Forecast tracking numbers and box contents when you purchase; on arrival in Shenzhen a WO-SK labeling work order is created and the warehouse labels and scans every piece.
• Query per-warehouse stock and the stock ledger, and receive webhooks for arrival, completed receiving, quantity discrepancies and stock changes.

Inbound flow

1. Create SKUs: send barcodes, variants, declared names and tariff codes.
2. Forecast inbound: send tracking numbers and the expected quantity of each SKU.
3. Arrival in Shenzhen: scanning the tracking number creates and prints a WO-SK work order.
4. Label and shelve: the warehouse prints product barcodes, labels each piece and scans it in.
5. Receiving complete: received units go into Shenzhen stock, damaged units are counted separately and discrepancies are sent to your system.

Planned features

Bulk outbound orders, shipment batches grouped automatically under declaration rules, and forward stock, sorting and marketplace shipping labels at the Taoyuan warehouse. They will be announced on this page when released.

How to get access

1. In the member center, add a “company” declarant with its 8-digit Taiwan tax ID.
2. Contact HowBridge support to enable the Merchant API. A key is issued after approval.
3. The key is shown only once. Store it in a server-side environment variable and never ship it in a browser or mobile app.
4. For webhooks, first set up and verify your URL on the member API page, then subscribe to merchant events.

Base URL

Format and language

Requests and responses are JSON. Error messages default to Traditional Chinese; send Accept-Language: en for English. Always branch on the fixed English error.code.

Response envelope

Success returns {"success": true, "data": …, "meta": …}; failure returns {"success": false, "error": {"code", "message", "errors", "context"}}, where errors lists per-field details. The only exception is a missing or invalid key: HTTP 401 with body {"message": "Unauthenticated."}.

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "errors": [
      { "code": "TRACKING_IN_USE", "field": "packages.0.tracking_no", "message": "…" }
    ]
  }
}

Rate limits

60 requests per minute and 5,000 per day per key (300 per minute and 50,000 per day on the high-volume plan). A batch request counts as one. For real-time data, subscribe to webhooks instead of polling.

Idempotency (Idempotency-Key)

Write requests accept an Idempotency-Key header (8–128 characters: letters, digits and _-:.). Retrying with the same key and the same body after a timeout returns the original response with Idempotent-Replayed: true; reusing a key with a different body returns 422. Keys are kept for 24 hours.

Batch responses

Batch endpoints report each item: 200 when all succeed, 207 when some fail and 422 when all fail. Every item has an index, a status (created / updated / failed) and the failure reasons.

Identifier characters

seller_sku may contain letters, digits and ._- (1–64 characters); product barcodes may also contain / and + (3–64 characters). Matching is case-insensitive.

Bulk create or update SKUs

POST/api/v1/merchant/skus/batch

Up to 200 items per request. Each item is processed independently, so one failure does not affect the others.

Request example (POST JSON)

curl -X POST https://howbridge.cn/api/v1/merchant/skus/batch \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-sync-20260917-001" \
  -d '{
  "items": [
    {
      "seller_sku": "TEE-RED-S",
      "barcode": "4710000000011",
      "product_name": "Cotton T-shirt",
      "spec": { "color": "red", "size": "S" },
      "declared_name_en": "Cotton knitted T-shirt",
      "declared_unit_value": 18.5,
      "declared_currency": "CNY",
      "hs_code": "61091000006",
      "weight_g": 160,
      "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566" } ]
    }
  ]
}'

Response 200

{
  "success": true,
  "data": [
    {
      "index": 0,
      "seller_sku": "TEE-RED-S",
      "status": "created",
      "sku": {
        "seller_sku": "TEE-RED-S",
        "barcode": "4710000000011",
        "system_barcode": null,
        "pick_code": "131999",
        "hs_code": "61091000006",
        "regulation": { "status": "ok", "import_codes": [], "reasons": [] },
        "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566", "platform_sku": null } ]
      }
    }
  ],
  "meta": { "summary": { "created": 1, "updated": 0, "failed": 0 } }
}

Import requirement check (regulation.status)

List SKUs

GET/api/v1/merchant/skus

Filter by seller_sku, barcode, regulation_status or updated_since (ISO 8601); paginate with page / per_page (max 100).

Get one SKU

GET/api/v1/merchant/skus/{seller_sku}

Update marketplace links

PUT/api/v1/merchant/skus/{seller_sku}/channels

Replaces all existing links with the list you send. The same marketplace variant cannot be linked to two SKUs.

Download barcode labels

GET/api/v1/merchant/skus/{seller_sku}/label.pdf?qty=10

Returns a 40×30 mm label PDF; qty is the number of labels (1–1000). The Shenzhen warehouse prints the same label when labeling; use this if you want to label goods yourself before shipping.

Create an inbound order

POST/api/v1/merchant/inbound-orders

Validated as a whole: nothing is created if any error occurs. A tracking number can belong to only one open inbound order; duplicate SKUs within a package are merged.

Request example (POST JSON)

curl -X POST https://howbridge.cn/api/v1/merchant/inbound-orders \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: po-20260917-0001" \
  -d '{
  "reference_no": "PO-20260917-0001",
  "supplier_order_no": "1688-3312456789",
  "packages": [
    {
      "tracking_no": "YT1234567890123",
      "carrier": "yto",
      "items": [
        { "seller_sku": "TEE-RED-S", "qty": 40 },
        { "seller_sku": "TEE-RED-M", "qty": 60 }
      ]
    }
  ]
}'

Inbound order status

Parcel status

List inbound orders

GET/api/v1/merchant/inbound-orders

GET/api/v1/merchant/inbound-orders/{id}

Filter by status, reference_no or updated_since. Each parcel returns expected, received and damaged quantities and the difference.

Cancel an inbound order

POST/api/v1/merchant/inbound-orders/{id}/cancel

Allowed only while no parcel has arrived; the tracking numbers can then be forecast again.

Get inventory

GET/api/v1/merchant/inventory?warehouse_code=SZ

Filter by warehouse_code and seller_sku[] (up to 200).

Response 200

{
  "success": true,
  "data": [
    { "seller_sku": "TEE-RED-S", "barcode": "4710000000011", "warehouse_code": "SZ",
      "on_hand": 38, "reserved": 0, "available": 38, "damaged": 2, "updated_at": "2026-09-17T15:20:11+08:00" }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 100, "last_page": 1 }
}

Stock ledger

GET/api/v1/merchant/inventory/movements?after_id=0&limit=200

Append-only movement records. Page forward with the after_id cursor (up to 500 per request) and keep meta.next_after_id to continue reconciliation.

Setup

1. Set your webhook URL (https only) on the member API page and complete ownership verification: your endpoint must respond HTTP 200 with body {"challenge": "the value you received"}.
2. Call PUT /api/v1/merchant/webhook/events to subscribe to merchant events. Changing the URL later in the member center keeps your merchant event subscriptions.

curl -X PUT https://howbridge.cn/api/v1/merchant/webhook/events \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": ["inbound.arrived", "inbound.received", "inbound.discrepancy", "inventory.changed"]}'

Events

inbound.received

{
  "event": "inbound.received",
  "delivery_id": "5b0f1c2e-8f3a-4d7e-9c21-0a6b2d4e8f10",
  "created_at": "2026-09-17T15:20:11+08:00",
  "data": {
    "inbound_order_id": 128,
    "reference_no": "PO-20260917-0001",
    "order_status": "completed_with_discrepancy",
    "tracking_no": "YT1234567890123",
    "work_order": "WO-SK-315",
    "warehouse_code": "SZ",
    "items": [
      { "seller_sku": "TEE-RED-S", "expected_qty": 40, "received_qty": 38, "damaged_qty": 2, "difference": 0 },
      { "seller_sku": "TEE-RED-M", "expected_qty": 60, "received_qty": 59, "damaged_qty": 0, "difference": -1 }
    ],
    "received_at": "2026-09-17T15:20:10+08:00"
  }
}

Verifying signatures

Every delivery includes X-Lucky-Event, X-Lucky-Delivery-Id and X-Lucky-Signature: t=timestamp,v1=signature. Compute HMAC-SHA256 with your webhook secret over “timestamp + . + raw body”, compare it with v1, and reject timestamps older than 5 minutes. Retries of the same event keep the same delivery_id, which you can use for de-duplication.

Non-2xx responses are retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. After 20 consecutive failures the webhook is disabled and must be set up again in the member center.

// PHP
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_LUCKY_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $sig);   // ['t' => '1789…', 'v1' => 'ab12…']

$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('LUCKY_WEBHOOK_SECRET'));

if (! hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);   // de-duplicate by $event['delivery_id']
http_response_code(200);

WeCom official account

Technical email howyunqisoftware@gmail.com

Version v1 Phase 1 (2026-09-17): product SKUs, inbound forecasts, Shenzhen labeling and shelving, inventory, webhooks.