Shopify Plus 中國大陸與香港跨境物流串接教學

Key Takeaways
- 用 Shopify Markets 將中港切成兩個獨立市場與 Shipping Profile
- Carrier Service 的 total_price 必須是以「分」為單位的字串
- HS Code 與原產地寫入 InventoryItem,批次更新用 bulkOperationRunMutation
- 身份證等清關敏感資料須加密傳輸並設保存期限政策
- LLM 可加速 HS Code 初判與地址清洗,但必須保留校驗層
要把 Shopify Plus 的中港跨境物流串起來,核心是四件事:用 Shopify Markets 切分中國大陸與香港兩個市場、以 Carrier Service API 即時回傳跨境運費、用 Fulfillment Service 把訂單推到保稅倉或香港倉、再以 Webhook 回寫運單號與清關狀態。
開始之前:這篇教學解決什麼問題
多數品牌在中港兩地賣貨時,會遇到三種版本的同一個痛點:香港倉發往大陸的訂單卡在清關、大陸保稅倉的庫存無法即時反映在 Shopify 前台、以及結帳頁顯示的運費與實際向物流商支付的費率對不上。這些都不是「換一家貨運商」能解決的問題,而是系統串接層面的設計問題。
本教學假設你已經有 Shopify Plus 方案(需要 Plus 才能用到 Checkout Extensibility 與多市場的進階設定),並且打算同時服務香港本地、中國大陸直郵(9610)或保稅備貨(1210)三種情境。文中的程式碼以 Node.js 20 與 Shopify Admin GraphQL API 2025-01 版本為準。
根據中國海關總署公布的數據,2024 年中國跨境電商進出口規模約為 2.63 萬億元人民幣,較前一年持續成長——這個規模意味著清關流程已經高度標準化,但同時也代表報關資料欄位的要求比一般國際小包嚴格得多。
為什麼中港跨境物流需要「串接」而不是人手上傳?
香港與中國大陸雖然地理相連,但在海關定義上是兩個獨立關稅區。香港是自由港,根據香港海關資料,除了酒類、煙草、碳氫油及甲醇四類應課稅品外,一般進口貨物不徵收關稅;而大陸則對跨境電商零售進口商品採取另一套稅制。
這種「一河之隔、兩套規則」的結構,造成幾個必須靠系統解決的落差:
- 報關欄位不對稱。香港出口端相對寬鬆,大陸進口端卻要求訂單、支付單、運單「三單對碰」,並附上購買人身份證號碼。
- 運費計算邏輯不同。香港市內配送多以件計價,跨境則依材積重、品類、申報價值分段計價。
- 庫存位置多元。品牌通常同時有香港倉、深圳前海或鹽田保稅倉、以及第三方海外倉,Shopify 必須知道每張訂單該從哪裡出。
人手處理在日訂單量低於數十張時勉強可行,但一旦進入推廣檔期,錯誤率與人力成本會同步上升。根據財政部、海關總署、稅務總局聯合公告(2018 年第 49 號及後續調整),跨境電商零售進口的個人年度交易限值與單次交易限值有明確上限,超限訂單必須以一般貿易方式處理——這種判斷如果靠人手,幾乎必然出錯。
Ready to Transform Your Ecommerce Operations?
Branch8 specializes in ecommerce platform implementation and AI-powered automation solutions. Contact us today to discuss your ecommerce automation strategy.
前置條件清單
動手前請先確認下列項目齊備,缺一項都會在中途卡住:
- Shopify Plus 商店,並已啟用 Shopify Markets(Settings → Markets)。
- Custom App 權限:在 Shopify Admin 建立 Custom App,勾選
write_shipping、write_fulfillments、read_orders、write_inventory、write_merchant_managed_fulfillment_orders、write_third_party_fulfillment_orders。 - 一組可公開存取的 HTTPS 端點(Carrier Service 的 callback URL 必須對外可達,且不能用自簽憑證)。開發階段可用 Cloudflare Tunnel 或 ngrok。
- 物流商 API 憑證:順豐(SF Express)開放平台、菜鳥(Cainiao)或 4PX 等,視你的清關模式而定。
- 保稅倉或海外倉的倉儲管理系統(WMS)帳號,並確認對方支援庫存回寫 API。
- 商品資料已補齊 HS Code 與原產地。這是後面所有流程的地基。
建議在正式商店之外先開一個 Development Store 做測試;Carrier Service 的費率回傳在測試店也能完整運作。
第一步:用 Shopify Markets 切分中港兩個市場
Shopify Markets 讓你用單一商店管理多個市場的貨幣、語言、定價與配送規則。中港場景下最乾淨的做法是建立兩個獨立市場。
市場設定建議
香港市場
- 貨幣:HKD
- 語言:繁體中文(主)、英文(次)
- 網域:主網域或
/zh-hk子路徑 - 配送:本地配送 + 自提點
中國大陸市場
- 貨幣:CNY
- 語言:簡體中文
- 網域:建議用子網域(例如
cn.yourbrand.com),方便日後接 ICP 備案或獨立 CDN - 配送:跨境直郵 / 保稅倉發貨
在 Admin GraphQL 建立市場的範例:
1mutation CreateMarket {2 marketCreate(input: {3 name: "Mainland China"4 handle: "cn"5 regions: [{ countryCode: CN }]6 enabled: true7 }) {8 market { id name handle }9 userErrors { field message }10 }11}
預期回傳:
1{2 "data": {3 "marketCreate": {4 "market": { "id": "gid://shopify/Market/12345678", "name": "Mainland China", "handle": "cn" },5 "userErrors": []6 }7 }8}
接著在 Settings → Shipping and delivery 建立兩組獨立的 Shipping Profile,分別綁定香港倉與保稅倉的 Location。切記:不要把兩地倉庫放進同一個 Profile,否則 Shopify 會嘗試合併運費計算,結果就是結帳頁出現莫名其妙的費率。
Ready to Transform Your Ecommerce Operations?
Branch8 specializes in ecommerce platform implementation and AI-powered automation solutions. Contact us today to discuss your ecommerce automation strategy.
第二步:建立 Carrier Service,即時回傳跨境運費
Carrier Service API 讓 Shopify 在顧客結帳時即時呼叫你的伺服器取得運費。這是中港場景最關鍵的一步,因為跨境運費取決於材積、品類與申報價值,無法用靜態費率表涵蓋。
註冊 Carrier Service
1mutation CarrierServiceCreate {2 carrierServiceCreate(input: {3 name: "Branch8 CN-HK Cross-border"4 callbackUrl: "https://logistics.yourbrand.com/shopify/rates"5 supportsServiceDiscovery: true6 active: true7 }) {8 carrierService { id name callbackUrl }9 userErrors { field message }10 }11}
Shopify 送來的請求格式
Shopify 會以 POST 傳送類似這樣的 payload:
1{2 "rate": {3 "origin": {4 "country": "HK", "postal_code": "", "province": "",5 "city": "Kwai Chung", "address1": "Container Port Road"6 },7 "destination": {8 "country": "CN", "postal_code": "518000",9 "province": "GD", "city": "Shenzhen"10 },11 "items": [{12 "name": "Serum 30ml",13 "sku": "SRM-030",14 "quantity": 2,15 "grams": 180,16 "price": 48000,17 "requires_shipping": true,18 "properties": {}19 }],20 "currency": "HKD"21 }22}
回傳費率的實作
1import express from 'express';2const app = express();3app.use(express.json());45const VOLUMETRIC_DIVISOR = 5000; // 空運常見係數,依合約調整6const CN_DUTY_FREE_SINGLE_LIMIT_CNY = 5000;78app.post('/shopify/rates', async (req, res) => {9 const { origin, destination, items, currency } = req.body.rate;1011 // 1. 計算計費重(實重 vs 材積重取大)12 const actualKg = items.reduce((s, i) => s + (i.grams * i.quantity), 0) / 1000;13 const volumetricKg = await estimateVolumetric(items, VOLUMETRIC_DIVISOR);14 const chargeableKg = Math.max(actualKg, volumetricKg);1516 // 2. 判斷清關模式17 const declaredValueCny = await toCny(18 items.reduce((s, i) => s + (i.price * i.quantity), 0) / 100, currency19 );20 const mode = destination.country === 'CN'21 ? (declaredValueCny > CN_DUTY_FREE_SINGLE_LIMIT_CNY ? 'GENERAL_TRADE' : 'BC_9610')22 : 'DOMESTIC_HK';2324 // 3. 向物流商取價(此處以快取費率表示意)25 const quotes = await carrierQuote({ mode, chargeableKg, destination });2627 const rates = quotes.map(q => ({28 service_name: q.label,29 service_code: q.code,30 total_price: String(Math.round(q.amount * 100)), // 以分為單位的字串31 description: q.note,32 currency,33 min_delivery_date: q.etaMin, // "2026-02-10 14:00:00 +0800"34 max_delivery_date: q.etaMax35 }));3637 res.json({ rates });38});3940app.listen(3000);
預期回傳給 Shopify 的 JSON:
1{2 "rates": [3 {4 "service_name": "順豐跨境標準(保稅倉發貨)",5 "service_code": "SF_BONDED_STD",6 "total_price": "3800",7 "description": "預計 2-4 個工作天送達,含代繳跨境綜合稅",8 "currency": "HKD",9 "min_delivery_date": "2026-02-10 14:00:00 +0800",10 "max_delivery_date": "2026-02-12 18:00:00 +0800"11 }12 ]13}
三個會讓你踩坑的細節
total_price必須是以「分」為單位的字串,不是浮點數。傳38.00會讓該費率直接消失,而且 Shopify 不會給錯誤訊息。- 逾時限制很嚴。Shopify 的 Carrier Service callback 有秒級的逾時門檻,超時就靜默略過。所有物流商 API 呼叫都應該走快取或預先同步的費率表,不要在請求鏈路中串接三個外部 API。
- 回傳空陣列等於「無法配送」,結帳頁會直接擋下訂單。務必保留一個 fallback 費率。
第三步:把訂單推到保稅倉或香港倉
下單後,訂單要自動路由到正確的倉庫。Shopify 的 Fulfillment Service 是官方建議的做法:註冊之後,Shopify 會自動為該服務建立一個 Location,指派到該 Location 的 Fulfillment Order 就由你的系統負責。
1mutation FulfillmentServiceCreate {2 fulfillmentServiceCreate(3 name: "Shenzhen Bonded Warehouse"4 callbackUrl: "https://logistics.yourbrand.com/shopify/fulfillment"5 trackingSupport: true6 inventoryManagement: true7 ) {8 fulfillmentService { id serviceName location { id name } }9 userErrors { field message }10 }11}
路由邏輯
建議以「目的地國家 + 商品清關資格 + 可用庫存」三個條件決定出貨倉:
- 目的地為香港/澳門 → 香港倉。
- 目的地為中國大陸、商品在《跨境電子商務零售進口商品清單》內、保稅倉有庫存 → 保稅倉(1210)。
- 目的地為中國大陸、但保稅倉無庫存或商品不在清單內 → 香港倉直郵(9610 或個人物品)。
- 以上皆不符 → 標記人工審核,不自動出貨。
Shopify 的 Fulfillment Constraint Rules 與 Order Routing(Plus 專屬)可以在 Admin 介面設定部分條件;更複雜的判斷建議放在你自己的中介層,再用 fulfillmentOrderMove 把訂單移到正確 Location:
1mutation MoveToBonded($id: ID!, $locationId: ID!) {2 fulfillmentOrderMove(id: $id, newLocationId: $locationId) {3 movedFulfillmentOrder { id status assignedLocation { name } }4 userErrors { field message }5 }6}
Ready to Transform Your Ecommerce Operations?
Branch8 specializes in ecommerce platform implementation and AI-powered automation solutions. Contact us today to discuss your ecommerce automation strategy.
第四步:報關欄位——HS Code 與三單對碰
這是最常被低估、卻最容易卡關的一步。
在 Shopify 填好 HS Code 與原產地
Shopify 的 InventoryItem 物件原生支援 harmonizedSystemCode 與 countryCodeOfOrigin:
1mutation SetCustomsFields($id: ID!) {2 inventoryItemUpdate(id: $id, input: {3 harmonizedSystemCode: "3304.99"4 countryCodeOfOrigin: JP5 provinceCodeOfOrigin: null6 }) {7 inventoryItem { id harmonizedSystemCode countryCodeOfOrigin }8 userErrors { field message }9 }10}
批次更新可用 bulkOperationRunMutation 搭配 JSONL 檔案,避免打爆 API 限流。
收集身份證資訊
中國大陸跨境電商零售進口要求「訂單、支付單、運單」三單資訊向海關推送並比對,其中訂單需包含購買人身份資訊。實作上,建議用 Checkout UI Extension 在中國市場的結帳頁加入一個欄位,寫入 Order Metafield:
1// extensions/customs-id/src/Checkout.jsx2import {3 reactExtension, TextField, useApplyMetafieldsChange, useMetafield4} from '@shopify/ui-extensions-react/checkout';56export default reactExtension('purchase.checkout.delivery-address.render-after', () => <IdField />);78function IdField() {9 const metafield = useMetafield({ namespace: 'customs', key: 'id_number' });10 const applyChange = useApplyMetafieldsChange();1112 return (13 <TextField14 label="身份證號碼(大陸清關必填)"15 value={metafield?.value ?? ''}16 onChange={(value) => applyChange({17 type: 'updateMetafield',18 namespace: 'customs',19 key: 'id_number',20 valueType: 'string',21 value22 })}23 />24 );25}
身份證號碼屬於個人敏感資料。香港《個人資料(私隱)條例》與中國《個人信息保護法》對跨境傳輸都有規範,實務上應只在推送海關時解密使用、不在自家資料庫長期明文保存,並在結帳頁明示用途。這一段建議請本地法律顧問覆核,不要照抄別人的實作。
香港陸路出口的 ROCARS
若貨物經陸路口岸進出香港,香港海關要求託運人透過道路貨物資料系統(ROCARS)預先提交貨物資料並取得貨物申報編號,司機在口岸出示。這一步通常由貨代代辦,但你的系統需要能把商業發票明細(品名、數量、價值、HS Code)以結構化格式交給貨代——CSV 或 API 都可以,重點是欄位要對得上。
第五步:用 Webhook 回寫運單號與狀態
倉庫出貨後,必須把追蹤號回寫到 Shopify,顧客才能收到出貨通知。
1import crypto from 'crypto';23function verifyShopifyHmac(rawBody, hmacHeader, secret) {4 const digest = crypto.createHmac('sha256', secret)5 .update(rawBody, 'utf8')6 .digest('base64');7 return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(hmacHeader));8}
回寫出貨:
1mutation CreateFulfillment($foId: ID!) {2 fulfillmentCreate(fulfillment: {3 lineItemsByFulfillmentOrder: [{ fulfillmentOrderId: $foId }]4 trackingInfo: {5 company: "SF Express"6 number: "SF1234567890123"7 url: "https://www.sf-express.com/"8 }9 notifyCustomer: true10 }) {11 fulfillment { id status trackingInfo { number company } }12 userErrors { field message }13 }14}
建議同時訂閱 fulfillments/update、orders/cancelled、refunds/create 三個 Webhook。退貨在跨境場景特別麻煩:大陸退回香港屬於再次出口,涉及退稅核銷,系統必須能分辨「未清關退回」與「已清關退貨」兩種狀態。
Ready to Transform Your Ecommerce Operations?
Branch8 specializes in ecommerce platform implementation and AI-powered automation solutions. Contact us today to discuss your ecommerce automation strategy.
第六步:用 LLM 處理 HS Code 與地址清洗
跨境串接裡最難自動化的,從來不是 API,而是髒資料。兩個典型場景:
HS Code 初判。上千個 SKU 要分類到六位稅則號,人手查表極慢。可行做法是以 LLM 根據品名、成分、材質產出候選稅則號與信心分數,再由報關行覆核。重點是把它當成「加速第一稿」而非「取代專業判斷」——錯誤歸類會導致罰款與查驗,責任不會因為是 AI 建議而轉移。
收件地址正規化。大陸地址常見省市區層級缺漏、簡繁混用、英文拼音混寫。用 LLM 把自由文字拆成結構化欄位,再與官方行政區劃表比對驗證:
1const prompt = `將以下中文地址拆解為 JSON,欄位:province, city, district, street, detail。2僅輸出 JSON,不確定的欄位填 null。3地址:${rawAddress}`;45const parsed = await llm.json(prompt);6const valid = await matchAgainstAdminDivisionTable(parsed); // 必須有校驗層
我們在一個港資美妝零售集團的 Shopify Plus 專案中,就是用這個模式處理舊系統匯入的歷史訂單地址:LLM 負責拆解,再以行政區劃對照表做硬性校驗,無法匹配的落到人工佇列。機制上的關鍵是「永遠有校驗層」,不要讓模型輸出直接進報關資料。
常見錯誤與排錯
結帳頁沒有出現任何跨境運費
依序檢查:callback URL 是否回 HTTP 200、回應是否為合法 JSON、total_price 是否為字串、currency 是否與該市場貨幣一致、Shipping Zone 是否包含中國大陸。可用 curl 直接模擬 Shopify 的請求:
1curl -X POST https://logistics.yourbrand.com/shopify/rates \2 -H "Content-Type: application/json" \3 -d '{"rate":{"origin":{"country":"HK"},"destination":{"country":"CN","postal_code":"518000"},"items":[{"grams":500,"quantity":1,"price":20000}],"currency":"HKD"}}'
訂單被指派到錯誤的 Location
通常是 Shipping Profile 與 Location 的對應沒設乾淨,或商品在兩個 Location 都有庫存、Shopify 依預設優先序選了近的那個。解法是關閉非目標 Location 的該商品庫存追蹤,或在中介層用 fulfillmentOrderMove 強制改派。
清關被退回,理由是「申報要素不全」
最常見是 HS Code 位數不足、品名過於籠統(例如只寫 "Cosmetics")、或申報價值與支付單金額不一致。折扣碼造成的實付金額差異必須如實反映在申報價值,不能用原價申報。
Webhook 重複觸發造成重複出貨
Shopify 的 Webhook 採 at-least-once 傳遞,必須用 X-Shopify-Webhook-Id 做冪等性去重,並在資料庫設唯一索引。
庫存在 Shopify 與 WMS 之間漂移
避免雙向即時同步,改為單向權威:保稅倉庫存以 WMS 為準,每 N 分鐘用 inventorySetQuantities 覆寫 Shopify,而不是用增量調整。增量在網路重試下必然累積誤差。
Ready to Transform Your Ecommerce Operations?
Branch8 specializes in ecommerce platform implementation and AI-powered automation solutions. Contact us today to discuss your ecommerce automation strategy.
上線前檢查清單
- 兩個市場的貨幣、語言、網域、Shipping Profile 各自獨立且已測試。
- Carrier Service 在逾時與物流商 API 故障時都有 fallback 費率。
- 全部可售 SKU 都有六位以上 HS Code 與原產地。
- 超過單次交易限值的訂單會被攔到人工佇列,而非自動放行。
- 身份證欄位有加密傳輸、有保存期限政策、結帳頁有用途說明。
- 退款與退貨流程在「已清關」與「未清關」兩種狀態下都走過一次。
- Webhook 有 HMAC 驗證與冪等性去重。
- 有一張端到端的監控儀表板:費率呼叫成功率、訂單推倉延遲、清關失敗率。
跨境串接沒有「設定完就不用管」這回事。稅則、商品清單與口岸規則都會更新,把監控與人工覆核流程建起來,比追求 100% 自動化更實際。
Branch8 總部位於香港,在新加坡、台灣、越南、馬來西亞、印尼、菲律賓與澳洲設有交付團隊,為亞太、美國、英國與歐洲品牌建置 Shopify Plus 與跨境物流串接。如果你正在規劃中港雙市場上線,或想檢視現有串接的穩定度,歡迎與我們談談你的架構。
Sources
- Shopify.dev — Shopify Developer Documentation
- Shopify.dev — Admin GraphQL API Reference
- Shopify Help Center — Shopify Markets
- General Administration of Customs of China — 中華人民共和國海關總署
- Hong Kong Customs and Excise Department — Road Cargo System (ROCARS)
- Ministry of Finance of the People's Republic of China — 中華人民共和國財政部
- SF Express — 順豐速運
- Office of the Privacy Commissioner for Personal Data, Hong Kong — PCPD
FAQ
Carrier Service API 需要 Shopify Plus,或在年繳方案上付費啟用第三方即時運費功能。若只用靜態費率表,一般方案也能運作,但無法依材積重與申報價值動態計價,跨境場景下誤差會很大。建議至少在中國大陸市場上線前評估升級 Plus。
About the Author
Matt Li
Co-Founder & CEO, Branch8 & Second Talent
Matt Li is Co-Founder and CEO of Branch8, a Y Combinator-backed (S15) Adobe Solution Partner and e-commerce consultancy headquartered in Hong Kong, and Co-Founder of Second Talent, a global tech hiring platform ranked #1 in Global Hiring on G2. With 12 years of experience in e-commerce strategy, platform implementation, and digital operations, he has led delivery of Adobe Commerce Cloud projects for enterprise clients including Chow Sang Sang, HomePlus (HKBN), Maxim's, Hong Kong International Airport, Hotai/Toyota, and Evisu. Prior to founding Branch8, Matt served as Vice President of Mid-Market Enterprises at HSBC. He serves as Vice Chairman of the Hong Kong E-Commerce Business Association (HKEBA). A self-taught software engineer, Matt graduated from the University of Toronto with a Bachelor of Commerce in Finance and Economics.