依時間區間、訂單狀態、通路來源查詢訂單列表。回傳精簡的訂單摘要。

【呼叫的 Shopline API】

• GET /v1/orders/search

• GET /v1/orders

取得指定時間區間的銷售摘要：營業額、訂單數、客單價、件單價、折扣總額等核心指標。支援依通路/門市篩選。

取得指定時間區間的商品銷售排行榜（依銷量或營業額排序），或滯銷商品清單。

取得銷售趨勢數據，支援每日/每週/每月粒度，可用於繪製趨勢圖。

比較各門市/通路的同期業績：營業額、訂單數、客單價等。支援線上 vs 門市，或門市之間的比較。

取得單筆訂單的完整資訊，包含商品明細、付款、物流、折扣等。

取得指定時間區間的退貨退款統計：退款金額、退貨筆數、退貨率、退貨商品明細。支援計算淨營收。

【用途】查詢已封存（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, } ] }

【用途】取得指定訂單的配送標籤資訊，可用於列印物流面單或查詢寄件單號。

【呼叫的 Shopline API】

• GET /v1/orders/{order_id}/labels

【回傳結構】 API 原始回應，通常包含： { "labels": [ { "tracking_number": str, # 物流追蹤號碼 "carrier": str, # 物流商名稱 "label_url": str, # 標籤列印 URL ... } ] }

【用途】取得指定訂單上附加的所有標籤，可用於分類管理或篩選特殊訂單。

【呼叫的 Shopline API】

• GET /v1/orders/{order_id}/tags

【回傳結構】 { "order_id": str, # 查詢的訂單 ID "tags": list, # 標籤列表（字串陣列） }

【用途】取得指定訂單的所有操作歷程紀錄，包含狀態變更、人員操作、時間戳記等，適合稽核追蹤。

【呼叫的 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 回應而定 } ] }

【用途】取得指定訂單的所有付款交易紀錄，包含付款金額、交易狀態、付款方式等，適合對帳與財務核查。

【呼叫的 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 回應而定 } ] }

取得商品列表，含 SKU 變體、價格、品牌、庫存數量等資訊。

【呼叫的 Shopline API】

• GET /v1/products

• GET /v1/products/search

取得特定商品的所有 SKU 變體明細，含尺寸×顏色的庫存矩陣。

【呼叫的 Shopline API】

• GET /v1/products/{product_id}

取得全商品庫存總覽：總庫存數量、庫存品項數、缺貨品項數等。從商品 variations 的 quantity 欄位計算。

取得低庫存或缺貨的 SKU 清單，可自訂庫存門檻值。

取得所有倉庫/門市據點列表。

取得商品在各倉庫/門市的庫存分佈矩陣。可查詢單一商品或全部商品的各倉庫庫存。

【用途】 取得目前被鎖定（預留）的庫存商品清單，協助分析哪些 SKU 有待出貨的預留數量。

【呼叫的 Shopline API】

• GET /v1/products/locked-inventory

【回傳結構】

• total: 鎖定庫存的 SKU 總筆數

• items: 每筆含 product_title、sku、locked_quantity

【用途】 取得 POS 採購單列表，用於了解進貨狀況與採購歷史。

【呼叫的 Shopline API】

• GET /v1/pos/purchase_orders

【回傳結構】

• total_found: 查詢到的採購單總數

• returned: 實際回傳筆數

• purchase_orders: 每筆含 id、status、total、created_at

【用途】 取得單一 POS 採購單的完整明細，含採購品項、數量、金額等資訊。

【呼叫的 Shopline API】

• GET /v1/pos/purchase_orders/{purchase_order_id}

【回傳結構】

• id、status、created_at、total

• items: 每筆含 product_title、sku、quantity、unit_cost

根據訂單資料進行 RFM（Recency/Frequency/Monetary）分群分析。注意：僅能分析有下單紀錄的客戶（Customers API 為 403）。

分析客戶回購率與回購週期。計算新客 vs 舊客比例、回購率、平均回購天數。

根據訂單的收件地址分析客戶地區分佈（縣市層級）。

計算庫存周轉指標：周轉天數、周轉率。需要商品庫存 + 銷售數據。

依商品分類（Category）彙總銷售數據：各分類的營業額、銷量、商品數。需交叉 Categories API + Products + Orders。

