servers / mcp-shopline
mcp-shopline
communitystdiolocaldestructive capablehealthy
MCP server wrapping the Shopline Open API into 143 AI-callable tools (75 read + 68 write) for e-commerce operations. Built for Claude Code, Claude Desktop, and any MCP-compatible AI client.
01Tools · 143
How to read this: tool names here are observed from a live tools/list handshake. The Risk label is a heuristic inferred from the tool name (write/destructive verbs), not from executing the tool — a conservative guess, not a verified capability. We never escalate risk from a description. Found one that's wrong? Tell us — we fix on report.
| Tool | Risk | Side effects | Approval |
|---|---|---|---|
| get_top_products 取得指定時間區間的商品銷售排行榜（依銷量或營業額排序），或滯銷商品清單。 | read | false | unknown |
| get_channel_comparison 比較各門市/通路的同期業績：營業額、訂單數、客單價等。支援線上 vs 門市，或門市之間的比較。 | read | false | unknown |
| get_order_labels
【用途】取得指定訂單的配送標籤資訊，可用於列印物流面單或查詢寄件單號。
【呼叫的 Shopline API】
- GET /v1/orders/{order_id}/labels
【回傳結構】
API 原始回應，通常包含：
{
"labels": [
{
"tracking_number": str, # 物流追蹤號碼
"carrier": str, # 物流商名稱
"label_url": str, # 標籤列印 URL
...
}
]
}
| write | true | unknown |
| query_orders 依時間區間、訂單狀態、通路來源查詢訂單列表。回傳精簡的訂單摘要。
【呼叫的 Shopline API】
- GET /v1/orders/search
- GET /v1/orders
| read | false | unknown |
| get_sales_summary 取得指定時間區間的銷售摘要：營業額、訂單數、客單價、件單價、折扣總額等核心指標。支援依通路/門市篩選。 | read | false | unknown |
| get_sales_trend 取得銷售趨勢數據，支援每日/每週/每月粒度，可用於繪製趨勢圖。 | read | false | unknown |
| get_refund_summary 取得指定時間區間的退貨退款統計：退款金額、退貨筆數、退貨率、退貨商品明細。支援計算淨營收。 | destructive | true | true |
| get_order_action_logs
【用途】取得指定訂單的所有操作歷程紀錄，包含狀態變更、人員操作、時間戳記等，適合稽核追蹤。
【呼叫的 Shopline API】
- GET /v1/orders/{order_id}/action-logs
【回傳結構】
{
"order_id": str, # 查詢的訂單 ID
"total": int, # 歷程總筆數
"logs": [ # 操作歷程列表
{
"action": str, # 操作類型（如 status_changed, payment_updated）
"operator": str, # 操作人員
"created_at": str, # 操作時間
... # 其他欄位依 API 回應而定
}
]
}
| write | true | unknown |
| get_order_detail 取得單筆訂單的完整資訊，包含商品明細、付款、物流、折扣等。 | write | true | unknown |
| get_order_tags
【用途】取得指定訂單上附加的所有標籤，可用於分類管理或篩選特殊訂單。
【呼叫的 Shopline API】
- GET /v1/orders/{order_id}/tags
【回傳結構】
{
"order_id": str, # 查詢的訂單 ID
"tags": list, # 標籤列表（字串陣列）
}
| write | true | unknown |
| get_product_variants 取得特定商品的所有 SKU 變體明細，含尺寸×顏色的庫存矩陣。
【呼叫的 Shopline API】
- GET /v1/products/{product_id}
| read | false | unknown |
| get_stock_by_warehouse 取得商品在各倉庫/門市的庫存分佈矩陣。可查詢單一商品或全部商品的各倉庫庫存。 | read | false | unknown |
| get_rfm_analysis 根據訂單資料進行 RFM（Recency/Frequency/Monetary）分群分析。注意：僅能分析有下單紀錄的客戶（Customers API 為 403）。 | read | false | unknown |
| get_category_sales 依商品分類（Category）彙總銷售數據：各分類的營業額、銷量、商品數。需交叉 Categories API + Products + Orders。 | read | false | unknown |
| get_archived_orders
【用途】查詢已封存（archived）的歷史訂單列表，適合調閱長期歸檔的舊訂單資料。
【呼叫的 Shopline API】
- GET /v1/orders/archived
【回傳結構】
{
"total_found": int, # 符合條件的總筆數
"returned": int, # 實際回傳筆數
"orders": [ # 精簡訂單列表
{
"id": str,
"order_number": str,
"status": str,
"channel": str, # "POS" 或 "線上"
"store_name": str,
"total": float,
"subtotal": float,
"discount": float,
"payment_type": str,
"payment_status": str,
"delivery_type": str,
"delivery_status": str,
"customer_name": str,
"items_count": int,
"created_at": str,
}
]
}
| read | false | unknown |
| get_order_transactions
【用途】取得指定訂單的所有付款交易紀錄，包含付款金額、交易狀態、付款方式等，適合對帳與財務核查。
【呼叫的 Shopline API】
- GET /v1/orders/{order_id}/transactions
【回傳結構】
{
"order_id": str, # 查詢的訂單 ID
"total": int, # 交易筆數
"transactions": [ # 交易列表
{
"id": str, # 交易 ID
"kind": str, # 交易類型（sale, refund, void 等）
"status": str, # 交易狀態
"amount": float, # 交易金額（TWD）
"gateway": str, # 付款閘道
"created_at": str, # 交易時間
... # 其他欄位依 API 回應而定
}
]
}
| write | true | unknown |
| get_low_stock_alerts 取得低庫存或缺貨的 SKU 清單，可自訂庫存門檻值。 | read | false | unknown |
| list_purchase_orders
【用途】
取得 POS 採購單列表，用於了解進貨狀況與採購歷史。
【呼叫的 Shopline API】
- GET /v1/pos/purchase_orders
【回傳結構】
- total_found: 查詢到的採購單總數
- returned: 實際回傳筆數
- purchase_orders: 每筆含 id、status、total、created_at
| read | false | unknown |
| get_customer_geo_analysis 根據訂單的收件地址分析客戶地區分佈（縣市層級）。 | read | false | unknown |
| get_product_list 取得商品列表，含 SKU 變體、價格、品牌、庫存數量等資訊。
【呼叫的 Shopline API】
- GET /v1/products
- GET /v1/products/search
| read | false | unknown |
| get_warehouses 取得所有倉庫/門市據點列表。 | read | false | unknown |
| get_inventory_overview 取得全商品庫存總覽：總庫存數量、庫存品項數、缺貨品項數等。從商品 variations 的 quantity 欄位計算。 | read | false | unknown |
| get_locked_inventory
【用途】
取得目前被鎖定（預留）的庫存商品清單，協助分析哪些 SKU 有待出貨的預留數量。
【呼叫的 Shopline API】
- GET /v1/products/locked-inventory
【回傳結構】
- total: 鎖定庫存的 SKU 總筆數
- items: 每筆含 product_title、sku、locked_quantity
| read | false | unknown |
| get_repurchase_analysis 分析客戶回購率與回購週期。計算新客 vs 舊客比例、回購率、平均回購天數。 | read | false | unknown |
| get_promotion_analysis 分析促銷活動效果：各活動的使用次數、折扣類型、狀態分佈。可搭配銷售數據評估促銷 ROI。 | read | false | unknown |
| get_purchase_order_detail
【用途】
取得單一 POS 採購單的完整明細，含採購品項、數量、金額等資訊。
【呼叫的 Shopline API】
- GET /v1/pos/purchase_orders/{purchase_order_id}
【回傳結構】
- id、status、created_at、total
- items: 每筆含 product_title、sku、quantity、unit_cost
| write | true | unknown |
| get_inventory_turnover 計算庫存周轉指標：周轉天數、周轉率。需要商品庫存 + 銷售數據。 | read | false | unknown |
| get_stock_transfer_suggestions 自動產生跨倉庫庫存調撥建議。
【用途】逐商品查詢各倉庫庫存，若同商品在不同倉庫之間的庫存差距過大
（差值 >= min_stock_diff），則建議從庫存多的倉庫調撥到庫存少的倉庫。
僅分析前 30 個商品以避免 API 速率限制。
【呼叫的 Shopline API】
- GET /v1/products（商品列表）
- GET /v1/products/{product_id}/stocks（各倉庫庫存）
- GET /v1/warehouses（倉庫名稱對照）
【回傳結構】dict 含 products_analyzed、suggestions_count、suggestions 列表。
| write | true | unknown |
| get_refund_by_store 依門市/通路分析退貨退款分佈。
【用途】取得指定時間區間內的退貨單，並依關聯訂單的門市/通路分群，
計算各門市的退貨筆數、退款金額、最常被退貨的商品，協助評估各通路退貨狀況。
【呼叫的 Shopline API】
- GET /v1/return_orders（退貨單列表）
- GET /v1/orders/{order_id}（取得關聯訂單的通路資訊）
【回傳結構】dict 含 period、total_return_orders、stores（各門市退貨統計）。
| destructive | true | true |
| get_promotion_roi 交叉比對促銷活動與銷售數據，計算各活動的 ROI。
【用途】取得指定時間區間內活躍的促銷活動，並比對訂單中的 promotion_items，
統計每個活動帶來的訂單數、營業額、折扣金額，計算平均每單折扣與折扣占比。
【呼叫的 Shopline API】
- GET /v1/promotions（促銷活動列表）
- GET /v1/orders/search（訂單查詢）
【回傳結構】dict 含 period、total_promotions、promotions（各活動 ROI 明細）。
| read | false | unknown |
| get_customer_profile 取得單一客戶的完整輪廓（基本資料 + 儲值金紀錄 + 會員點數 + 會員等級變動 + 優惠券）。
【用途】
回答「這位客戶是誰、消費狀況、會員狀態」等完整客戶概況問題。適合客服
場景或個別會員分析。若要批次分析客戶行為請改用 get_rfm_analysis。
【呼叫的 Shopline API】
- GET /v1/customers/{customer_id}
- GET /v1/customers/{customer_id}/store-credit-history
- GET /v1/customers/{customer_id}/member-points
- GET /v1/customers/{customer_id}/membership-tier-history
- GET /v1/customers/{customer_id}/promotions
【回傳結構】
dict 包含 profile / store_credits / member_points / tier_history / promotions 五大區塊。
金額皆為 float (TWD)。
| read | false | unknown |
| list_membership_tiers 取得商店的所有會員等級定義。
【用途】
查看商店設定了哪些會員等級、升等門檻、各等級權益。
用於分析會員結構或確認等級設定。
【呼叫的 Shopline API】
- GET /v1/membership_tiers
【回傳結構】
dict 含 total, tiers[]。
每個 tier 包含 id, name, threshold, benefits 等。
| read | false | unknown |
| get_category_tree 取得所有商品分類並組成樹狀結構。
【用途】
瀏覽商店的完整分類層級，了解分類架構與父子關係。
可用於確認分類 ID、名稱，再搭配 get_category_detail 取得個別分類詳情，
或搭配商品工具按分類篩選商品。
【呼叫的 Shopline API】
- GET /v1/categories
【回傳結構】
dict 含 total, tree[]（樹狀）, flat[]（扁平列表）。
每個節點包含 id, name, parent_id, children[]（僅在 tree 中）。
| read | false | unknown |
| get_customer_lifecycle 比較兩個時間區間的 RFM 分群遷移，分析客戶生命週期變化。
【用途】分別計算兩個時段的客戶 RFM 分群，然後比較客戶在兩期之間的分群遷移，
找出升級（segment 改善）、流失（segment 退步）、新增、消失的客戶，
產出分群遷移矩陣，協助制定客戶經營策略。
【呼叫的 Shopline API】
- GET /v1/orders/search（兩個時段各查詢一次）
【回傳結構】dict 含 period1、period2、segment_migration、upgrade_count、churn_count、new_count、lost_count。
| read | false | unknown |
| get_slow_movers 找出庫存高但銷量低的滯銷商品。
【用途】交叉比對商品庫存與銷售數據，計算每個商品的日均銷量與可售天數（days_of_supply），
標記 days_of_supply 超過門檻或零銷售的商品為滯銷品，協助清倉決策。
【呼叫的 Shopline API】
- GET /v1/products（商品列表含庫存）
- GET /v1/orders/search（銷售數據）
【回傳結構】dict 含 period、period_days、total_products、slow_movers（滯銷商品列表）。
| read | false | unknown |
| list_customers 取得客戶列表，支援依關鍵字搜尋客戶。
【用途】
查詢特定客戶或瀏覽客戶清單。可用姓名、email、電話搜尋。
若要取得單一客戶的完整資訊（含儲值金、點數、等級），請改用 get_customer_profile。
【呼叫的 Shopline API】
- GET /v1/customers（無搜尋條件時）
- GET /v1/customers/search（有搜尋條件時）
【回傳結構】
dict 含 total_found, returned, customers[]。
每個 customer 包含 id, name, email, phone, tags, created_at。
| read | false | unknown |
| list_customer_groups 取得客戶群組列表，支援依名稱搜尋。
【用途】
瀏覽或搜尋已建立的客戶群組（分群）。可用於確認客戶標籤分群策略、
取得群組 ID 後進一步查詢群組成員。
【呼叫的 Shopline API】
- GET /v1/customer-groups（無搜尋條件時）
- GET /v1/customer-groups/search（有搜尋條件時）
【回傳結構】
dict 含 total_found, returned, groups[]。
每個 group 包含 id, name, customers_count, created_at。
| read | false | unknown |
| get_customer_group_members 取得指定客戶群組中的所有客戶 ID 列表。
【用途】
查詢特定群組包含哪些客戶。回傳客戶 ID 列表，可搭配 get_customer_profile 取得個別客戶詳情。
【呼叫的 Shopline API】
- GET /v1/customer-groups/{group_id}/customers
【回傳結構】
dict 含 group_id, total_members, customer_ids[]。
| read | false | unknown |
| list_store_credits 取得所有客戶的儲值金餘額列表。
【用途】
瀏覽客戶儲值金餘額概況，了解儲值金發放與使用狀況。
可用於計算儲值金負債、找出高餘額客戶。
【呼叫的 Shopline API】
- GET /v1/user_credits
【回傳結構】
dict 含 total_found, returned, total_balance, credits[]。
每個 credit 包含 customer_id, balance (TWD float)。
| read | false | unknown |
| list_custom_fields 取得商店定義的客戶自訂欄位清單。
【用途】
查看商店在客戶資料上設定了哪些額外自訂欄位（如生日、偏好、備註等）。
用於了解客戶資料結構或分析資料完整度。
【呼叫的 Shopline API】
- GET /v1/custom_fields
【回傳結構】
dict 含 total, fields[]。
每個 field 包含 id, name, type, options 等。
| read | false | unknown |
| get_customer_tier_history 取得指定客戶的會員等級變動歷程。
【用途】
追蹤客戶會員等級升降紀錄，了解是升等還是降級、原因為何。
搭配 list_membership_tiers 對照等級名稱。
【呼叫的 Shopline API】
- GET /v1/customers/{customer_id}/membership-tier-history
【回傳結構】
dict 含 customer_id, total_changes, history[]。
每筆含 from_tier, to_tier, reason, created_at。
| read | false | unknown |
| list_member_point_rules 取得商店的會員點數規則設定。
【用途】
查看商店設定的點數回饋規則（消費回饋比例、點數到期規則等）。
用於分析會員忠誠度計畫或對照客戶點數異動。
【呼叫的 Shopline API】
- GET /v1/member_point_rules
【回傳結構】
dict 含 total, rules[]。
每條規則含 id, name, type, value, conditions 等。
| read | false | unknown |
| list_promotions 取得促銷活動列表，支援依狀態篩選。
【用途】
瀏覽商店目前所有促銷活動，了解進行中、已排程或已結束的促銷。
可用於分析促銷策略，或取得 promotion_id 後進一步查詢詳情。
【呼叫的 Shopline API】
- GET /v1/promotions
【回傳結構】
dict 含 total_found, returned, items[]。
每筆包含 id, title, status, discount_type, start_at, end_at。
| read | false | unknown |
| get_category_detail 取得單一商品分類的完整詳情。
【用途】
查詢特定分類的名稱、描述、父分類等完整資訊。
適合在已知分類 ID 的情況下取得詳細欄位。
【呼叫的 Shopline API】
- GET /v1/categories/{category_id}
【回傳結構】
dict 包含 id, name, parent_id, description, position, created_at, updated_at。
| read | false | unknown |
| list_flash_price_campaigns 取得快閃價格活動列表。
【用途】
瀏覽商店所有快閃特賣（限時特價）活動，了解活動名稱、狀態與時間範圍。
可取得 campaign_id 後進一步呼叫 get_flash_price_campaign_detail 查詢完整詳情。
【呼叫的 Shopline API】
- GET /v1/flash_price_campaigns
【回傳結構】
dict 含 total_found, returned, items[]。
每筆包含 id, title, status, start_at, end_at, created_at。
| read | false | unknown |
| get_affiliate_campaign_usage 取得聯盟行銷活動的訂單使用統計。
【用途】
分析特定聯盟行銷活動帶來的訂單數與銷售額，評估推廣效果。
回傳訂單使用紀錄，可計算總訂單數、總銷售額、佣金金額等。
【呼叫的 Shopline API】
- GET /v1/affiliate_campaigns/{campaign_id}/order_usage
【回傳結構】
dict 含 campaign_id, total_orders, total_revenue (TWD), items[]。
每筆訂單包含 order_id, order_number, revenue, commission, created_at。
| read | false | unknown |
| get_promotion_detail 取得單一促銷活動的完整詳情。
【用途】
查詢特定促銷活動的折扣規則、適用商品、使用限制等完整資訊。
適合在已知 promotion_id 的情況下取得所有欄位。
【呼叫的 Shopline API】
- GET /v1/promotions/{promotion_id}
【回傳結構】
dict 包含 id, title, status, discount_type, discount_value,
target_type, conditions, start_at, end_at, created_at, updated_at 等完整欄位。
| read | false | unknown |
| list_affiliate_campaigns 取得聯盟行銷活動列表。
【用途】
瀏覽商店所有聯盟行銷（Affiliate）活動，了解活動名稱、狀態與推廣條件。
可取得 campaign_id 後進一步呼叫 get_affiliate_campaign_detail 或
get_affiliate_campaign_usage 查詢詳細資訊與訂單使用統計。
【呼叫的 Shopline API】
- GET /v1/affiliate_campaigns
【回傳結構】
dict 含 total_found, returned, items[]。
每筆包含 id, title, status, commission_type, commission_value, created_at。
| read | false | unknown |
| list_addon_products 取得加購商品列表，支援依關鍵字搜尋。
【用途】
瀏覽或搜尋商店所有加購商品（Addon Products）設定，了解加購商品名稱、
價格與庫存狀況。若提供搜尋關鍵字則呼叫搜尋端點，否則列出所有加購商品。
適合分析加購策略與商品搭配情況。
【呼叫的 Shopline API】
- GET /v1/addon_products（無搜尋條件時）
- GET /v1/addon_products/search（有搜尋條件時）
【回傳結構】
dict 含 total_found, returned, items[]。
每筆包含 id, name, sku, price (TWD), quantity, status, created_at。
| read | false | unknown |
| search_promotions 依關鍵字搜尋促銷活動。
【用途】
快速找到特定名稱的促銷活動，例如搜尋「週年慶」、「黑五」等。
搜尋結果含 id 可進一步呼叫 get_promotion_detail 取得完整資訊。
【呼叫的 Shopline API】
- GET /v1/promotions/search
【回傳結構】
dict 含 total_found, returned, items[]。
每筆包含 id, title, status, discount_type, start_at, end_at。
| read | false | unknown |
| get_affiliate_campaign_detail 取得單一聯盟行銷活動的完整詳情。
【用途】
查詢特定聯盟行銷活動的佣金規則、適用範圍與推廣連結等完整資訊。
適合在已知 campaign_id 的情況下取得所有欄位。
【呼叫的 Shopline API】
- GET /v1/affiliate_campaigns/{campaign_id}
【回傳結構】
dict 包含 id, title, status, commission_type, commission_value,
tracking_code, start_at, end_at, created_at, updated_at 等完整欄位。
| read | false | unknown |
| list_product_subscriptions 取得商品訂閱列表。
【用途】
瀏覽所有商品訂閱紀錄，了解客戶訂閱哪些商品、訂閱狀態與週期設定。
可取得 subscription_id 後進一步呼叫 get_product_subscription_detail 查詢完整詳情。
適合分析訂閱收入與客戶留存率。
【呼叫的 Shopline API】
- GET /v1/product_subscriptions
【回傳結構】
dict 含 total_found, returned, items[]。
每筆包含 id, customer_id, product_id, status, frequency, next_billing_at, created_at。
| read | false | unknown |
| get_flash_price_campaign_detail 取得單一快閃價格活動的完整詳情。
【用途】
查詢特定快閃特賣活動的折扣規則、適用商品與時間設定等完整資訊。
適合在已知 campaign_id 的情況下取得所有欄位。
【呼叫的 Shopline API】
- GET /v1/flash_price_campaigns/{campaign_id}
【回傳結構】
dict 包含 id, title, status, discount_type, discount_value,
products, start_at, end_at, created_at, updated_at 等完整欄位。
| read | false | unknown |
| list_gifts 取得贈品列表，支援依關鍵字搜尋。
【用途】
瀏覽或搜尋商店所有贈品設定，了解贈品名稱、庫存與適用條件。
若提供搜尋關鍵字則呼叫搜尋端點，否則列出所有贈品。
【呼叫的 Shopline API】
- GET /v1/gifts（無搜尋條件時）
- GET /v1/gifts/search（有搜尋條件時）
【回傳結構】
dict 含 total_found, returned, items[]。
每筆包含 id, name, sku, quantity, status, created_at。
| read | false | unknown |
| get_product_subscription_detail 取得單一商品訂閱的完整詳情。
【用途】
查詢特定訂閱紀錄的完整資訊，包含客戶、商品、付款方式、配送設定與
訂閱週期等所有欄位。適合客服場景或個別訂閱狀態確認。
【呼叫的 Shopline API】
- GET /v1/product_subscriptions/{subscription_id}
【回傳結構】
dict 包含 id, customer_id, product_id, variant_id, status, frequency,
frequency_unit, price (TWD), shipping_address, payment_method,
next_billing_at, created_at, updated_at 等完整欄位。
| read | false | unknown |
| list_conversations 取得客服對話列表。
【用途】
瀏覽所有客服對話的摘要清單，了解目前進行中或歷史的客服溝通狀況。
可依此清單篩選需要進一步查閱訊息內容的對話，再用 get_conversation_messages
取得完整聊天記錄。
【呼叫的 Shopline API】
- GET /v1/conversations
【回傳結構】
dict 含 total_found, returned, conversations[]。
每個 conversation 包含 id, platform（通訊平台）, status（對話狀態）,
created_at。
| read | false | unknown |
| list_return_orders 取得退貨單列表，可依建立日期區間篩選。
【用途】
查詢特定時段內的退貨申請清單，了解退貨狀況與數量。提供退貨單的摘要資訊
（含狀態、對應原始訂單、退款金額及退貨品項數）。若需取得單一退貨單的完整
品項明細，請改用 get_return_order_detail。
注意：analytics_tools 中的 get_refund_summary 也使用同一端點，但以彙總分析
為目的；本工具提供的是原始列表檢視，適合逐筆查閱退貨紀錄。
【呼叫的 Shopline API】
- GET /v1/return_orders
【回傳結構】
dict 含 total_found, returned, return_orders[]。
每個 return_order 包含 id, status, order_id, total（TWD float）,
items_count, created_at。
| read | false | unknown |
| get_return_order_detail 取得單一退貨單的完整明細，包含所有退貨品項。
【用途】
查閱特定退貨申請的完整資訊：退貨原因、每件退貨商品（商品名稱、數量、退款
金額）、物流狀態及客戶聯絡資料。適合客服處理個案或審核退貨申請時使用。
【呼叫的 Shopline API】
- GET /v1/return_orders/{return_order_id}
【回傳結構】
dict 包含退貨單基本資訊（id, status, reason, order_id, created_at）、
金額摘要（total, refund_amount，皆為 TWD float）及 line_items[]。
每個 line_item 包含 product_name, variant_title, quantity, price。
| write | true | unknown |
| get_order_delivery 取得單一配送單的完整資訊，包含物流狀態、追蹤編號及收件地址。
【用途】
查詢特定出貨單的配送狀態與物流詳情，適用於追蹤包裹、確認收件資料，
或協助客服處理配送相關問題。配送單 ID 通常來自 get_order_detail 回傳的
出貨資訊（shipments / deliveries 欄位）。
【呼叫的 Shopline API】
- GET /v1/order_deliveries/{delivery_id}
【回傳結構】
dict 包含：
- id：配送單 ID
- status：配送狀態（如 pending, shipped, delivered）
- tracking_number：物流追蹤編號
- tracking_url：物流追蹤連結
- carrier：物流商名稱
- shipping_address：收件地址（含姓名、電話、地址欄位）
- line_items[]：出貨品項（商品名稱、數量）
- created_at, updated_at
| write | true | unknown |
| get_conversation_messages 取得指定對話的完整訊息記錄。
【用途】
查閱特定客服對話的所有聊天訊息，適用於了解客戶問題脈絡、審核客服回應品質，
或追蹤訂單相關諮詢的處理進度。對話 ID 從 list_conversations 取得。
【呼叫的 Shopline API】
- GET /v1/conversations/{conversation_id}/messages
【回傳結構】
dict 含 conversation_id, total_found, returned, messages[]。
每個 message 包含 id, sender_type（發送者類型：customer/staff）,
content（訊息內容）, message_type, created_at。
| read | false | unknown |
| get_merchant_detail 取得指定商家的詳細資訊。
【用途】
查詢單一商家的完整設定資訊，包含聯絡資訊、幣別、語系等。
適合確認特定商家設定或做資料核對。
【呼叫的 Shopline API】
- GET /v1/merchants/{merchant_id}
【回傳結構】
dict 含商家詳細欄位：id, name, handle, currency, locale,
country, email, phone, address, created_at 等。
| read | false | unknown |
| get_delivery_time_slots 取得指定配送方式的可用時段清單。
【用途】
查詢特定配送方式的預約時段設定，例如到府配送的時間選項。
適合確認預約配送時段或分析客戶配送時段偏好。
【呼叫的 Shopline API】
- GET /v1/delivery_options/{delivery_option_id}/time_slots
【回傳結構】
dict 含 delivery_option_id, total, time_slots[]。
每個 time_slot 包含 id, day, start_time, end_time, enabled 等。
| read | false | unknown |
| list_taxes 取得商店設定的稅率清單。
【用途】
查看商店目前設定的稅率規則，例如營業稅、消費稅等。
適合確認稅率設定或在財務分析時核對稅務規則。
【呼叫的 Shopline API】
- GET /v1/taxes
【回傳結構】
dict 含 total, taxes[]。
每個 tax 包含 id, name, rate, included_in_price,
country, region, created_at 等。
| read | false | unknown |
| list_product_reviews 取得商品評價列表。
【用途】
瀏覽所有商品評價的摘要清單，了解顧客對商品的整體評分與回饋。可用於監控
評價品質、找出評分偏低的商品，或追蹤近期新增的評論。若需查看單一評價的
完整內容（含圖片、店家回覆等），請改用 get_product_review_detail。
【呼叫的 Shopline API】
- GET /v1/product_review_comments
【回傳結構】
dict 含 total_found, returned, reviews[]。
每個 review 包含 id, product_id, product_name（多語系翻譯優先取中文）,
rating（評分，通常 1-5）, content（評價內容摘要）, created_at。
| read | false | unknown |
| list_payments 取得商店啟用的付款方式清單。
【用途】
查看商店目前設定的付款方式，例如信用卡、ATM 轉帳、
貨到付款、第三方支付等。適合確認可用付款渠道或做訂單
付款方式分析的參考。
【呼叫的 Shopline API】
- GET /v1/payments
【回傳結構】
dict 含 total, payments[]。
每個 payment 包含 id, name, payment_type, enabled,
position, created_at 等。
| read | false | unknown |
| get_product_review_detail 取得單一商品評價的完整內容，包含圖片與店家回覆。
【用途】
查閱特定評價的詳細資料：完整評論文字、評分、附圖、顧客資訊及店家回覆。
適用於客服處理評價問題、追蹤店家回應進度，或人工審核評價內容。
【呼叫的 Shopline API】
- GET /v1/product_review_comments/{comment_id}
【回傳結構】
dict 包含：
- id：評價 ID
- product_id / product_name：商品資訊
- rating：評分（通常 1–5）
- content：完整評論文字
- images[]：附圖 URL 列表
- reviewer_name：評價者姓名
- status：評價審核狀態（如 published, pending）
- reply：店家回覆內容（若有）
- created_at, updated_at
| read | false | unknown |
| list_merchants 取得所有商家清單。
【用途】
查看此 API token 可存取的商家帳號列表。
適合多商家環境下確認可操作的商家範圍。
【呼叫的 Shopline API】
- GET /v1/merchants
【回傳結構】
dict 含 total, merchants[]。
每個 merchant 包含 id, name, handle, currency, locale, created_at 等。
| read | false | unknown |
| get_delivery_option_detail 取得指定配送方式的詳細資訊。
【用途】
查詢單一配送方式的完整設定，包含費率規則、地區限制、
重量限制等。適合確認特定配送方式的詳細條件。
【呼叫的 Shopline API】
- GET /v1/delivery_options/{delivery_option_id}
【回傳結構】
dict 含配送方式詳細欄位：id, name, delivery_type,
enabled, price, weight_limit, regions, created_at 等。
| read | false | unknown |
| list_delivery_options 取得商店啟用的配送方式清單。
【用途】
查看商店目前設定的所有配送方式，例如宅配、超商取貨、
門市自取等。適合確認可用配送渠道或分析訂單配送偏好。
【呼叫的 Shopline API】
- GET /v1/delivery_options
【回傳結構】
dict 含 total, delivery_options[]。
每個 delivery_option 包含 id, name, delivery_type,
enabled, position, price, created_at 等。
| read | false | unknown |
| get_channel_detail 取得指定銷售渠道的詳細資訊。
【用途】
查詢單一銷售渠道的完整設定，包含渠道類型、狀態、
連結設定等。適合確認特定渠道的詳細配置。
注意：此端點在部分 token 權限下可能回傳 403 或 422。
【呼叫的 Shopline API】
- GET /v1/channels/{channel_id}
【回傳結構】
dict 含渠道詳細欄位：id, name, channel_type, enabled,
created_at, updated_at 等。
| read | false | unknown |
| list_channels 取得商店所有銷售渠道清單。
【用途】
查看商店目前開啟的銷售渠道，例如線上商店、POS、
Facebook、Instagram 等。適合了解多渠道銷售佈局，
或做渠道業績分析前的渠道資料確認。
注意：此端點在部分 token 權限下可能回傳 403 或 422，
渠道資訊亦可從訂單的 channel.created_by_channel_name
欄位取得。
【呼叫的 Shopline API】
- GET /v1/channels
【回傳結構】
dict 含 total, channels[]。
每個 channel 包含 id, name, channel_type, enabled,
created_at 等。
| read | false | unknown |
| get_app_settings 取得商店應用程式設定。
【用途】
查詢商店層級的應用程式設定，包含功能開關、主題設定等。
適合確認商店目前的功能啟用狀態。
注意：此端點已被 Shopline 標記為 deprecated（已棄用），
但仍可使用，涵蓋以求完整性。建議優先使用其他設定端點
取得最新商店資訊。
【呼叫的 Shopline API】
- GET /v1/settings/app
【回傳結構】
dict 含 settings，包含各應用程式層級設定欄位。
實際欄位依商店設定而定。
| read | false | unknown |
| list_agents 取得商店的代理人帳號清單。
【用途】
查看商店目前設定的代理人帳號，代理人通常用於
客服、業務等特定角色的操作授權。適合確認代理人
配置或了解有哪些外部帳號有商店操作權限。
【呼叫的 Shopline API】
- GET /v1/agents
【回傳結構】
dict 含 total, agents[]。
每個 agent 包含 id, name, email, role,
enabled, created_at 等。
| read | false | unknown |
| update_customer_tags [WRITE] 設定客戶標籤（覆蓋現有標籤）。
【用途】
為客戶設定標籤，常用於行銷分群、VIP 標記等。注意：會覆蓋客戶現有的所有標籤。
【呼叫的 Shopline API】
- PUT /v1/customers/{customer_id}/tags
- POST /v1/customers/{customer_id}/tags
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 覆蓋客戶的所有現有標籤為新的標籤列表
- 若要新增標籤而非覆蓋，請先用 get_customer_profile 取得現有標籤再合併
| write | true | unknown |
| execute_order_shipment [WRITE] 執行訂單出貨。
【用途】
將指定訂單標記為已出貨，觸發 Shopline 出貨流程，適用於倉庫確認出貨後的狀態更新。
【呼叫的 Shopline API】
- POST /v1/orders/{order_id}/shipment
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 訂單出貨狀態更新為已出貨
- 可能觸發客戶出貨通知（取決於商店設定）
- 訂單需處於可出貨狀態，否則 API 會回傳錯誤
| write | true | unknown |
| get_staff_permissions 取得指定員工的權限設定。
【用途】
查詢特定員工帳號在商店後台的存取權限範圍，
例如可操作的功能模組及操作層級。適合確認員工
權限配置或排查存取問題。
【呼叫的 Shopline API】
- GET /v1/staffs/{staff_id}/permissions
【回傳結構】
dict 含 staff_id, permissions[]。
每個 permission 包含 resource, actions 等，
描述該員工可操作的資源與動作。
| read | false | unknown |
| get_token_info 取得目前 API Token 的資訊與授權範圍。
【用途】
查詢此 API Token 的詳細資訊，包含所屬商家、
授權的 scope（權限範圍）以及有效期限等。
適合排查 API 存取問題、確認 token 是否擁有
所需的操作權限。
【呼叫的 Shopline API】
- GET /v1/token/info
【回傳結構】
dict 含 token_info，包含 merchant_id, scopes[],
expires_at, created_at 等欄位。
| read | false | unknown |
| delete_customer [WRITE] 刪除客戶。
【用途】
從 Shopline 商店中刪除客戶記錄。通常用於清除測試資料或 GDPR 合規需求。
【呼叫的 Shopline API】
- DELETE /v1/customers/{customer_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 永久刪除客戶記錄，不可復原
- 客戶相關的訂單紀錄可能仍保留（取決於 Shopline 實作）
| destructive | true | true |
| create_customer [WRITE] 建立新客戶。
【用途】
在 Shopline 商店中建立新的客戶記錄。適合客服手動建檔或批次匯入場景。
【呼叫的 Shopline API】
- POST /v1/customers
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, customer: dict。
【副作用】
- 在商店客戶列表中新增一筆客戶
- 如果 email 或 phone 已存在，可能會失敗（Shopline 可能不允許重複）
| write | true | unknown |
| update_customer [WRITE] 更新客戶基本資料。
【用途】
修改客戶姓名、聯絡方式、生日等基本資料。僅傳入要修改的欄位，未傳入的欄位不會被覆蓋。
【呼叫的 Shopline API】
- PUT /v1/customers/{customer_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 修改客戶資料，變更立即生效
- 不可復原（無版本歷史），但可再次呼叫此工具覆蓋
| write | true | unknown |
| update_customer_store_credits [WRITE] 調整客戶儲值金餘額。
【用途】
增加或扣除客戶儲值金，常用於儲值金充值、退款補償、活動贈送等場景。
【呼叫的 Shopline API】
- PUT /v1/customers/{customer_id}/store-credits
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 客戶儲值金餘額立即變動
- 異動紀錄會寫入客戶的儲值金歷史（可透過 get_customer_profile 查看）
- 扣除後如餘額不足，API 可能回傳錯誤
| write | true | unknown |
| bulk_execute_shipment [WRITE] 批次執行多訂單出貨。
【用途】
一次性將多筆訂單標記為已出貨，提升倉庫作業效率，適用於每日批量出貨場景。
【呼叫的 Shopline API】
- POST /v1/orders/shipment/bulk
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, order_ids: list。
【副作用】
- 所有指定訂單的出貨狀態批次更新為已出貨
- 部分訂單若無法出貨，API 可能整批失敗或回傳各別結果（取決於 Shopline 實作）
- 可能觸發多封客戶出貨通知
| write | true | unknown |
| adjust_customer_member_points [WRITE] 調整客戶會員點數。
【用途】
增加或扣除客戶會員點數，常用於手動補點、活動贈點、客訴補償等場景。
【呼叫的 Shopline API】
- PUT /v1/customers/{customer_id}/member-points
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 客戶點數餘額立即變動
- 異動紀錄會寫入客戶的點數歷史（可透過 get_customer_profile 查看）
- 扣除後如點數不足，API 可能回傳錯誤
| unknown | unknown | unknown |
| split_order [WRITE] 拆分訂單為多個子出貨單。
【用途】
將一筆訂單拆分為多個子單，適用於商品分批到貨或不同倉庫分開出貨的場景。
split_config 為字典，內容依 Shopline API 規格定義各子單。
【呼叫的 Shopline API】
- POST /v1/orders/{order_id}/split
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 原訂單被拆分為多個子訂單，原訂單狀態可能變更
- 操作通常不可逆，請確認拆單設定正確後再執行
- 已出貨的訂單無法拆單
| write | true | unknown |
| create_order [WRITE] 建立新訂單。
【用途】
在 Shopline 商店中手動建立新訂單，適用於電話訂購、客服補單、線下訂單轉入等場景。
order_data 需包含 Shopline 建立訂單 API 所需的完整欄位。
【呼叫的 Shopline API】
- POST /v1/orders
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, order: dict。
【副作用】
- 在商店訂單列表中新增一筆訂單
- 可能觸發庫存扣減（取決於訂單內容與商店設定）
- 可能觸發客戶訂單確認通知（取決於商店設定）
- 建立後訂單立即生效，需確認資料正確再執行
| write | true | unknown |
| cancel_order [WRITE] 取消訂單。
【用途】
取消指定訂單，適用於客戶要求取消、庫存不足或付款問題等場景。
【呼叫的 Shopline API】
- POST /v1/orders/{order_id}/cancel
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 訂單狀態變更為已取消，操作不可逆
- 若訂單已出貨，可能無法取消（取決於 Shopline 規則）
- 已付款訂單取消後需另行退款
| destructive | true | true |
| update_order [WRITE] 更新訂單欄位。
【用途】
修改訂單的可編輯欄位（如備註、配送地址等）。僅傳入要修改的欄位，未傳入欄位不受影響。
【呼叫的 Shopline API】
- PATCH /v1/orders/{order_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 訂單資料立即變更，不可復原（可再次呼叫此工具覆蓋）
- 部分欄位（如金額）可能受限於訂單狀態而無法修改
| write | true | unknown |
| update_order_status [WRITE] 更新訂單狀態（支援同時更新多種狀態）。
【用途】
分別或同時更新訂單的主狀態、配送狀態、付款狀態。
僅傳入非 None 的參數，每個非 None 參數會各自呼叫一支 API。
【呼叫的 Shopline API】
- PATCH /v1/orders/{order_id}/status（若 status 非 None）
- PATCH /v1/orders/{order_id}/delivery-status���若 delivery_status 非 None）
- PATCH /v1/orders/{order_id}/payment-status（若 payment_status 非 None）
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, updated_fields: list。
【副作用】
- 訂單狀態立即變更，影響前台顯示與後台報表
- 狀態變更可能觸發客戶通知（取決於商店設定）
- 非法的狀態值或不合法的狀態轉換會導致 API 回傳錯誤
| write | true | unknown |
| update_order_tags [WRITE] 設定訂單標籤（覆蓋現有標籤）。
【用途】
為訂單設定標籤，常用於訂單分類、優先處理標記、客服備註分群等場景。
注意：會覆蓋訂單現有的所有標籤。
【呼叫的 Shopline API】
- PATCH /v1/orders/{order_id}/tags
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 覆蓋訂單的所有現有標籤為新的標籤列表
- 若要新增標籤而非覆蓋，請先用 get_order_detail 取得現有標籤再合併
| write | true | unknown |
| create_product [WRITE] 建立新商品。
【用途】
在 Shopline 商店中建立一筆新的商品記錄。product_data 為完整的商品 body，
應依 Shopline Open API 規格組裝（含名稱、描述、售價、SKU 等）。
【呼叫的 Shopline API】
- POST /v1/products
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, product: dict。
【副作用】
- 商品立即在商店後台可見
- 若 SKU 或 barcode 重複，API 可能回傳錯誤
- 新商品預設狀態取決於 product_data 內的 status 欄位
| write | true | unknown |
| update_product_price [WRITE] 更新商品售價（無變體商品）。
【用途】
直接設定無變體商品的售價。適用於調價、促銷結束恢復原價等場景。
若商品有變體，請改用 update_variation_price。
【呼叫的 Shopline API】
- PUT /v1/products/{product_id}/price
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 售價立即更新，前台同步顯示新價格
- 不影響進行中的訂單（訂單成立時已鎖定價格）
| write | true | unknown |
| update_product [WRITE] 更新商品基本資料。
【用途】
修改現有商品的名稱、描述、分類、狀態等欄位。僅傳入要修改的欄位，
未傳入的欄位不會被覆蓋。
【呼叫的 Shopline API】
- PUT /v1/products/{product_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 商品資料變更立即生效，前台同步更新
- 不可復原（無版本歷史），但可再次呼叫此工具覆蓋
| write | true | unknown |
| delete_product [WRITE] 刪除商品。
【用途】
從 Shopline 商店中永久刪除商品記錄。通常用於清除下架商品或測試資料。
【呼叫的 Shopline API】
- DELETE /v1/products/{product_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 永久刪除商品，不可復原
- 商品相關的訂單行項目記錄可能仍保留（取決於 Shopline 實作）
- 刪除後前台立即下架
| destructive | true | true |
| update_product_variation [WRITE] 更新商品變體資料。
【用途】
修改特定商品變體的 SKU、規格選項、狀態等欄位。僅傳入要修改的欄位，
未傳入的欄位不會被覆蓋。
【呼叫的 Shopline API】
- PUT /v1/products/{product_id}/variations/{variation_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 變體資料變更立即生效，前台同步更新
- 不可復原（無版本歷史），但可再次呼叫此工具覆蓋
| write | true | unknown |
| update_product_tags [WRITE] 設定商品標籤（覆蓋現有標籤）。
【用途】
為商品設定標籤，常用於商品分群、促銷標記、SEO 分類等。
注意：此操作會覆蓋商品現有的所有標籤。
【呼叫的 Shopline API】
- POST /v1/products/{product_id}/tags
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 覆蓋商品的所有現有標籤為新的標籤列表
- 若要新增標籤而非覆蓋，請先用 get_product_list 取得現有標籤再合併後傳入
| write | true | unknown |
| bulk_assign_categories [WRITE] 批次將多個商品指派至指定分類。
【用途】
一次將多個商品加入一或多個分類，適用於新季商品上架分類、重新整理分類結構等場景。
比逐一更新商品分類更有效率。
【呼叫的 Shopline API】
- POST /v1/products/bulk-assign-categories
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, product_count: int, category_count: int。
【副作用】
- 商品與分類的關聯立即生效，前台分類頁面同步更新
- 此操作為新增關聯（非覆蓋），商品原有的分類不會被移除
- 若商品或分類 ID 不存在，API 可能略過或回傳錯誤
| write | true | unknown |
| update_product_quantity [WRITE] 更新商品庫存數量（無變體商品）。
【用途】
直接設定無變體商品的庫存數量。適用於盤點後調整庫存或手動補貨場景。
若商品有變體，請改用 update_variation_quantity。
【呼叫的 Shopline API】
- PUT /v1/products/{product_id}/quantity
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 庫存數量立即更新，影響前台可購買數量
- 若設為 0 且商品設定不允許超賣，前台將顯示缺貨
| write | true | unknown |
| delete_product_variation [WRITE] 刪除商品變體。
【用途】
從商品中永久刪除指定的規格變體。適用於停售特定規格或清理錯誤變體。
【呼叫的 Shopline API】
- DELETE /v1/products/{product_id}/variations/{variation_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 永久刪除變體，不可復原
- 若該變體為商品唯一變體，刪除後商品可能無法購買
- 刪除後前台立即移除該規格選項
| destructive | true | true |
| create_product_variation [WRITE] 為商品新增變體。
【用途】
在現有商品下建立新的規格變體（如顏色、尺寸等）。variation_data 應依
Shopline Open API 規格組裝，含 SKU、價格、庫存等欄位。
【呼叫的 Shopline API】
- POST /v1/products/{product_id}/variations
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, variation: dict。
【副作用】
- 變體立即加入商品，前台可供選擇
- 若 SKU 重複，API 可能回傳錯誤
| write | true | unknown |
| update_variation_price [WRITE] 更新商品變體售價。
【用途】
直接設定特定變體的售價。適用於個別規格調價、限時特價等場景。
【呼叫的 Shopline API】
- PUT /v1/products/{product_id}/variations/{variation_id}/price
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 售價立即更新，前台同步顯示新價格
- 不影響進行中的訂單（訂單成立時已鎖定價格）
| write | true | unknown |
| update_variation_quantity [WRITE] 更新商品變體庫存數量。
【用途】
直接設定特定變體的庫存數量。適用於盤點後調整庫存或手動補貨場景。
若要批次更新多個 SKU 庫存，可改用 bulk_update_quantities。
【呼叫的 Shopline API】
- PUT /v1/products/{product_id}/variations/{variation_id}/quantity
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 庫存數量立即更新，影響前台可購買數量
- 若設為 0 且商品設定不允許超賣，前台將顯示缺貨
| write | true | unknown |
| add_product_images [WRITE] 為商品新增圖片。
【用途】
上傳圖片 URL 至商品相簿，圖片會被加入到現有圖片之後。
適用於新增商品展示圖、情境圖等。
【呼叫的 Shopline API】
- POST /v1/products/{product_id}/images
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, images: list。
【副作用】
- 圖片加入商品相簿，前台立即可見
- 圖片 URL 必須為公開可存取的連結，Shopline 將下載並儲存
- 圖片數量上限取決於 Shopline 商店方案設定
| write | true | unknown |
| delete_product_images [WRITE] 刪除商品圖片。
【用途】
從商品相簿中刪除指定圖片。適用於移除過時圖片或錯誤上傳的圖片。
【呼叫的 Shopline API】
- DELETE /v1/products/{product_id}/images
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 永久刪除指定圖片，不可復原
- 若被刪除的圖片為商品主圖，商品主圖將自動替換為相簿中下一張圖片
| destructive | true | true |
| update_promotion [WRITE] 更新既有促銷活動。
【用途】
修改已建立的促銷活動內容，例如調整折扣金額、有效期限、適用條件等。
【呼叫的 Shopline API】
- PUT /v1/promotions/{promotion_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 修改立即生效，已在結帳流程中的消費者可能受影響
- 不可復原（無版本歷史），但可再次呼叫此工具覆蓋
| write | true | unknown |
| bulk_update_quantities [WRITE] 批次更新多個 SKU 的庫存數量。
【用途】
一次更新多個商品或變體的庫存，適用於盤點後大批調整、進貨入庫等場景。
比逐一呼叫 update_product_quantity / update_variation_quantity 更有效率。
【呼叫的 Shopline API】
- PUT /v1/products/bulk-update-quantities
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, updated_count: int。
【副作用】
- 所有 SKU 的庫存數量立即更新，影響前台可購買數量
- 若某 SKU 不存在，API 可能略過或回傳錯誤（取決於 Shopline 實作）
- 建議先確認 SKU 正確後再執行批次操作
| write | true | unknown |
| delete_promotion [WRITE] 刪除促銷活動。
【用途】
永久刪除指定的促銷活動。通常用於清除過期、測試或錯誤建立的活動。
【呼叫的 Shopline API】
- DELETE /v1/promotions/{promotion_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 永久刪除該促銷活動，不可復原
- 刪除後消費者無法再使用與該活動相關的折扣碼或優惠
- 已套用該促銷的歷史訂單不受影響
| destructive | true | true |
| create_promotion [WRITE] 建立新促銷活動。
【用途】
在 Shopline 商店中建立新的促銷活動，例如折扣碼、買一送一、滿額折扣等。
【呼叫的 Shopline API】
- POST /v1/promotions
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, promotion: dict。
【副作用】
- 在商店促銷列表中新增一筆促銷活動，活動狀態依 promotion_data 設定而定
- 若活動設定為立即啟用，消費者即可使用該促銷
- 促銷規則設定後如需修改，請使用 update_promotion
| write | true | unknown |
| send_coupon [WRITE] 發送優惠券給指定客戶。
【用途】
主動將優惠券發送給特定客戶，常用於行銷活動、客戶回饋、CRM 觸發場景。
【呼叫的 Shopline API】
- POST /v1/coupons/send
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, result: dict。
【副作用】
- 優惠券發送後，目標客戶帳號中將出現對應的優惠券
- 依優惠券設定，可能有數量限制；若庫存不足，API 會回傳錯誤
- 部分類型的優惠券一旦發送，無法收回
| write | true | unknown |
| redeem_coupon [WRITE] 核銷（使用）優惠券。
【用途】
在結帳或特定場景下核銷優惠券，將優惠券標記為已使用狀態。
適合 POS 場景或 API 整合的結帳流程。
【呼叫的 Shopline API】
- POST /v1/coupons/redeem
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, result: dict。
【副作用】
- 優惠券狀態變更為已使用，不可再次使用（一次性優惠券）
- 核銷紀錄會寫入系統，影響促銷統計報告
- 操作通常不可逆，請確認核銷對象與條件正確
| unknown | unknown | unknown |
| delete_flash_price_campaign [WRITE] 刪除快閃價格活動。
【用途】
永久刪除指定的快閃價格活動。用於清除已結束、取消或錯誤建立的活動。
【呼叫的 Shopline API】
- DELETE /v1/flash_price_campaigns/{campaign_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 永久刪除該活動，不可復原
- 若活動正在進行中，刪除後商品立即恢復原價
- 歷史訂單中已套用的特價不受影響
| destructive | true | true |
| claim_coupon [WRITE] 客戶領取優惠券。
【用途】
代表客戶領取（claim）一張優惠券，將優惠券綁定至該客戶帳號。
適合兌換碼場景或 API 整合的會員領券流程。
【呼叫的 Shopline API】
- POST /v1/coupons/claim
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, result: dict。
【副作用】
- 優惠券與指定客戶綁定，消費者帳號中可看到此優惠券
- 若優惠券已達領取上限或已過期，API 會回傳錯誤
- 同一張優惠券通常每位客戶只能領取一次（依設定而異）
| unknown | unknown | unknown |
| create_flash_price_campaign [WRITE] 建立快閃價格活動。
【用途】
建立限時特價活動（Flash Sale），在指定時段內將商品調整為特定價格。
適合節慶特賣、清倉、限時搶購等場景。
【呼叫的 Shopline API】
- POST /v1/flash_price_campaigns
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, campaign: dict。
【副作用】
- 活動建立後，依設定的開始時間自動啟用特價
- 活動期間，符合條件的商品會顯示特價，影響商店前台的價格呈現
- 若活動時段與其他促銷重疊，需確認優先規則
| write | true | unknown |
| update_flash_price_campaign [WRITE] 更新快閃價格活動。
【用途】
修改已建立的快閃價格活動，例如調整特價金額、活動時段或適用商品範圍。
【呼叫的 Shopline API】
- PUT /v1/flash_price_campaigns/{campaign_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 修改立即生效；若活動正在進行中，前台價格即時更新
- 不可復原（無版本歷史），但可再次呼叫此工具覆蓋
| write | true | unknown |
| create_affiliate_campaign [WRITE] 建立聯盟行銷活動。
【用途】
建立聯盟行銷（Affiliate）活動，設定推薦獎勵規則，讓推廣夥伴（聯盟會員）
透過分享連結或代碼帶來訂單並獲得佣金。
【呼叫的 Shopline API】
- POST /v1/affiliate_campaigns
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, campaign: dict。
【副作用】
- 活動建立後，可將活動連結或代碼分發給聯盟夥伴
- 活動啟用後，透過聯盟連結產生的訂單將自動計算佣金
- 請確認佣金規則與結算方式設定正確，避免財務損失
| write | true | unknown |
| update_affiliate_campaign [WRITE] 更新聯盟行銷活動。
【用途】
修改已建立的聯盟行銷活動，例如調整佣金比例、活動期限或適用條件。
【呼叫的 Shopline API】
- PUT /v1/affiliate_campaigns/{campaign_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 修改立即生效；佣金規則調整後，新訂單將套用新規則
- 已產生的佣金紀錄不受影響（依各活動的歷史快照而定）
- 不可復原（無版本歷史），但可再次呼叫此工具覆蓋
| write | true | unknown |
| delete_category [WRITE] 刪除商品分類。
【用途】
從 Shopline 商店中永久刪除指定分類。適合清除已停用或錯誤建立的分類。
【呼叫的 Shopline API】
- DELETE /v1/categories/{category_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 永久刪除分類記錄，不可復原
- 原本屬於此分類的商品將解除分類關聯，商品本身不會被刪除
- 若有子分類，子分類的父分類關聯可能一併受影響（視 Shopline 實作而定）
| destructive | true | true |
| delete_affiliate_campaign [WRITE] 刪除聯盟行銷活動。
【用途】
永久刪除指定的聯盟行銷活動。用於清除已結束、取消或錯誤建立的活動。
【呼叫的 Shopline API】
- DELETE /v1/affiliate_campaigns/{campaign_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 永久刪除該活動，不可復原
- 刪除後聯盟夥伴的推廣連結或代碼將失效，無法再追蹤新訂單
- 已累積的佣金紀錄與歷史訂單資料不受影響（依 Shopline 實作而定）
| destructive | true | true |
| create_category [WRITE] 建立新商品分類。
【用途】
在 Shopline 商店中建立新的商品分類，可指定父分類以建立層級結構。
【呼叫的 Shopline API】
- POST /v1/categories
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, category: dict。
【副作用】
- 在商店分類列表中新增一筆分類記錄
- 若 parent_id 不存在，API 可能回傳錯誤
| write | true | unknown |
| update_return_order [WRITE] 更新退貨單狀態或資料。
【用途】
修改退貨單的審核狀態、退款金額、備註等資料，適用於客服審核退貨申請流程。
【呼叫的 Shopline API】
- PUT /v1/return_orders/{return_order_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 退貨單資料變更立即生效
- 若將狀態更新為「已退款」，可能觸發實際退款動作並影響財務帳務
- 不可復原，請謹慎確認狀態變更
| write | true | unknown |
| update_category [WRITE] 更新商品分類資料。
【用途】
修改分類名稱、排序、父分類等屬性。僅傳入要修改的欄位，未傳入的欄位不會被覆蓋。
【呼叫的 Shopline API】
- PUT /v1/categories/{category_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 分類資料變更立即生效，影響前台分類導覽顯示
- 不可復原，但可再次呼叫此工具覆蓋
| write | true | unknown |
| create_return_order [WRITE] 建立退貨／退款申請單。
【用途】
針對指定訂單建立退貨或退款申請，適用於客服處理退換貨流程。
【呼叫的 Shopline API】
- POST /v1/return_orders
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, return_order: dict。
【副作用】
- 在系統中建立退貨／退款申請記錄，狀態為待審核
- 觸發退貨流程，可能影響庫存預留與財務帳務（視 Shopline 退貨處理設定）
- 若訂單不符退貨條件（如已超過退貨期限），API 可能回傳錯誤
| write | true | unknown |
| send_order_message [WRITE] 發送與特定訂單相關的對話訊息。
【用途】
針對指定訂單發送訊息給買家，適用於出貨通知、客服回覆、訂單異常說明等場景。
【呼叫的 Shopline API】
- POST /v1/conversations/order-messages
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, conversation: dict。
【副作用】
- 在買家的對話收件匣中新增一則訊息，買家可即時收到通知
- 訊息送出後無法撤回或修改
| write | true | unknown |
| send_shop_message [WRITE] 發送一般商店對話訊息。
【用途】
對客戶發送非特定訂單的通用訊息，適用於行銷通知、活動公告、客服主動聯繫等場景。
【呼叫的 Shopline API】
- POST /v1/conversations/shop-messages
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, conversation: dict。
【副作用】
- 在客戶的對話收件匣中新增一則商店訊息，客戶可即時收到通知
- 訊息送出後無法撤回或修改
- 大量發送時請注意 Shopline 的訊息頻率限制，以避免觸發反垃圾機制
| write | true | unknown |
| bulk_update_product_reviews [WRITE] 批次更新多筆商品評論。
【用途】
一次性批次審核或修改多筆評論狀態，適用於管理員批次公開或隱藏評論。
【呼叫的 Shopline API】
- PATCH /v1/product_review_comments
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, result: dict。
【副作用】
- 批次更新多筆評論，變更立即生效
- 若有評論狀態變更，相關商品的平均評分可能同步更新
- 部分評論若 id 不存在，整批可能失敗或僅失敗該筆（視 API 實作而定）
| write | true | unknown |
| create_product_review [WRITE] 建立單筆商品評論。
【用途】
為指定商品建立一筆顧客評論，適用於客服代為補登評論或匯入歷史評論資料。
【呼叫的 Shopline API】
- POST /v1/product_review_comments
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, review: dict。
【副作用】
- 在商品評論列表中新增一筆評論，依商店設定可能立即公開或待審核
- 影響商品的平均評分顯示
| write | true | unknown |
| delete_product_review [WRITE] 刪除單筆商品評論。
【用途】
從 Shopline 商店中永久刪除指定評論，適用於移除違規、惡意或測試用評論。
【呼叫的 Shopline API】
- DELETE /v1/product_review_comments/{comment_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 永久刪除評論記錄，不可復原
- 商品的評論總數與平均評分將同步更新
| destructive | true | true |
| update_gift_quantity_by_sku [WRITE] 依 SKU 更新贈品庫存數量。
【用途】
直接以 SKU 為索引更新贈品庫存數量，適合批次庫存同步場景。
【呼叫的 Shopline API】
- PATCH /v1/gifts/quantity-by-sku
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 指定 SKU 的贈品庫存數量將被覆蓋為新值
- 庫存變動立即生效，影響贈品可用性
| write | true | unknown |
| update_addon_product_quantity_by_sku [WRITE] 依 SKU 更新加購商品庫存數量。
【用途】
直接以 SKU 為索引更新加購商品庫存數量，適合批次庫存同步場景。
【呼叫的 Shopline API】
- PUT /v1/addon_products/sku/quantity
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 指定 SKU 的加購商品庫存數量將被覆蓋為新值
- 庫存變動立即生效
| write | true | unknown |
| create_metafield [WRITE] 建立商家應用元欄位（App Metafield）。
【用途】
為商家建立自定義的元欄位，用於儲存應用程式所需的額外商家設定或資料。
【呼叫的 Shopline API】
- POST /merchants/current/app-metafields
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, metafield: dict。
【副作用】
- 在商家的應用元欄位中新增一筆記錄
- 相同 namespace + key 組合若已存在，可能會失敗或覆蓋（取決於 Shopline 實作）
| write | true | unknown |
| bulk_create_product_reviews [WRITE] 批次建立多筆商品評論。
【用途】
一次性批次建立多筆商品評論，適用於大量匯入歷史評論或促銷活動後的評論補登。
【呼叫的 Shopline API】
- POST /v1/product_review_comments/bulk
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, result: dict。
【副作用】
- 批次在商品評論列表中新增多筆評論
- 依商店設定，評論可能立即公開或待審核
- 影響相關商品的平均評分顯示
- 部分評論若格式錯誤，整批可能失敗或僅失敗該筆（視 API 實作而定）
| write | true | unknown |
| update_product_review [WRITE] 更新單筆商品評論。
【用途】
修改評論內容、審核狀態、評分等資料，適用於客服審核或編輯不當評論。
【呼叫的 Shopline API】
- PATCH /v1/product_review_comments/{comment_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 評論資料變更立即生效
- 若變更評分，商品平均評分將同步更新
- 不可復原，但可再次呼叫此工具覆蓋
| write | true | unknown |
| create_gift [WRITE] 建立新贈品。
【用途】
在 Shopline 商店中建立一個新的贈品記錄，可搭配促銷活動使用。
【呼叫的 Shopline API】
- POST /v1/gifts
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, gift: dict。
【副作用】
- 在商店贈品列表中新增一筆記錄
- 贈品建立後可透過促銷規則設定觸發條件
| write | true | unknown |
| bulk_delete_product_reviews [WRITE] 批次刪除多筆商品評論。
【用途】
一次性永久刪除多筆評論，適用於批次清除測試資料或大量違規評論。
【呼叫的 Shopline API】
- DELETE /v1/product_review_comments
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, deleted_count: int。
【副作用】
- 永久刪除多筆評論記錄，不可復原
- 相關商品的評論總數與平均評分將同步更新
- 部分 id 若不存在，整批可能失敗或僅失敗該筆（視 API 實作而定）
| destructive | true | true |
| update_gift [WRITE] 更新贈品資料。
【用途】
修改指定贈品的名稱、數量、圖片等欄位。僅傳入要修改的欄位。
【呼叫的 Shopline API】
- PATCH /v1/gifts/{gift_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 修改指定贈品的資料，變更立即生效
- 不可復原，但可再次呼叫此工具覆蓋
| write | true | unknown |
| create_addon_product [WRITE] 建立新加購商品。
【用途】
在 Shopline 商店中建立一個新的加購商品（Addon Product），可於結帳時讓顧客選購。
【呼叫的 Shopline API】
- POST /v1/addon_products
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, addon_product: dict。
【副作用】
- 在商店加購商品列表中新增一筆記錄
- 建立後需於促銷或商品設定中啟用才會顯示給顧客
| write | true | unknown |
| update_addon_product [WRITE] 更新加購商品資料。
【用途】
修改指定加購商品的名稱、價格、圖片等欄位。僅傳入要修改的欄位。
【呼叫的 Shopline API】
- PUT /v1/addon_products/{addon_product_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 修改指定加購商品的資料，變更立即生效
- 不可復原，但可再次呼叫此工具覆蓋
| write | true | unknown |
| delete_purchase_orders [WRITE] 批次刪除採購單。
【用途】
一次刪除一或多筆 POS 採購單記錄，適合清除測試資料或作廢錯誤採購單。
【呼叫的 Shopline API】
- DELETE /v1/pos/purchase_orders
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 永久刪除指定的採購單記錄，不可復原
- 若採購單已執行入庫操作，刪除可能受限（取決於 Shopline 實作）
| destructive | true | true |
| update_addon_product_quantity [WRITE] 更新加購商品庫存數量。
【用途】
直接以 ID 更新指定加購商品的庫存數量。
【呼叫的 Shopline API】
- PUT /v1/addon_products/{addon_product_id}/quantity
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 指定加購商品的庫存數量將被覆蓋為新值
- 庫存變動立即生效
| write | true | unknown |
| upload_media [WRITE] 上傳媒體檔案至 Shopline。
【用途】
上傳圖片或其他媒體檔案至 Shopline 媒體庫，上傳後可取得媒體 ID 供商品圖片等用途使用。
注意：Shopline API 可能需要 multipart/form-data，本工具目前以 JSON body 傳送，
若 API 回傳格式錯誤，請改用 multipart 上傳方式。
【呼叫的 Shopline API】
- POST /v1/media
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, media: dict。
【副作用】
- 在 Shopline 媒體庫中新增一筆媒體記錄
- 上傳的檔案將佔用商店的媒體儲存空間
| write | true | unknown |
| create_purchase_order [WRITE] 建立新採購單。
【用途】
在 Shopline POS 系統中建立一筆新的採購單，用於記錄向供應商進貨的資訊。
【呼叫的 Shopline API】
- POST /v1/pos/purchase_orders
【回傳結構】
dict 含 success: bool, resource_id: str, message: str, purchase_order: dict。
【副作用】
- 在 POS 採購單列表中新增一筆記錄
- 採購單建立後可進行後續入庫確認操作
| write | true | unknown |
| update_order_delivery [WRITE] 更新訂單配送資訊。
【用途】
修改指定訂單配送記錄的物流資訊，例如更新追蹤號碼、物流公司、配送狀態等。
適合整合第三方物流系統後回寫配送狀態。
【呼叫的 Shopline API】
- PUT /v1/order_deliveries/{delivery_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 修改訂單配送記錄，變更立即生效
- 狀態變更可能觸發 Shopline 的自動通知（如寄送出貨通知 Email 給顧客）
- 不可復原，但可再次呼叫此工具覆蓋
| write | true | unknown |
| update_pickup_store [WRITE] 更新配送選項的自取門市資訊。
【用途】
修改指定配送選項下的自取門市（Pickup Store）資訊，例如更新門市名稱、地址、電話、營業時間等。
適合門市資訊異動時同步更新 Shopline 的自取門市設定。
【呼叫的 Shopline API】
- PUT /v1/delivery_options/{delivery_option_id}/pickup_store
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 修改指定配送選項下的自取門市資訊，變更立即生效
- 顧客於結帳頁選擇自取時將看到更新後的門市資訊
- 不可復原，但可再次呼叫此工具覆蓋
| write | true | unknown |
| update_merchant [WRITE] 更新商家基本資料。
【用途】
修改指定商家的名稱、聯絡資訊、地址等基本設定。僅傳入要修改的欄位，未傳入的欄位不會被覆蓋。
適合商家資料異動（如搬遷、更名）時同步更新 Shopline 商家設定。
【呼叫的 Shopline API】
- PUT /v1/merchants/{merchant_id}
【回傳結構】
dict 含 success: bool, resource_id: str, message: str。
【副作用】
- 修改商家資料，變更立即生效
- 商家名稱等資訊可能顯示於顧客可見的頁面（如收據、通知 Email）
- 不可復原，但可再次呼叫此工具覆蓋
| write | true | unknown |
02Install & source
uvx --from mcp-shopline mcp-shopline
uvx- repohttps://github.com/asgard-ai-platform/mcp-shopline
- licenseMIT
- adoption19 stars · 6 forks
03Access granted
Process payments · destructiveManage e-commerce · write
The access this server can exercise, inferred from its verified tools — not a declared OAuth scope.
05Provenance & freshness
sourcesGitHub repo search [p4]
last_checked2026-08-23 09:04Z
next_check2026-08-25 09:04Z
cadenceevery 48h
verifiedhandshake:failed metadata:passed handshake:failed metadata:passed handshake:failed metadata:passed handshake:failed metadata:passed handshake:failed metadata:passed
index_statusindex — 9 unique facts >= 5
06Badge
Add the “as seen on MCPExplorer” badge to your README. 
[](https://mcpexplorer.com/servers/mcp-shopline)
Next step
This is one server. A loadout combines the right servers, governance, and proven plays for a whole job — assembled deliberately, not tool-dumped.
Explore loadouts →