分析促銷活動效果：各活動的使用次數、折扣類型、狀態分佈。可搭配銷售數據評估促銷 ROI。

依門市/通路分析退貨退款分佈。

【用途】取得指定時間區間內的退貨單，並依關聯訂單的門市/通路分群， 計算各門市的退貨筆數、退款金額、最常被退貨的商品，協助評估各通路退貨狀況。 【呼叫的 Shopline API】

• GET /v1/return_orders（退貨單列表）

• GET /v1/orders/{order_id}（取得關聯訂單的通路資訊） 【回傳結構】dict 含 period、total_return_orders、stores（各門市退貨統計）。

自動產生跨倉庫庫存調撥建議。

【用途】逐商品查詢各倉庫庫存，若同商品在不同倉庫之間的庫存差距過大 （差值 >= 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 列表。

交叉比對促銷活動與銷售數據，計算各活動的 ROI。

【用途】取得指定時間區間內活躍的促銷活動，並比對訂單中的 promotion_items， 統計每個活動帶來的訂單數、營業額、折扣金額，計算平均每單折扣與折扣占比。 【呼叫的 Shopline API】

• GET /v1/promotions（促銷活動列表）

• GET /v1/orders/search（訂單查詢） 【回傳結構】dict 含 period、total_promotions、promotions（各活動 ROI 明細）。

比較兩個時間區間的 RFM 分群遷移，分析客戶生命週期變化。

【用途】分別計算兩個時段的客戶 RFM 分群，然後比較客戶在兩期之間的分群遷移， 找出升級（segment 改善）、流失（segment 退步）、新增、消失的客戶， 產出分群遷移矩陣，協助制定客戶經營策略。 【呼叫的 Shopline API】

• GET /v1/orders/search（兩個時段各查詢一次） 【回傳結構】dict 含 period1、period2、segment_migration、upgrade_count、churn_count、new_count、lost_count。

找出庫存高但銷量低的滯銷商品。

【用途】交叉比對商品庫存與銷售數據，計算每個商品的日均銷量與可售天數（days_of_supply）， 標記 days_of_supply 超過門檻或零銷售的商品為滯銷品，協助清倉決策。 【呼叫的 Shopline API】

• GET /v1/products（商品列表含庫存）

• GET /v1/orders/search（銷售數據） 【回傳結構】dict 含 period、period_days、total_products、slow_movers（滯銷商品列表）。

取得客戶列表，支援依關鍵字搜尋客戶。

【用途】 查詢特定客戶或瀏覽客戶清單。可用姓名、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。

取得單一客戶的完整輪廓（基本資料 + 儲值金紀錄 + 會員點數 + 會員等級變動 + 優惠券）。

【用途】 回答「這位客戶是誰、消費狀況、會員狀態」等完整客戶概況問題。適合客服 場景或個別會員分析。若要批次分析客戶行為請改用 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)。

取得客戶群組列表，支援依名稱搜尋。

【用途】 瀏覽或搜尋已建立的客戶群組（分群）。可用於確認客戶標籤分群策略、 取得群組 ID 後進一步查詢群組成員。

【呼叫的 Shopline API】

• GET /v1/customer-groups（無搜尋條件時）

• GET /v1/customer-groups/search（有搜尋條件時）

【回傳結構】 dict 含 total_found, returned, groups[]。 每個 group 包含 id, name, customers_count, created_at。

取得指定客戶群組中的所有客戶 ID 列表。

【用途】 查詢特定群組包含哪些客戶。回傳客戶 ID 列表，可搭配 get_customer_profile 取得個別客戶詳情。

【呼叫的 Shopline API】

• GET /v1/customer-groups/{group_id}/customers

【回傳結構】 dict 含 group_id, total_members, customer_ids[]。

取得所有客戶的儲值金餘額列表。

【用途】 瀏覽客戶儲值金餘額概況，了解儲值金發放與使用狀況。 可用於計算儲值金負債、找出高餘額客戶。

【呼叫的 Shopline API】

• GET /v1/user_credits

【回傳結構】 dict 含 total_found, returned, total_balance, credits[]。 每個 credit 包含 customer_id, balance (TWD float)。

取得商店的所有會員等級定義。

【用途】 查看商店設定了哪些會員等級、升等門檻、各等級權益。 用於分析會員結構或確認等級設定。

【呼叫的 Shopline API】

• GET /v1/membership_tiers

【回傳結構】 dict 含 total, tiers[]。 每個 tier 包含 id, name, threshold, benefits 等。

取得指定客戶的會員等級變動歷程。

【用途】 追蹤客戶會員等級升降紀錄，了解是升等還是降級、原因為何。 搭配 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。

取得商店的會員點數規則設定。

【用途】 查看商店設定的點數回饋規則（消費回饋比例、點數到期規則等）。 用於分析會員忠誠度計畫或對照客戶點數異動。

【呼叫的 Shopline API】

• GET /v1/member_point_rules

【回傳結構】 dict 含 total, rules[]。 每條規則含 id, name, type, value, conditions 等。

取得商店定義的客戶自訂欄位清單。

【用途】 查看商店在客戶資料上設定了哪些額外自訂欄位（如生日、偏好、備註等）。 用於了解客戶資料結構或分析資料完整度。

【呼叫的 Shopline API】

• GET /v1/custom_fields

【回傳結構】 dict 含 total, fields[]。 每個 field 包含 id, name, type, options 等。

取得所有商品分類並組成樹狀結構。

【用途】 瀏覽商店的完整分類層級，了解分類架構與父子關係。 可用於確認分類 ID、名稱，再搭配 get_category_detail 取得個別分類詳情， 或搭配商品工具按分類篩選商品。

【呼叫的 Shopline API】

• GET /v1/categories

【回傳結構】 dict 含 total, tree[]（樹狀）, flat[]（扁平列表）。 每個節點包含 id, name, parent_id, children[]（僅在 tree 中）。

取得單一商品分類的完整詳情。

【用途】 查詢特定分類的名稱、描述、父分類等完整資訊。 適合在已知分類 ID 的情況下取得詳細欄位。

【呼叫的 Shopline API】

• GET /v1/categories/{category_id}

【回傳結構】 dict 包含 id, name, parent_id, description, position, created_at, updated_at。

取得促銷活動列表，支援依狀態篩選。

【用途】 瀏覽商店目前所有促銷活動，了解進行中、已排程或已結束的促銷。 可用於分析促銷策略，或取得 promotion_id 後進一步查詢詳情。

【呼叫的 Shopline API】

• GET /v1/promotions

【回傳結構】 dict 含 total_found, returned, items[]。 每筆包含 id, title, status, discount_type, start_at, end_at。

取得單一促銷活動的完整詳情。

【用途】 查詢特定促銷活動的折扣規則、適用商品、使用限制等完整資訊。 適合在已知 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 等完整欄位。

依關鍵字搜尋促銷活動。

【用途】 快速找到特定名稱的促銷活動，例如搜尋「週年慶」、「黑五」等。 搜尋結果含 id 可進一步呼叫 get_promotion_detail 取得完整資訊。

【呼叫的 Shopline API】

• GET /v1/promotions/search

【回傳結構】 dict 含 total_found, returned, items[]。 每筆包含 id, title, status, discount_type, start_at, end_at。

取得快閃價格活動列表。

【用途】 瀏覽商店所有快閃特賣（限時特價）活動，了解活動名稱、狀態與時間範圍。 可取得 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。

取得單一快閃價格活動的完整詳情。

【用途】 查詢特定快閃特賣活動的折扣規則、適用商品與時間設定等完整資訊。 適合在已知 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 等完整欄位。

取得聯盟行銷活動列表。

【用途】 瀏覽商店所有聯盟行銷（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。

取得單一聯盟行銷活動的完整詳情。

【用途】 查詢特定聯盟行銷活動的佣金規則、適用範圍與推廣連結等完整資訊。 適合在已知 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 等完整欄位。

取得聯盟行銷活動的訂單使用統計。

【用途】 分析特定聯盟行銷活動帶來的訂單數與銷售額，評估推廣效果。 回傳訂單使用紀錄，可計算總訂單數、總銷售額、佣金金額等。

【呼叫的 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。

取得贈品列表，支援依關鍵字搜尋。

【用途】 瀏覽或搜尋商店所有贈品設定，了解贈品名稱、庫存與適用條件。 若提供搜尋關鍵字則呼叫搜尋端點，否則列出所有贈品。

【呼叫的 Shopline API】

• GET /v1/gifts（無搜尋條件時）

• GET /v1/gifts/search（有搜尋條件時）

【回傳結構】 dict 含 total_found, returned, items[]。 每筆包含 id, name, sku, quantity, status, created_at。

取得加購商品列表，支援依關鍵字搜尋。

【用途】 瀏覽或搜尋商店所有加購商品（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。

取得商品訂閱列表。

【用途】 瀏覽所有商品訂閱紀錄，了解客戶訂閱哪些商品、訂閱狀態與週期設定。 可取得 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。

取得單一商品訂閱的完整詳情。

【用途】 查詢特定訂閱紀錄的完整資訊，包含客戶、商品、付款方式、配送設定與 訂閱週期等所有欄位。適合客服場景或個別訂閱狀態確認。

【呼叫的 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 等完整欄位。

取得退貨單列表，可依建立日期區間篩選。

【用途】 查詢特定時段內的退貨申請清單，了解退貨狀況與數量。提供退貨單的摘要資訊 （含狀態、對應原始訂單、退款金額及退貨品項數）。若需取得單一退貨單的完整 品項明細，請改用 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。

取得單一退貨單的完整明細，包含所有退貨品項。

【用途】 查閱特定退貨申請的完整資訊：退貨原因、每件退貨商品（商品名稱、數量、退款 金額）、物流狀態及客戶聯絡資料。適合客服處理個案或審核退貨申請時使用。

【呼叫的 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。

取得單一配送單的完整資訊，包含物流狀態、追蹤編號及收件地址。

【用途】 查詢特定出貨單的配送狀態與物流詳情，適用於追蹤包裹、確認收件資料， 或協助客服處理配送相關問題。配送單 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

取得客服對話列表。

【用途】 瀏覽所有客服對話的摘要清單，了解目前進行中或歷史的客服溝通狀況。 可依此清單篩選需要進一步查閱訊息內容的對話，再用 get_conversation_messages 取得完整聊天記錄。

【呼叫的 Shopline API】

• GET /v1/conversations

【回傳結構】 dict 含 total_found, returned, conversations[]。 每個 conversation 包含 id, platform（通訊平台）, status（對話狀態）, created_at。

取得指定對話的完整訊息記錄。

【用途】 查閱特定客服對話的所有聊天訊息，適用於了解客戶問題脈絡、審核客服回應品質， 或追蹤訂單相關諮詢的處理進度。對話 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。

取得商品評價列表。

【用途】 瀏覽所有商品評價的摘要清單，了解顧客對商品的整體評分與回饋。可用於監控 評價品質、找出評分偏低的商品，或追蹤近期新增的評論。若需查看單一評價的 完整內容（含圖片、店家回覆等），請改用 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。

取得單一商品評價的完整內容，包含圖片與店家回覆。

【用途】 查閱特定評價的詳細資料：完整評論文字、評分、附圖、顧客資訊及店家回覆。 適用於客服處理評價問題、追蹤店家回應進度，或人工審核評價內容。

【呼叫的 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

取得所有商家清單。

【用途】 查看此 API token 可存取的商家帳號列表。 適合多商家環境下確認可操作的商家範圍。

【呼叫的 Shopline API】

• GET /v1/merchants

【回傳結構】 dict 含 total, merchants[]。 每個 merchant 包含 id, name, handle, currency, locale, created_at 等。

取得指定商家的詳細資訊。

【用途】 查詢單一商家的完整設定資訊，包含聯絡資訊、幣別、語系等。 適合確認特定商家設定或做資料核對。

【呼叫的 Shopline API】

• GET /v1/merchants/{merchant_id}

【回傳結構】 dict 含商家詳細欄位：id, name, handle, currency, locale, country, email, phone, address, created_at 等。

取得商店啟用的付款方式清單。

【用途】 查看商店目前設定的付款方式，例如信用卡、ATM 轉帳、 貨到付款、第三方支付等。適合確認可用付款渠道或做訂單 付款方式分析的參考。

【呼叫的 Shopline API】

• GET /v1/payments

【回傳結構】 dict 含 total, payments[]。 每個 payment 包含 id, name, payment_type, enabled, position, created_at 等。

取得商店啟用的配送方式清單。

【用途】 查看商店目前設定的所有配送方式，例如宅配、超商取貨、 門市自取等。適合確認可用配送渠道或分析訂單配送偏好。

【呼叫的 Shopline API】

• GET /v1/delivery_options

【回傳結構】 dict 含 total, delivery_options[]。 每個 delivery_option 包含 id, name, delivery_type, enabled, position, price, created_at 等。

取得指定配送方式的詳細資訊。

【用途】 查詢單一配送方式的完整設定，包含費率規則、地區限制、 重量限制等。適合確認特定配送方式的詳細條件。

【呼叫的 Shopline API】

• GET /v1/delivery_options/{delivery_option_id}

【回傳結構】 dict 含配送方式詳細欄位：id, name, delivery_type, enabled, price, weight_limit, regions, created_at 等。

取得指定配送方式的可用時段清單。

【用途】 查詢特定配送方式的預約時段設定，例如到府配送的時間選項。 適合確認預約配送時段或分析客戶配送時段偏好。

【呼叫的 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 等。

取得商店所有銷售渠道清單。

【用途】 查看商店目前開啟的銷售渠道，例如線上商店、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 等。

取得指定銷售渠道的詳細資訊。

【用途】 查詢單一銷售渠道的完整設定，包含渠道類型、狀態、 連結設定等。適合確認特定渠道的詳細配置。

注意：此端點在部分 token 權限下可能回傳 403 或 422。

【呼叫的 Shopline API】

• GET /v1/channels/{channel_id}

【回傳結構】 dict 含渠道詳細欄位：id, name, channel_type, enabled, created_at, updated_at 等。

取得商店應用程式設定。

【用途】 查詢商店層級的應用程式設定，包含功能開關、主題設定等。 適合確認商店目前的功能啟用狀態。

注意：此端點已被 Shopline 標記為 deprecated（已棄用）， 但仍可使用，涵蓋以求完整性。建議優先使用其他設定端點 取得最新商店資訊。

【呼叫的 Shopline API】

• GET /v1/settings/app

【回傳結構】 dict 含 settings，包含各應用程式層級設定欄位。 實際欄位依商店設定而定。

取得商店設定的稅率清單。

【用途】 查看商店目前設定的稅率規則，例如營業稅、消費稅等。 適合確認稅率設定或在財務分析時核對稅務規則。

【呼叫的 Shopline API】

• GET /v1/taxes

【回傳結構】 dict 含 total, taxes[]。 每個 tax 包含 id, name, rate, included_in_price, country, region, created_at 等。

取得指定員工的權限設定。

【用途】 查詢特定員工帳號在商店後台的存取權限範圍， 例如可操作的功能模組及操作層級。適合確認員工 權限配置或排查存取問題。

【呼叫的 Shopline API】

• GET /v1/staffs/{staff_id}/permissions

【回傳結構】 dict 含 staff_id, permissions[]。 每個 permission 包含 resource, actions 等， 描述該員工可操作的資源與動作。

取得目前 API Token 的資訊與授權範圍。

【用途】 查詢此 API Token 的詳細資訊，包含所屬商家、 授權的 scope（權限範圍）以及有效期限等。 適合排查 API 存取問題、確認 token 是否擁有 所需的操作權限。

【呼叫的 Shopline API】

• GET /v1/token/info

【回傳結構】 dict 含 token_info，包含 merchant_id, scopes[], expires_at, created_at 等欄位。

取得商店的代理人帳號清單。

【用途】 查看商店目前設定的代理人帳號，代理人通常用於 客服、業務等特定角色的操作授權。適合確認代理人 配置或了解有哪些外部帳號有商店操作權限。

【呼叫的 Shopline API】

• GET /v1/agents

【回傳結構】 dict 含 total, agents[]。 每個 agent 包含 id, name, email, role, enabled, created_at 等。

[WRITE] 建立新客戶。

【用途】 在 Shopline 商店中建立新的客戶記錄。適合客服手動建檔或批次匯入場景。

【呼叫的 Shopline API】

• POST /v1/customers

【回傳結構】 dict 含 success: bool, resource_id: str, message: str, customer: dict。

【副作用】

• 在商店客戶列表中新增一筆客戶

• 如果 email 或 phone 已存在，可能會失敗（Shopline 可能不允許重複）

[WRITE] 更新客戶基本資料。

【用途】 修改客戶姓名、聯絡方式、生日等基本資料。僅傳入要修改的欄位，未傳入的欄位不會被覆蓋。

【呼叫的 Shopline API】

• PUT /v1/customers/{customer_id}

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 修改客戶資料，變更立即生效

• 不可復原（無版本歷史），但可再次呼叫此工具覆蓋

[WRITE] 刪除客戶。

【用途】 從 Shopline 商店中刪除客戶記錄。通常用於清除測試資料或 GDPR 合規需求。

【呼叫的 Shopline API】

• DELETE /v1/customers/{customer_id}

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 永久刪除客戶記錄，不可復原

• 客戶相關的訂單紀錄可能仍保留（取決於 Shopline 實作）

[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] 調整客戶儲值金餘額。

【用途】 增加或扣除客戶儲值金，常用於儲值金充值、退款補償、活動贈送等場景。

【呼叫的 Shopline API】

• PUT /v1/customers/{customer_id}/store-credits

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 客戶儲值金餘額立即變動

• 異動紀錄會寫入客戶的儲值金歷史（可透過 get_customer_profile 查看）

• 扣除後如餘額不足，API 可能回傳錯誤

[WRITE] 調整客戶會員點數。

【用途】 增加或扣除客戶會員點數，常用於手動補點、活動贈點、客訴補償等場景。

【呼叫的 Shopline API】

• PUT /v1/customers/{customer_id}/member-points

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 客戶點數餘額立即變動

• 異動紀錄會寫入客戶的點數歷史（可透過 get_customer_profile 查看）

• 扣除後如點數不足，API 可能回傳錯誤

[WRITE] 取消訂單。

【用途】 取消指定訂單，適用於客戶要求取消、庫存不足或付款問題等場景。

【呼叫的 Shopline API】

• POST /v1/orders/{order_id}/cancel

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 訂單狀態變更為已取消，操作不可逆

• 若訂單已出貨，可能無法取消（取決於 Shopline 規則）

• 已付款訂單取消後需另行退款

[WRITE] 執行訂單出貨。

【用途】 將指定訂單標記為已出貨，觸發 Shopline 出貨流程，適用於倉庫確認出貨後的狀態更新。

【呼叫的 Shopline API】

• POST /v1/orders/{order_id}/shipment

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 訂單出貨狀態更新為已出貨

• 可能觸發客戶出貨通知（取決於商店設定）

• 訂單需處於可出貨狀態，否則 API 會回傳錯誤

[WRITE] 批次執行多訂單出貨。

【用途】 一次性將多筆訂單標記為已出貨，提升倉庫作業效率，適用於每日批量出貨場景。

【呼叫的 Shopline API】

• POST /v1/orders/shipment/bulk

【回傳結構】 dict 含 success: bool, resource_id: str, message: str, order_ids: list。

【副作用】

• 所有指定訂單的出貨狀態批次更新為已出貨

• 部分訂單若無法出貨，API 可能整批失敗或回傳各別結果（取決於 Shopline 實作）

• 可能觸發多封客戶出貨通知

[WRITE] 拆分訂單為多個子出貨單。

【用途】 將一筆訂單拆分為多個子單，適用於商品分批到貨或不同倉庫分開出貨的場景。 split_config 為字典，內容依 Shopline API 規格定義各子單。

【呼叫的 Shopline API】

• POST /v1/orders/{order_id}/split

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 原訂單被拆分為多個子訂單，原訂單狀態可能變更

• 操作通常不可逆，請確認拆單設定正確後再執行

• 已出貨的訂單無法拆單

[WRITE] 更新訂單欄位。

【用途】 修改訂單的可編輯欄位（如備註、配送地址等）。僅傳入要修改的欄位，未傳入欄位不受影響。

【呼叫的 Shopline API】

• PATCH /v1/orders/{order_id}

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 訂單資料立即變更，不可復原（可再次呼叫此工具覆蓋）

• 部分欄位（如金額）可能受限於訂單狀態而無法修改

[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] 設定訂單標籤（覆蓋現有標籤）。

【用途】 為訂單設定標籤，常用於訂單分類、優先處理標記、客服備註分群等場景。 注意：會覆蓋訂單現有的所有標籤。

【呼叫的 Shopline API】

• PATCH /v1/orders/{order_id}/tags

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 覆蓋訂單的所有現有標籤為新的標籤列表

• 若要新增標籤而非覆蓋，請先用 get_order_detail 取得現有標籤再合併

[WRITE] 建立新訂單。

【用途】 在 Shopline 商店中手動建立新訂單，適用於電話訂購、客服補單、線下訂單轉入等場景。 order_data 需包含 Shopline 建立訂單 API 所需的完整欄位。

【呼叫的 Shopline API】

• POST /v1/orders

【回傳結構】 dict 含 success: bool, resource_id: str, message: str, order: dict。

【副作用】

• 在商店訂單列表中新增一筆訂單

• 可能觸發庫存扣減（取決於訂單內容與商店設定）

• 可能觸發客戶訂單確認通知（取決於商店設定）

• 建立後訂單立即生效，需確認資料正確再執行

[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] 更新商品基本資料。

【用途】 修改現有商品的名稱、描述、分類、狀態等欄位。僅傳入要修改的欄位， 未傳入的欄位不會被覆蓋。

【呼叫的 Shopline API】

• PUT /v1/products/{product_id}

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 商品資料變更立即生效，前台同步更新

• 不可復原（無版本歷史），但可再次呼叫此工具覆蓋

[WRITE] 刪除商品。

【用途】 從 Shopline 商店中永久刪除商品記錄。通常用於清除下架商品或測試資料。

【呼叫的 Shopline API】

• DELETE /v1/products/{product_id}

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 永久刪除商品，不可復原

• 商品相關的訂單行項目記錄可能仍保留（取決於 Shopline 實作）

• 刪除後前台立即下架

[WRITE] 更新商品庫存數量（無變體商品）。

【用途】 直接設定無變體商品的庫存數量。適用於盤點後調整庫存或手動補貨場景。 若商品有變體，請改用 update_variation_quantity。

【呼叫的 Shopline API】

• PUT /v1/products/{product_id}/quantity

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 庫存數量立即更新，影響前台可購買數量

• 若設為 0 且商品設定不允許超賣，前台將顯示缺貨

[WRITE] 更新商品售價（無變體商品）。

【用途】 直接設定無變體商品的售價。適用於調價、促銷結束恢復原價等場景。 若商品有變體，請改用 update_variation_price。

【呼叫的 Shopline API】

• PUT /v1/products/{product_id}/price

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 售價立即更新，前台同步顯示新價格

• 不影響進行中的訂單（訂單成立時已鎖定價格）

[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] 更新商品變體資料。

【用途】 修改特定商品變體的 SKU、規格選項、狀態等欄位。僅傳入要修改的欄位， 未傳入的欄位不會被覆蓋。

【呼叫的 Shopline API】

• PUT /v1/products/{product_id}/variations/{variation_id}

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 變體資料變更立即生效，前台同步更新

• 不可復原（無版本歷史），但可再次呼叫此工具覆蓋

[WRITE] 刪除商品變體。

【用途】 從商品中永久刪除指定的規格變體。適用於停售特定規格或清理錯誤變體。

【呼叫的 Shopline API】

• DELETE /v1/products/{product_id}/variations/{variation_id}

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 永久刪除變體，不可復原

• 若該變體為商品唯一變體，刪除後商品可能無法購買

• 刪除後前台立即移除該規格選項

[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] 更新商品變體售價。

【用途】 直接設定特定變體的售價。適用於個別規格調價、限時特價等場景。

【呼叫的 Shopline API】

• PUT /v1/products/{product_id}/variations/{variation_id}/price

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 售價立即更新，前台同步顯示新價格

• 不影響進行中的訂單（訂單成立時已鎖定價格）

[WRITE] 設定商品標籤（覆蓋現有標籤）。

【用途】 為商品設定標籤，常用於商品分群、促銷標記、SEO 分類等。 注意：此操作會覆蓋商品現有的所有標籤。

【呼叫的 Shopline API】

• POST /v1/products/{product_id}/tags

【回傳結構】 dict 含 success: bool, resource_id: str, message: str。

【副作用】

• 覆蓋商品的所有現有標籤為新的標籤列表

• 若要新增標籤而非覆蓋，請先用 get_product_list 取得現有標籤再合併後傳入